Under Construction
Statement: format
The format statement is used to control the conversion of text to date (the Julian Day Number) and visa versa. It is both a statement and a grammar-statement. When used as a statement, it is possible to add formats to existing grammars - including the default schemes' grammars.
| format Statement | ||
|---|---|---|
| Format | Example | Output |
|
format gcode:fcode { format-statements } |
format j:LONG { output "On the (Day::os) Day of |(Month:m) |in the (Year::os) Year"; } ... write string.g:LONG 2432814; | On the 19th Day of September in the 1948th Year |
| format gcode:fcode format-string; | format g:MYD "(Month:m:a) |(Year)|, (Day)"; ... write date.g:MYD "Sep1948 19" + "; " + string.g:MYD 2432814 | 2432814; Sep 1948, 19 |
|
grammar gcode { grammar-statements format fcode { format-statements } } |
grammar XG { inherit j; format dXmy { output "(Day) |(Month::rn) |(Year)"; } } scheme XS { base gregorian; grammar XG; } ... write string.XS:dXmy 2432814; | 19 IX 1948 |
There are two aspects to the formatting of dates, firstly, interpreting the input from a user or application and secondly, creating the output to write a date in a particular way. If the text from the output can be fed directly back to the input, and the result remain unchanged, then the format is said to be reversible. The format statement is designed to handle both reversible and non-reversible text.
A format within a particular grammar is given a unique code by which it can be referred to. If a grammar inherits another, it may replace one of its inherited formats by reusing the same name.
If the format is being declared outside of a grammar statement, the code is a compound code including both the grammar and its name within that grammar, the parts separated by a colon ':' character.
Format Sub-Statement: rules
The conversion between date and text is controlled by the rules statement. Currently there are three rules available, as shown below.
| rules Statements | |
|---|---|
| Statement | Use |
| rules text | Use a text string to define the date. The default value. |
| rules units | Use value, unit pairs to define the date, or date elements. |
| rules iso8601 | Use the ISO 8601 standard to define a Gregorian date. |
Format Sub-Statement: rules units
A units format is one where a date (or parts of a date) is written as a sequence of value, unit pairs. Since the pair is self contained, they may be placed in any order.
The unit name can be any field name from the schemes record, and the value will be placed into that field. The field name can be replaced with an alias provided by the owning grammar, either the alias unit or the alias field sub-statements.
A units format may be created automatically using the "u" fcode (format code). This can be used as follows.
| Example | Result |
|---|---|
| date.g:u "9month1948year19day" | 2432814 |
| date.g:u "1948y 19d 9m" | 2432814 |
| record.g:u "9 Month" | {"g", ?, 9, ?, ?} |
| string.g:u 2432814 | "1948y 9m 19d" |
Note, this aspect of the language is still being actively developed. Since the units format has no options (at present) and can be created for any scheme using the "u" format code, there is no need to explicitly use it. It is included for completeness and future development only.
Format Sub-Statement: rules iso8601
Although it is possible to input and output dates conforming to the common parts of the ISO 8601 standard, full implementation requires its own format sub-system. This is achieved with the rules iso8601 sub-statement. This method can only be used with the Gregorian calendar schemes.
Various optional parts of the standard can be activated using a number of switches following the rules sub-statement. these can be broken down into a number of groups as follows.
| Switches used with rules iso8601 Sub-Statement | ||||
|---|---|---|---|---|
| Group | Switch | Description | Example | Output |
| Style | caldate | Dates are treated as Gregorian Year, Month and Day of month. Default | rules iso8601 caldate; | 1948-09-19 |
| week | Dates are output as Year, Week number and Day of week. | rules iso8601 week; | 1948-W38-7 | |
| ordinal | Dates are output as Year and Day of year. | rules iso8601 ordinal; | 1948-263 | |
| Extended | extended | Dates are output with '-' (hyphen) separators between the elements. Default | rules iso8601 extended; | 1948-09-19 |
| basic | Dates are output without any separators between the elements. | rules iso8601 basic; | 19480919 | |
| Expanded Year | year4 | Year is input and output as 4 positive digits without a leading '+'. Default | rules iso8601 year; | 1948-09-19 |
| year5 | Year are input and output as 5 digits with a leading '+' or '-'. | rules iso8601 year5; | +01948-09-19 | |
| year6 | Year are input and output as 6 digits with a leading '+' or '-'. | rules iso8601 year6; | +001948-09-19 | |
| Sign Prefix | nosign | Year is positive without a leading '+'. Default | rules iso8601 nosign; | 1948-09-19 |
| minus | Negative years have a leading '-'. | rules iso8601 minus; | 1948-09-19 | |
| sign | Year has a leading '+' or '-'. | rules iso8601 sign; | +1948-09-19 | |
| Date Set | dateset | Date is output as a Set of Ranges | rules iso8601 dateset; | [1948-09-19] |
The switches for each group may be mixed and matched as required. The order of the switches is not significant, except if rules are contradictory then the value to the right has precedence.
Format Sub-Statement: rules text
The text format rule uses a format string to control the order and style of the text being read or written. Since this is the default rule, there is no need to explicitly state it.
| Format Sub-Statements used with rules text | ||
|---|---|---|
| Statement | Example | Note |
| inout format-string; | inout "(Day) |(Month:m:a) |(Year)"; | Format string used for both input and output. |
| input format-string; | input "(Day) |(Month) |(Year)"; | Format string used for just input. |
| output format-string; | output "(CompDay:frcomp) |(NMDay) |(NMonth:frm) |(Year)"; | Format string used for just output. |
| separators string-expr; | separators "-"; | Characters to be used to separate date elements. Default is ":,". |
| rank string-list; | rank "ce", "ceyear", "month", "day"; | Set the significance order for input and output fields. |
| rankout string-list; | rankout year, nmonth, nmday, cday; | Set the significance order for output fields only. |
| style switch; | style hide; | Set the style for the format. |
The format definition must contain either the
inout or,
one or both of the input and output sub-statements.
All these statements use the format-string to describe
how text is to be interpreted as a date
and/or how a date is to output as text.
For input text, the format describes the expected order of the elements. The exact form of those elements (digits or text) is not important. If the number of elements is less than the format's, then the lest significant field or fields are removed from the format. A fields significance is determined by its ranking order. For example:-
| "(Month) |(Day) |(Year)" |
In this example with a ranking of Year, Month, Day
and 3 values input, the 1st value is assigned to the Year field,
the 2nd to the Month and 3rd to the Year
If only 2 values are input, the 1st
For input text, the format describes the expected order of the elements. The exact form of those elements (digits or text) is not important. If the number of elements is less than the format's, then the lest significant field (or more) is removed from the format.
For text output, the value inside the parenthesis describes the field to be output. The field name may be the default, or alias field name detailed in the associated grammar. Text outside of the parenthesis (excluding the '|' characters) is output verbatim. If an field is suppressed (a range short-cut for example), then everything in that element is omitted.
The table below shows the available styles.
| Field Format Specifier | |||
|---|---|---|---|
| Style | Syntax | Example | Result |
| Number | (Name) | (Month) | 9 |
| Lexicon token | (Name:Lexicon) | (Month:m) | September |
| Abbreviated lexicon | (Name:Lexicon:a) | (Month:m:a) | Sep |
| Left padded number | (Name::lp:cwidth) | (Month::lp:02) | 09 |
| Note, cwidth is the character used for padding followed by the minimum width. | |||
| Output Only Specifiers | |||
| Number and ordinal suffix | (Name::os) (Name::os.u) | (Month::os) (Month::os:u) | 9th 9TH |
| Just ordinal suffix | (Name::oa) (Name::oa:u) | (Month)_(Month::oa) (Month)_(Month::oa:u) | 9_th 9_TH |
| Number, Roman numerals | (Name::rn) (Name::rn:l) | (Month::rn) (Month::rn:l) | IX ix |
Format Sub-Statement: separators
When inputting a date, by default the characters used to separate date elements are ',' and ';'. This sub-statement allows a change to the default.
Format Sub-Statement: rank
Rank is the order of the separate elements of a record that is used when an incomplete or range short-cut is used. The missing elements are assumed to be the lowest ranks, and the range covers all the possible dates.
If not given, the rank order is that stated by the grammar or the same as the default order.
Format Sub-Statement: rankout
The same as the rank sub-statement but it only affects the output of a format. It is used when separate input and output sub-statements are used.
Format Sub-Statement: style
Set style attributes for the Format. The default is style none.
| style Sub-Statement | |
|---|---|
| Description | Switch |
| No style settings. | style none; |
| Do not show the format in the format list. | style hide; |
