#
# Copyright (C) 1999-2014. Christian Heller.
#
# This file lists arguments for certain design decisions.
# Its content may later be moved into the cyboi book
# or a cyboi FAQ on the website.
#
# Cybernetics Oriented Programming (CYBOP) <http://www.cybop.org/>
# CYBOP Developers <cybop-developers@nongnu.org>
#
# @version CYBOP 0.16.0 2014-03-31
# @author Christian Heller <christian.heller@tuxtax.de>
#

Design Decisions
================

Arithmetic Operands
___________________

Question:
Is it possible to combine operands of type "integer" and "double" for an arithmetic operation?

Example:
    <!-- This example cuts off decimal places of the resulting number, since integer is used as type. -->
    <part name="divide" channel="inline" encoding="utf-8" language="text/cybol" format="calculate/divide" model="">
        <property name="result" channel="inline" encoding="utf-8" language="text/cybol" format="path/knowledge" model=".result"/>
        <property name="operand" channel="inline" encoding="utf-8" language="text/cybol" format="number/integer" model="2"/>
        <property name="type" channel="inline" encoding="utf-8" language="text/cybol" format="meta/type" model="number/integer"/>
    </part>

Answer:
It is NOT possible.
- cyboi uses void* types only for passing parametres around
- a type cast is done before executing an arithmetic operation
- the type could theoretically be read from each argument
- however, both arguments might have different types so that
  cyboi could not decide which operation to use and how to cast
- once, the result might be a double and the operand an integer,
  another time the other way around
- in the end it is the responsibility of the CYBOL developer
  to decide if he wants to work with integer or double values
- a combination of both worlds is not possible, nor necessary
- if needed, there is always the "cast/" operations in cybol

HTML Formatting
_______________

- a cybol constraint "indentation" of type "logicvalue/boolean"
  may be handed over to send/serialise operations that indicates
  whether or not generated html should be formatted
- a formatted file (indented and using more line breaks) is
  approximately three times as big as a "condensed" (non-formatted) one

- if formatting (pretty printing) is wanted, then pre-formatted tags
  might get indented, even though this is not wanted
- therefore, a cybol property "preformatted" of type "logicvalue/boolean"
  may be specified for each html node
- it is excluded from generated html attributes
- actually, it is not a good idea to give format-related properties
  on structure-related tags
- however, THIS IS THE BEST CHOICE, since no-break spaces also have
  to be specified directly
- one functioning alternative would be to filter for <pre> tags
- the problem is that nowadays, preformatting is mostly done via css
  classes whose name may vary, so that they cannot be filtered

Accessing Array Elements
________________________

The following is NOT necessary, since indices may be given to operations like "overwrite" or "add"
* Find solution for accessing single elements of an array from within cybol
--> possibly use "overwrite" operation and specify index as property
--> using a special knowledge path syntax like .settings.buffer[0] is probably NOT possible,
since a knowledge part (and not integer or character value etc.) is to be returned

Question:
Should the knowledge path be extended for accessing single array elements?

Example:
.variables.buffer[0]

Answer:
No, for two reasons.
a) The knowledge path always returns a part, never a primitive like integer etc.
b) The "modify/overwrite" operation has "index" properties, so that
   single elements of an array may be accessed.

Multiple Formats
________________

Question:
Should multiple formats (types) be allowed?
- separated by a pipe character
- as value of the "format" CYBOL attribute
- to be processed in this order, one-by-one in CYBOI

Example:
format="text/plain|UTF-8|tar|gzip"

Answer:
This is NOT necessary.
- there is a "format" attribute in CYBOL, e.g. number/fraction-vulgar
- there is an additional "language" attribute, e.g. text/html
- multiple translations can be handled as separate operations,
  by assigning the result of one translation to a tree node
  which serves as input to another operation
- similar to pipelining in UNIX

Sensing Thread Interruption
___________________________

Question:
Stop sensing thread while data detection irq is set?
- seems better than "busy waiting" (sleep loop)
- might relax the cpu
- sensing might continue if irq has been processed and reset
- how to continue a thread?

Example:
- see function "sense_terminal"

Answer:
NO for now.
- interrupting and creating threads eats performance
- a new sensing thread would have to be created every some miliseconds
- is whole process context (memory?) copied for each new thread?
- probably causes more effort than busy waiting

Date Time
_________

There are dozens of calendars, historic and in use.
Most of them are based on the position of the sun or/and moon,
others on an era/epoch in which a certain king was ruling.
Neither CYBOI, nor any other system can support them all
with 100 % accuracy, since some epochs of kings can only
be estimated.
Decision: CYBOI will only support the most important calendars.

The modern calendar is the "Gregorian Calendar",
introduced by pope Gregor in the 16th century (1582-10-15).
Decision: Therefore, CYBOI has to offer this date representation.

Another often used calendar is the "Julian Calendar",
introduced by Julius Caesar around 40 B. C.
It was valid until the Gregorian Calendar was introduced.
Decision: CYBOI should additionally support also this date representation.

For computing and many sciences like astronomy etc. it is useful
to have a CONTINUOUS COUNTING of time. This is not the case
with calendars, since they use "leap days" and have inconsistencies,
e.g. the two weeks left out when the Julian was switched to
the Gregorian calendar.
Therefore, a so-called "Julian Day Number" (JDN) exists, which is
something different than the "Julian Calendar". It is the continuous
count of days since the beginning of the Julian Period, starting at
noon on January 1, 4713 BC proleptic Julian calendar, which is
equal to November 24, 4714 BC, in the proleptic Gregorian calendar.
The "Julian Date" (JD) of any instant is the Julian day number for
the preceding noon plus the fraction of the day since that instant.
Julian Dates are expressed as a Julian day number with a decimal
fraction added. For example, The Julian Date for 00:30:00.0
January 1, 2013 is 2456293.520833.
Decision: CYBOI does NOT use the Julian Date, since it is to be
represented as floating point number, which is not very efficient.

Another option is to use a single signed integer number which
increments every second.
This is done so in Unix-like and many other operating systems and
file formats and called "Unix time", or "POSIX time".
It is defined as the number of seconds that have elapsed since
00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970,
NOT counting leap seconds.
Modern Unix time is based on UTC, which counts time using SI seconds,
and breaks up the span of time into days almost always 86400 seconds
long, but due to "leap seconds" occasionally 86401 seconds.
This extra second keeps the days synchronized with the rotation
of the Earth, per Universal Time.
Due to its handling of leap seconds, it is NEITHER a linear
representation of time NOR a true representation of UTC.
When a leap second occurs, so that the UTC day is not exactly
86400 seconds long, a DISCONTINUITY occurs in the Unix time number.
When a leap second is inserted, the Unix time number increases
continuously during the leap second, and then jumps back by 1
at the end of the leap second. This leads to ambiguous Unix
time numbers that can refer either to the instant in the middle
of a leap second, or to the instant one second later.
Decision: CYBOI will use a signed integer number.

Generally, it is necessary to decide whether a time scale is counting:
1 calendar days:
- measurand: time-of-day [mean solar second]
- count of mean solar seconds (which are subdivisions of calendar days)
- determined by astronomy
- example: Julian Date (JD), Coordinated Universal Time (UTC)
- application: civil purposes, modern calendars, most legal systems of time
2 SI seconds:
- measurand: elapsed time interval [SI second]
- following atomic seconds (which are unrelated to calendar days)
- calendar becomes influenceable by politics
- example: Temps Atomique International (TAI)
- application: modern telecommunication, navigation systems
3 other effects:
- just recently, it was found that TAI is not quite accurate
- it was proposed by astronomers to observe effects of pulsars (stars)

UTC is a combination of the first two incommensurate concepts.
It only works fine through the concept of occasional "leap seconds".

Also POSIX tries to be both and as a result it cannot address leap
seconds meaningfully. The Realtime and Advanced Realtime extensions
to POSIX now offer two separate clocks:
http://pubs.opengroup.org/onlinepubs/007904975/basedefs/time.h.html

Decision: CYBOI will use TWO TIMES (separate clocks) internally.

A "leap second" as well as "daylight/summer time" are decisions
by some humans to reset all of the clocks to comply with changes.
These two kinds of clock resets are extremely similar, and the
zoneinfo (or tz library) files and POSIX rules already have the
mechanisms for handling both. It now consists of two separate databases:

1 posix: considers a Unix time_t value to be equivalent to the number
of mean solar seconds since 1970-01-01; since 1972-01-01 its value
matches UTC except during leap seconds; every day has 86400 seconds;
for correct time this requires that the system clock be retarded or
reset backward at each leap second; this is the default provided
with most Unix systems, and it is most consistent with POSIX

2 right: considers a Unix time_t value to be equivalent to the count
of seconds actually broadcast in radio time signals since 1970-01-01;
it requires a file of leap seconds to be updated whenever a new one
occurs; for correct time this requires that the system clock
increment monotonically using TAI seconds; despite its name, this is
generally regarded as experimental and inconsistent with POSIX;
this was the branch of code which was briefly used by default in 4.4BSD Unix

There are two time scales which can reasonably be extrapolated back to 1601:
- Universal Time (UT): mean solar second
- Terrestrial Time (TT): SI second

However, UT in all its forms (including GMT) is actually a measure of
time-of-day, which is really the earth rotation angle, and should not
be used anymore, possibly for calculating historic dates, as an exception.

See:
http://en.wikipedia.org/wiki/Unix_Time
http://www.ucolick.org/~sla/leapsecs/timescales.html

Decision: CYBOI will use internal "zoneinfo" maps with information
similar to the "zoneinfo" (or tz library) database files in Unix.
UTC will be treated as timezone distinct from the underlying
operating system time, based on the broadcast time signals.
The only frequent change needed is to place the leap second
information into the internal "zoneinfo" maps, just like timezones.
That way, CYBOI will remain flexible even if broadcast time signals
abandon leap seconds and are based on atomic time only.

The relevant pieces of the POSIX 2008 specification are the definition
of tzset(), and the definition of environment variable TZ.
The only change needed in the POSIX spec is to substitute the
new name of an internationally-approved, uniformly-incrementing,
atomically-regulated broadcast time scale (e.g., "TI", as the
2003 Colloquium in Torino suggested) in place of the current "UTC".
This would allow the underlying system time to increment uniformly while
also allowing the time presented to humans to keep pace with the sun.
It would remove the need for the kernel to handle leap seconds.
It would remove the need for other coding hacks and code complexity
which try to work around the non-uniform timing hiccup which POSIX
compliance currently demands.

See:
http://pubs.opengroup.org/onlinepubs/007904975/basedefs/time.h.html
http://www.ucolick.org/~sla/leapsecs/right+gps.html

Decision: CYBOI will use International Time (TI) in the future,
which is likely to start in year 2022.
It is a candidate for radio broadcast time signals.
TI would be a purely atomic time scale offset from Temps Atomique
International (TAI) by a fixed integer number of seconds.
In order to avoid discontinuities for systems using radio
broadcast time signals the offset would be equal to the
offset of UTC at the instant of switching from UTC to TI.

Conversion:

http://www.astro-toolbox.com/
Julian Day --> any other: http://www.fourmilab.ch/documents/calendar/
TAI --> TT: http://cr.yp.to/libtai/tai64.html
Gregorian --> Julian Calendar: http://www.scribd.com/doc/28678552/Astronomische-Berechnungen
http://www.ortelius.de/kalender/calc_de.php

Definition:

http://de.wikipedia.org/wiki/Julianisches_Datum
http://de.wikipedia.org/wiki/Umrechnung_zwischen_Julianischem_Datum_und_Gregorianischem_Kalender
http://www.fourmilab.ch/documents/calendar/
https://en.wikipedia.org/wiki/System_time

Links:

http://de.wikibooks.org/wiki/Astronomische_Berechnungen_f%C3%BCr_Amateure/_Druckversion
http://de.wikipedia.org/wiki/Zeitrechnung
http://de.wikipedia.org/wiki/Proleptisch
http://de.wikipedia.org/wiki/Jahr_Null
http://docs.oracle.com/javase/1.5.0/docs/api/java/util/GregorianCalendar.html
http://de.wikipedia.org/wiki/Datumsformat
http://de.wikipedia.org/wiki/ISO_8601
http://de.wikipedia.org/wiki/Uhrzeit

Timezone database (tz, zoneinfo):

http://www.twinsun.com/tz/tz-link.htm
