Statement: grammar

The grammar statement contains a number of sub-statements which describe how a scheme's input and output is written.

The grammar must be given a unique (within all other grammars) code name by which it can be referred to. It may then contain the following sub-statements in between '{' and '}' braces.

grammar Sub-Statement List
Sub-Statement	Use	Example
name	Give the grammar a text description.	name "Julian calendar schemes";
inherit	Inherit all the settings from a previously defined grammar.	inherit j;
fields	List of base fields, must match base order.	fields year month day;
calculated	List of calculated fields.	calculated ce ceyear;
optional	List of optional fields.	optional wday;
rank	The field ranking used by the format sub-statements.	rank ce ceyear month day;
lexicons	The list of lexicons used with this grammar.	lexicons m w jce;
alias	Allow the use of alternative field names.	alias field {WDay wday; ...}
function	A function to be available to an attached scheme.	function code { ... result = this; }
use	The default functions to be used by format.	use { calculate cmonth; from:text month; }
format	The description of the formats.	format dmy "{day} |{month:m:a} |{year}";
preferred	The preferred format to use, unless otherwise stated.	preferred dmy;

Sub-Statement: name

Gives a descriptive name to the grammar. This gives a way to document the purpose of the grammar, which will help in reuse.

Sub-Statement: inherit

Create a new grammar by extending an existing one. The action of the original grammar is not changed in any way.

Sub-Statement: fields

Declare the required fields that match the intended scheme base required fields. This list is checked whenever the grammar is attached to a scheme. If the match fails, an error is generated.

If the grammar inherits, then the inherited fields are appended those given.

Sub-Statement: calculated

List fields which are calculated based on the required fields.

Sub-Statement: optional

Declare all the optional fields required. The format definitions can only refer to the required and calculated fields plus the extended fields listed here.

Sub-Statement: rank

This is the ranking order to be used by the format statements, unless the format statement has its own rank sub-statement.

Ranking is used with shortcut ranges. For example, "Jul 2023" is a shortcut for the range of all the days in July 2023.

We create the shortcut by omitting the fields to the right of the ranking list.

Sub-Statement: lexicons

Declare all the lexicon statements to be used. The format definitions can only refer to the lexicons listed here.

Sub-Statement: alias

In a number of places, it is preferable to use a different name than the default. The statement takes the form:-

alias type { alias field-name; alias field-name; ... }

Where type is one of: field, pseudo, unit or lexicon.

grammar alias Sub-Statement
Sub-Statement	Use	Example
alias field	Allow the use of more user friendly field names.	alias field {WDay wday; ...}
alias pseudo	The pseudonym matching numbers in the pseudo date.	alias pseudo {w wday; dd day; ...}
alias unit	Alternative field name when used as a unit.	alias field {d day; m month; ...}
alias lexicon	When the register name does not match the lexicon name.	alias lexicon {wday day; ...}

Note, the alias does not replace the field-name, but gives a preferred alternative.

Sub-Statement: alias field

Create user friendly names for the fields used in the format strings.

Sub-Statement: alias pseudo

When the date format needs to show that numbers will be displayed for a particular element in a particular position, the pseudo alias shown here will be used in creating the pseudo date.

Note, if a lexicon is used to provide output, the pseudo name will be provided by the lexicon definition.

Sub-Statement: alias unit

The universal unit format ":u" expects input in one or more 'number unit' pairs. The unit given is (in order of lookup) the unit alias, the field alias or the default field name.

Sub-Statement: function

This defines a function that can be used by any scheme which has attached the grammar. The function is defined in the same way as an object function.

The default, calculated and optional field names will be available to the function as local variables. To actually make changes to the scheme object, the function should set the result to 'this' (the modified scheme object).

Sub-Statement: use

Define the default functions to be used by format sub-statements. Either define the functions directly or refer to those automatically created.

grammar use Sub-Statement
Code	Note	Example
use { calculate create-calculated; from:text create-default; }	Create all calculated fields from the default fields. Create all fields the fields provided from the text.	use { calculate calc_cmonth; from:text calc_month; }
use epoch;	Used with schemes that define an epoch date.	use epoch;

A format may use a function in two different ways.

1. Converting a jdn (Julian Day Number) to a text string which uses calculated fields. The jdn is converted into the default fields and a function would complete the calculated fields before formulating the text string. This uses the calculate function.
2. When converting a text string to a jdn. The date elements are composed into their fields and any calculated fields are used to complete the default fields. The default fields are then used to obtain the jdn value. This uses the from:text function.

If a format does not use the default function for text input, then the format sub-statement use:in should be used to specify it.

Sub-Statement: format

Apart from the grammar:format signature, the format sub-statement is the same as format statement.

A grammar may have many format sub-statements.

Sub-Statement: preferred

The preferred format to use. If this sub-statement is missing, the first format listed is used.