## Value Types

Expressions use the following value types.

### Field

A field is a integer value. The meaning will depend upon the context. It can represent an individual element for a date of any given calendar scheme. If the scheme is the Julian Day Number (jdn), then it represents a single day in the time continuum. It may also be used as a number without reference to any calendar.

A field may hold one of the following special values.

Keyword | Meaning |
---|---|

past | The earliest possible day that can be represented. |

future | The last possible day that can be represented. |

today |
The current day number (jdn) according to the underling operating system. The value is substituted when the keyword is first encountered. |

? | An unknown or indeterminate value. |

### Range

A range is expressed as two field values which denote the first and last values of an inclusive, continuous list. Both values may be the same, which implies a list of one value. A range is written using the '~' operator. (a ~ b) is identical to (b ~ a). When a range is output as a string, it is always written with the lower value first.

The 'past' and 'future' values are permitted in a range but not the '?' value.

A field may be promoted to a range with the upper and lower values the same.

A range may only be demoted to a field if both upper and lower values are the same.

### Rlist

An rlist is a list of ranges. The list may contain zero or more ranges. If the rlist has more than one range, it is written using the '|' union operator. When an rlist is output, it is always written as a well ordered list.

A range may be promoted to an rlist with a single range.

An rlist may only be demoted to a range if, after conversion to a well ordered list, it contains a single range.

### Record

This part of the specification is still under development.

A record is a specialist type to represent the separate fields of a particular calendar scheme. The scheme must be defined before the record can be used. The format of the record type is '{"sig", field_1, field_2, field_3}' where 'sig' is the scheme code and the field values are in record-default order. If not all field values are given, the '?' value is assumed for those missing. If the scheme code is missing, the default input scheme is assumed.

### String

A string is sequence of unicode (UTF-8) characters. It is written by enclosing the text in double quotes '"'. If a double quote is required in the text, use two double quotes together. For example, the value "Say ""Hello""" would print as Say "Hello".

### Boolean

A boolean value holds one of the two keywords 'true' or 'false'.

### Error

An error value is created whenever an operation is carried which has undefined results. When written out, the value should print text that describes where and why the error was created.

### Date

A date type is not a separate type but a convenient way to refer to one of the three ways of holding a date, a field, a range or an rlist. A date value can promote or demote a value between these types as required. An error should only occur if a demotion is required but the value is such that it can not take place.

A date type strongly implies that the values are julian day numbers.

### Number

A number type is similar to a date type, but there is no implied promotion or demotion. Not all the field, range or rlist types may be valid in any given context.

## Names

Any text in the script which is not an operator, literal or keyword is termed a 'name'. How a name is treated depends upon the context, as detailed below.

Names are constructed from alphanumeric, '_' underline, ':' colon and '.' dot characters. They can not start with a numeric or dot character.

In some cases the script may accept either a name or a literal string.

### Variables

Variables are created using the 'let' statement. They link a name to a value. Once created the 'let' statement name is optional as any known variable name (other than a statement name) is treated as a let statement.

The life of a variable is controlled by the 'mark' and 'clear' statements. It should be noted that unless directed otherwise, the variable names and values are remembered after a script has finished running. So subsequent scripts can use values calculated by previous ones.

### Entity Codes

The vocab, grammar, scheme and format entities are identified by (normally short) codes. These codes are written as names or literal strings. The characters used in the codes can be any UTF-8 character except the ':' and '#' characters. (Note, other restrictions may be included in future versions.) If the code uses characters not permitted in a name, then it must be written as a literal string.

### Signatures

A Signature is the scheme and/or the format codes to be used when converting between different value types.

Signature | Example |
---|---|

scheme | write string,j today; |

scheme:format | write string,"g:dmy+" today; |

:format | write string,:iso today; |

## Operators

### Arithmetic Operations

Operator | Name | Use | Result |
---|---|---|---|

- | Unary minus | - number_type | number_type |

+ | Plus | number_type + number_type | number_type |

- | Minus | number_type - number_type | number_type |

* | Multiply | field_type * field_type | field_type |

/ | Divide | field_type / field_type | field_type |

mod | Modulo | field_type mod field_type | field_type |

For field values, the arithmetic operators '+' (addition), '-' (subtraction, negation) and '*' (multiplication) retain their normal mathematical meanings, division '/' and 'mod' provides integer division and modulus (remainder). Note that the modulo operator always returns a positive value and that if q = a / b and r = a mod b then a = b * q + r.

#### Unary Minus

Unary minus has normal meaning of negation. The special field values are negated as follows,

-past = future

-future = past

-? = ?

Negation of a range negates both limits, so -(a ~ b) = (-b ~ -a).

Negation of an rlist negates all the ranges, but retains the well orderedness,

so -(a ~ b | c ~ d) = (-d ~ -c | -b ~ -a).

#### Addition and Subtraction

Normal addition is applied when both sides of an expression are field values. If one side of an expression is a range then the field value is added to both limits of the range. If both sides of an expression are ranges, then both the lower limits and the upper limits are added together. If one side of an expression is a rlist, then the other side is added to each range in turn. Adding two rlists together is currently an error.

Subtraction is carried out by adding the negated right hand side. So a - b = a + -b and (a ~ b) - (c ~ d) = (a ~ b) + (-d ~ -c).

Expression | Example | Result |
---|---|---|

field_type + field_type | 5 + 10 past + 123 past + future | 15 past Error |

range_type + field_type field_type + range_type |
(8 ~ 16) + 20 250 + (500 ~ future) past + (500 ~ future) |
28 ~ 36 750 ~ future Error |

range_type + range_type | (8 ~ 16) + (10 ~ 20) | 18 ~ 36 |

rlist_type + field_type field_type + rlist_type |
(8 ~ 16 | 20 ~ 50) + 20 250 + (past ~ 90 | 500 ~ future) |
28 ~ 36 | 40 ~ 70 past ~ 340 | 750 ~ future |

rlist_type + range_type range_type + rlist_type |
(8 ~ 16 | 20 ~ 50) + (10 ~ 20) (10 ~ 25) + (past ~ 9 | 50 ~ future) |
18 ~ 36 | 30 ~ 70 past ~ 34 | 60 ~ future |

rlist_type + rlist_type | (8 ~ 16 | 20 ~ 50) + (15 ~ 18 | 25 ~ 27) | Error. Unable to add or subtract rlists. |

#### String Concatenation

The '+' operator is also used to combine string values. If both sides of the operator are string values, the right hand side will be appended to the left hand. If just one side is a string value then the other is stringified first (see write Statement).

#### Multiplication, Division and Modulo

Currently, these operators can only be used with field types. The division and modulus operators are based on Euclidean integer division.

Multiplication of any number with the ? value is an error.

Multiplication of any number with past (except ? and future) results in past.

Multiplication of any number with future (except ? and past) results in future.

Multiplication of past and future values is an error.

For the division operator, the following conditions apply.

The divisor must be a non-zero integer value. Using the values 0, ?, past or future results in an error.

If the dividend is past and the divisor valid, the result is also past.

If the dividend is future and the divisor valid, the result is also future.

Division of the ? value results in an error.

For the modulo operator, the following conditions apply.

Use of ?, past or future on either side the operation results in an error.

Using zero on the right hand side of the operation results in an error.

Expression | Example | Result |
---|---|---|

field_type * field_type | 5 * 10 past * 123 past * future |
50 past Error |

field_type / field_type | 10 / 5 past / 123 123 / future |
2 past Error |

field_type mod field_type |
21 mod 5-100 mod -6past mod 2 |
1 2 Error |

### Range Operator

The binary range operator creates a range value which is just large enough to include
both its operands.

The order of the operands is not significant.

The operands can be either field or range types.

The values past and future may be used.

Use of the ? value is an error.

Example | Result |
---|---|

5 ~ 10 | 5 ~ 10 |

123 ~ past | past ~ 123 |

? ~ 40 | Error |

(5 ~ 10) ~ 6 | 5 ~ 10 |

(5 ~ 10) ~ (15 ~ 8) | 5 ~ 15 |

48 ~ 25 ~ 5 ~ 10 | 5 ~ 48 |

### Set Operators

The Complement '!' is a unary prefix operator which operates on a rlist. The Union '|', Intersection '&', Symmetric difference '^' and Relative complement '\' operators are binary. These operate on an rlist on left hand side and a range on right hand side. If necessary, range and field types are be promoted to an rlist or range.

Details of the set operators are found here.

### Comparison Operators

The comparison operators must have operands of the same type, after type allowing for type promotion. The output is always a boolean type.

Any types, other than error types, can be compared for equality or non-equality.

Comparison operators that compare magnitude can only be used with field or string types. Use with any other type results in an error.

### Boolean Operators

The unary prefix operator 'not' and the binary operators 'and' and 'or' can be used with boolean types only. Any other type will produce an error.

### Subscript operators

The subscript operators allow access to to the various parts of the more complex value types.

#### Index operator

Used in the form **Value[ Index ]**,
the square brackets are used to enclose an index into left hand value.

If the value is a rlist type and the index a number (field), then the result is the range pointed to by the (zero based) index.

If the value is a record type and the index a number (field),
then the result is the field pointed to by the (zero based) index.

If the index is a name or string value then this is treated as a field name,
and the result is the corresponding value of the field.

If the value is a field, then it is assumed to be a date jdn. The index must be a name or string signature corresponding to a scheme and field name. If the scheme is not given, the default input scheme will be used. The result is the field value.

Note, the field names used may be the default record or the alias field name.

Example | Result |
---|---|

(8~16|20~50|75~99)[1] | 20 ~ 50 |

{g,1948,9,19}[0] | 1948 |

{g,1948,9,19,?}[wday] | ? |

2432814[g:wday] | 7 |

let i="g:Month"; 2432814[(i)] | 9 |

#### Property operator

A subscript starting with a dot '.' and followed by a name will return a property of the value, as listed below.

Property | Use | Result | Comment |
---|---|---|---|

low | (7~16)[.low] | 7 | Return the lower bound of a range or rlist. |

high | (7~16)[.high] | 16 | Return the upper bound of a range or rlist. |

span | (7~16)[.span] | 10 | Return the inclusive count between upper and lower bounds of a range or rlist. |

span | (21|79~88|100~120|200~210)[.span] | 190 | |

size | (21|79~88|100~120|200~210)[.size] | 4 | Return the number of elements in a rlist or record. |

size | {g,1948,9,19}[.size] | 3 | |

envelope | (21|79~88|100~120|200~210)[.envelope] | 21 ~ 210 | Return the enclosing range af an rlist. |

scheme | {g,1948,9,19}[.scheme] | "g" | Return the scheme code string of a record. |

type | 2432814[.type] | "field" | Return the type of value as a string. |

The [.type] property returns one of the following strings: "field", "range", "rlist", "string", "record", "bool", "null". Since if the value is an error, the error will be propagated and so will not be detected.

### Functions

A function first has to be defined using the function statement. It can then be called directly using the call statement, but in this case the function result (if one is assigned) is ignored. It can also be called in an expression using the at '@' operator.

Example | Result |
---|---|

function power(number, power) { result = 1; do while power > 0 result *= number; power -= 1; loop } | |

4 * @power(2,4) + 10 | 74 |

### Type Conversions

The cast operators are used to covert values between different types. If additional information is required (such as scheme and/or format) then a comma and signature can be added to the cast. If it is omitted, the system wide default values are assumed.

#### Date Cast

A date, in this context, means a rlist or an well ordered list of ranges. As well as an rlist, a date may be encapsulated as a text string or a record type. The date cast puts these two record types into a consistent rlist type. The rlist will then be demoted to a range or field if appropriate.

If the original type is a string, then the cast operation will need to know the scheme and format to be used, and so a signature can be added or else the system output default settings are used. Note the a string description of an rlist may include embedded range and union symbols, but this is different from a HistoryCal Date Expression. One significant difference is that only one scheme format can be used for the conversion.

Example | Result |
---|---|

date "19sep1948" | 2432814 |

date "1940~1950|1945~1955" | 2429630 ~ 2435473 |

date,g:iso "[1940..1950,1945..1955]" | 2429630 ~ 2435473 |

date {g, 1948, 9, 19} | 2432814 |

date {g, 1948} | 2432552 ~ 2432917 |

The above examples assume a system input setting of "g:dmy". |

#### String Cast

The string cast operator converts a field, range, rlist or record type into a string type.

Except for a record type, the scheme code signature must be provided. If the format code is not included in the signature, then the default for that scheme is used.

Example | Result |
---|---|

string,"g:dmy+" 2432814 | "19 September 1948" |

string,g 2429630~2435473 | "1940 ~ 1955" |

string,g:iso 2429630 ~ 2429995 | 2433283 ~ 2435473 | "[1940,1950..1955]" |

string {g, 1948, 9, 19} | "19 Sep 1948" |

string {j, 1948} | "1948" |

The above examples assume a system output setting of "g:dmy". |

#### Record Cast

The record cast operator converts a field (as a julian day number) or string type into a record type. At this time, using the record cast with a range or rlist type is an error.

If a scheme:format signature is not given, then to cast a field the output default setting is used, whereas if casting a string, the input default is used.

Note that a record created from a cast always has all the fields included, even the optional ones. Only main fields are given values though. Records created using the record operator '{}' only include the given fields, even if this does not fully qualify a date.

Example | Result |
---|---|

record,g:dmy "19sep1948" | {"g", 1948, 9, 19, ?} |

record "21??" | {"g", ?, ?, 21, ?} |

record,:u "1948Year 9Month 19Day" | {"g", 1948, 9, 19, ?} |

record,j 2432814 | {"j", 1948, 9, 6, ?} |

record 2429630~2435473 | Error |

The above examples assume a system input and output setting of "g:dmy". |

#### Error Cast

The error cast operator converts a string into an error. This can be used to signal an unusable value in a calculation or function.

The prefix "Error (" + line + "): " is added to message, where line is the line number of the the error cast operator.

Example | Result |
---|---|

error "Age is negative." | "Error (10): Age is negative." |

error ("Age of " + age + " is too high.") | "Error (10): Age of 150 is too high." |

## Operator Precedence

Expressions are evaluated according to the operators detailed in the table. Operators with higher precedence are listed first. When precedence is equal, operations are carried out from left to right.

Operator List | |||
---|---|---|---|

Operator | Name | Use | Result |

() | Parenthesized expression | ( expr ) | value |

{} | Record | {sig,field_value,...} | record_value |

! | Complement | !rlist_value | rlist_value |

not | Logical not | not bool_value | bool_value |

- | Unary minus | -number_value | number_value |

date | Date cast | date,sig string_valuedate record_value | date_value |

record | Record cast | record,sig string_valuerecord field_value | record_value |

string | String cast | string,sig date_valuestring,sig record_value | string_value |

error | Error cast | error string_value | error_value |

@ | Function | @name@name(expr, ...) | value |

[] | Subscript | date_value[string_value] | field_value |

[.name] | Property | value[.name] | value |

* | Multiply | field_value * field_value | field_value |

/ | Divide | field_value / field_value | field_value |

mod | Modulo | field_value mod field_value | field_value |

+ | Plus | number_value + number_valuestring_value + valuevalue + string_value |
number_value string_value string_value |

- | Minus | number_value - number_value | number_value |

~ | Range | field_value ~ field_valuerange_value ~ range_value |
range_value range_value |

| | Union | rlist_value | range_value | rlist_value |

& | Intersection | rlist_value & range_value | rlist_value |

^ | Symmetric difference | rlist_value ^ range_value | rlist_value |

\ | Relative complement | rlist_value \ range_value | rlist_value |

< | Less than | value < value | bool_value |

<= | Less than or equal | value <= value | bool_value |

> | Greater than | value > value | bool_value |

>= | Greater than or equal | value >= value | bool_value |

= | Equal | value = value | bool_value |

<> | Not equal | value <> value | bool_value |

and | Logical and | bool_value and bool_value | bool_value |

or | Logical inclusive or | bool_value or bool_value | bool_value |

## Keywords

The following is a complete list of keywords. These words cannot be used as variable names and, if used as signature codes, they must be enclosed in double quotes.

**and, date, do, endif, else, elseif, error, false, future, if, invalid, loop, mod,
not, or, past, record, string, today, true, until, while**

The other statement words
**call, clear, end, format, function, grammar, let, mark, scheme, set, vocab, write, writeln**
are not strictly keyword, but must be used with care.
If they are used as variable names then all assignments must start with 'let'.