Statement: scheme

Before any calendar can be used as input or output, it must be defined using the 'scheme' definition statement. The layout of the statement varies according to the calendar type being defined.

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

The scheme must include the base sub-statement. Other sub-statements are optional.

scheme Sub-Statement List
Sub-Statement	Use	Example
name	A descriptive name for the scheme.	name "Julian Annunciation";
base	The base calendar used by the scheme.	base julian;
epoch	Scheme uses a different epoch to the base calendar.	epoch 1721507;
grammar	Predefined grammar to be used.	grammar jce;
	Anonymous grammar definition.	grammar { optional wday; }
visible	The default visibility in scheme lists.	visible no;

Sub-Statement: name

Gives a descriptive name to the calendar scheme. This name would normally be shown to the user whenever they need to select a scheme. Although this statement is optional, any operational scheme should include it.

Sub-Statement: base

The Hics extension has the ability to work with with a number of calendars and scheme types. This list will be extended in the future.

Base Calendars
Name	Base-name	Description	Reference Scheme
Julian Day Number	jdn	A day count calendar used internally by Glich.	jdn
Julian Week Number	jwn	A week count calendar based on Julian Day Number.	jwn
Julian	julian	The base for the Julian calendar variants.	j
Gregorian	gregorian	The modified Julian calendar used world wide.	g
ISO Week	isoweek	A solar calendar with numbered 7 day weeks, based on Gregorian.	gw
Gregorian Ordinal	ordinal	A solar calendar with numbered days, based on Gregorian.	go
Hebrew	hebrew	The calendar used by Jewish communities.
French Republic	french	The calendar used for a while by the French Republic.
Islamic Tabular	islamic	A tabular version of the calendar used by Muslim communities.
Chinese	chinese	The lunisolar calendar used by China and other Asian countries.
Hybrid	hybrid	A calendar created by combining two or more similar schemes.	ay

The base sub-statement will create one of the built-in calendar schemes. These schemes have associated with them a default record containing a fixed number of named fields. The record may be extended by adding calculated fields and optional values.

The base-name keyword may be followed by further keywords which further define the scheme. These are detailed below with the base-name description.

All base sub-statements may include the location keyword. This pinpoints an exact location for identifying the local time. This may be needed for calculating astronomical features required by the scheme. For example the day that a new moon occurs. Unless otherwise stated, the default location is the Greenwich Observatory, England.

Base Keywords
Keyword	Description	Default
loc:latitude:longitude	Location for local time	"loc:51.4772:0.0"

Sub-Statement: base jdn

This sub-statement implements the Julian Day Number day count calendar. The calendar has a record with a single fixed field named 'day'. If a field is used to represent a date in the script, then by default it is a jdn (Julian Day Number).

An additional keyword epoch:date may be used to create any day count calendar scheme by changing the scheme's epoch.

Base jdn Keyword
Keyword	Description	Example	Reference Scheme
epoch:date	Change the day count epoch.	base jdn epoch:2400002	mjd

Sub-Statement: base jwn

This sub-statement implements a Julian Week Number day count calendar. There no known use of this calendar outside of Glich and is included for completeness. The calendar has a record with two fixed fields named 'week' and 'day'.

Week days are normally handles by other schemes as an optional field. The optional field names depend on the day the week starts.

Base jwn Keywords
Keyword	Description	Default Epoch	Reference Scheme
monday	Week start Monday. Default	1w 1d = jdn 7d	jwn
tuesday	Week start Tuesday.	1w 1d = jdn 1d
wednesday	Week start Wednesday.	1w 1d = jdn 2d
thursday	Week start Thursday.	1w 1d = jdn 3d
friday	Week start Friday.	1w 1d = jdn 4d
saturday	Week start Saturday.	1w 1d = jdn 5d
sunday	Week start Sunday.	1w 1d = jdn 6d	jwsn

base julian Sub-Statement

This sub-statement implements the Julian calendar. The calendar has a record with three fixed fields named 'year', 'month' and 'day', ranked in that order. The year is divided into 12 months numbered 1 to 12. The months have the following number of days, 31, 28/29, 31, 30, 31, 30, 31, 31, 30, 31, 30 and 31, numbered from 1. If the year is divisible by 4 then it is a leap year and the second month has 29 days, otherwise it is a common year and it has 28 days. The epoch is jdn# 1721424.

An additional keyword year:offset may be used which effectively changes the epoch by a fixed number of years.

Base julian Keyword
Keyword	Description	Example	Reference Scheme
year:offset	Offset the year by a fixed amount.	base julian "year:-38"	eh

base gregorian Sub-Statement

This sub-statement implements the Gregorian calendar. The calendar is identical to the Julian calendar except the epoch is jdn# 1721426 and century years not divisible by 4 are common years.

base isoweek Sub-Statement

This sub-statement implements the ISO 8601 Week calendar, a variant of the Gregorian calendar. The calendar has a record with three fixed fields named 'year', 'week' and 'wday', ranked in that order. Weeks are a repeating cycle of 7 days numbered 1 to 7. The epoch is jdn# 1721426, a Monday. The year starts on the week day 1 (Monday) that is closest to the Gregorian year start.

base isoordinal Sub-Statement

This sub-statement implements the ISO 8601 Ordinal calendar, a variant of the Gregorian calendar. The calendar has a record with two fixed fields named 'year' and 'day', ranked in that order. The year has the same value as the Gregorian year. The day is numbered 1 to 365 days in a common year and 1 to 366 in a leap year.

base hebrew Sub-Statement

This sub-statement implements the arithmetical lunisolar Hebrew calendar used by Jewish communities since the 12th century. The calendar has a record with three fixed fields named 'year', 'month' and 'day', ranked in that order. The year is divided into 12 months in a common year and 13 in a leap year. The months have the following number of days, 30, 29, 30, 29, 30, 29, 30, 29/30, 29/30, 29, 30 and 29/30 (29), numbered from 1. The epoch is jdn# 347998 (jce:dmy# 7 Oct 3761 BCE). See the default script Hebrew calendar definition for more details.

base french Sub-Statement

This sub-statement implements the calendar established following the creation of the French Republic. The calendar has a record with three fixed fields named 'year', 'month' and 'day', ranked in that order. The year is divided into 12 months of 30 days and a 13th period of 5 or 6 days. The months and days are numbered from 1. The first day of the year occurs on the autumnal equinox as measured at the Paris Observatory. The epoch is jdn# 2375840 (g:dmy# 22 Sep 1792).

base islamic Sub-Statement

This sub-statement implements the arithmetical lunar Islamic calendar. (The observational Islamic calendar will be implemented in a future version.) The calendar has a record with three fixed fields named 'year', 'month' and 'day', ranked in that order. The year is divided into 12 months in a year. The months have the following number of days, 30, 29, 30, 29, 30, 29, 30, 29, 30, 29, 30 and 29/30, numbered from 1. The length 12th month is 29 in a common year and 30 in a leap year. Determination of a leap year is based on the 30 year Metonic cycle. Two alternative epochs may be used, jdn# 1948439 (j:wdmy# Thur 15 Jul 622) or jdn# 1948440 (j:wdmy# Fri 16 Jul 622). The arrangement is selected using an additional keyword based on the descriptions given by R.H. van Gent.

Tabular Islamic Calendars
Keyword	Leap years within Metonic cycle	Epoch (j:wdmy)	Reference Scheme
Ia	2, 5, 7, 10, 13, 15, 18, 21, 24, 26 & 29	Thur 15 Jul 622
Ic	2, 5, 7, 10, 13, 15, 18, 21, 24, 26 & 29	Fri 16 Jul 622
IIa	2, 5, 7, 10, 13, 16, 18, 21, 24, 26 & 29	Thur 15 Jul 622	ims
IIc	2, 5, 7, 10, 13, 16, 18, 21, 24, 26 & 29	Fri 16 Jul 622	i
IIIa	2, 5, 8, 10, 13, 16, 19, 21, 24, 27 & 29	Thur 15 Jul 622	if
IIIc	2, 5, 8, 10, 13, 16, 19, 21, 24, 27 & 29	Fri 16 Jul 622
IVa	2, 5, 8, 11, 13, 16, 19, 21, 24, 27 & 30	Thur 15 Jul 622
IVc	2, 5, 8, 11, 13, 16, 19, 21, 24, 27 & 30	Fri 16 Jul 622

If the additional keyword is not given, IIc is assumed.

base chinese Sub-Statement

This sub-statement implements the lunisolar Chinese calendar. The calendar has a record with five fixed fields named 'cycle', 'cyear', 'month', 'lmonth' and 'day', ranked in that order. A cycle is divided into 60 Chinese years (cyear). The year is divided into 12 lunar months in a common year and one month is repeated in a leap year. The lmonth field is always zero, except in a leap year when the during the repeated month it has the value of 1. Each month starts on the day of the new moon and has 29 or 30 days. The epoch is jdn# 758326 (jce:dmy# 8 Mar 2637 BCE). See the default script for the Chinese calendar for more details.

epoch Shift Sub-Statement

Calendars normally have two separate parts to their definitions. There is the definition that describes how the days are counted within the year, then there is the method of counting those years. One common occurrence is that different calendar schemes may use the same method to count the days with the year but have different ways of counting the years. The year count may start at any point of the year, not just the point normally considered the start of the year (New Years Day).

For instance, when Julius Caesar introduced the Julian calendar, New Years Day was considered to be 1st January. However, not all calendar systems increased the year count on this day. When the AD (Anno Domini) Julian calendar was first used, the year change occurred on the 25th December. Later, many other dates were used, for instance, 25th March, the Feast of the Annunciation.

We can also use the epoch variant to change the era, even if the year change remains the 1st January, as with the Julian Spanish Era calendar. It will also work with day count calendars, to create day count calendar that starts at a different date, such as the Modified Julian Day calendar.

epoch Sub-Statement
Sub-Statement	Example
epoch date-field base-scheme;	epoch 1721417 julian; // j:dmy# 25 Dec 0 epoch 2400001 jdn; // Modified Julian Day

The sub-statement consists of the 'epoch' keyword followed by the epoch date followed by the base scheme.

Example Script
scheme JS { name "Julian September Start Calendar"; epoch date.j:dmy "1 Sep 0" julian; grammar jepoch; }

hybrid Sub-Statement

When an authority changes from one calender system to another, and where the underling system is the same, we can create a hybrid calender. This occurred quite often with the Julian and Gregorian calenders. Not only do they switch between them, they may also change the year count change date.

In order for a hybrid calendar to be useful, the change over must occur in an organised way, on a particular day. Where it is possible, a hybrid calendar can simplify things.

The hybrid calendar has the appearance of adding or removing days from the calender. On the occasions that days are added, this produces an ambiguity. When one of these ambiguities occurs, entering a date may produces two possible results. An additional element is required to indicate the required day, for example, the precise scheme being used. Alternatively, something like the day of the week can be added.

The sub-statement consists of a sequence of further sub-statements between braces, starting with a 'fields' statement that lists the fields used. This is followed by the initial 'scheme' statement, followed by one or more 'change' and 'scheme' statement pairs.

Example Script
scheme eng { name "English Hybrid"; hybrid { fields year, month, day; scheme ja; change 2360976; // j:dmy# 1 Jan 1752 scheme j; change 2361222; // g:dmy# 14 Sep 1752 scheme g; } grammar hy; // See default script eng }

hybrid Sub-Statement
Sub-Statement	Example
hybrid { fields name1, name2, name3; ... }	fields year, month, day;
hybrid { ... scheme scode; ... }	scheme ja; // Julian Annunciation
hybrid { ... change date_value; ... }	change 2360976; // j:dmy# 1 Jan 1752
hybrid { ... scheme {scheme sub-statements} ... }	scheme { base julian; }

Note, a schemes must either be defined before use, or created in place anonymously.

regnal Sub-Statement

A common method of numbering the years in a calendar is to number them from the start of the reign of a monarch or official. Such calendars are still in use today.

A calendar based on this system is really a sequence of shifted calendars, the era of each based on the start of the reign. We can also specify the date range covered by each era, which may overlap or have gaps. A default calendar is also defined and is used if no suitable range is found.

regnal Sub-Statement
Sub-Statement	Example
regnal { fields name1, name2, name3; ... }	fields year, month, day;
regnal { ... extended name1, name2; ... }	extended hyear;
regnal { ... fixed date.field = value; ... }	fixed year = 1;
regnal { ... era { era-sub-statements } }	era { scheme j; } // Julian default scheme

grammar Sub-Statement

This can be used to link to a previously defined grammar (using its grammar code) or to define an anonymous grammar. One or zero grammar sub-statements can be defined.

visible Sub-Statement

When a scheme list is requested, this attribute determines if the scheme is to be included. The default is visible yes.

visible Sub-Statement
Description	Switch
Show scheme is scheme list.	visible yes;
Do not show in the scheme list.	visible no;