Under Construction

scheme Statement

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. These types are currently 'base', 'shifted', 'hybrid' and 'regal'.

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 one, and only one, of the sub-statements: 'base', 'shift', 'epoch', 'hybrid' or 'regnal'. Other sub-statements are optional.

scheme Sub-Statement List
Sub-Statement	Use	Example
name	A descriptive name for the scheme.	name "Julian Annunciation";
base	Scheme uses one of the base calendars.	base gregorian;
epoch	Scheme uses one of the base calendars with the epoch shifted.	epoch 1721507 julian;
hybrid	Scheme uses more than one the base calendars.	hybrid { ... }
regnal	Scheme uses calendars with a succession of eras.	regnal { ... }
grammar	Predefined grammar to be used.	grammar jce;
	Anonymous grammar definition.	grammar {optional newmoon;}
style	The scheme style used.	style hide;

name Sub-Statement

Gives a descriptive name to the calendar scheme. Used by the HistoryCal program to show a 'pick-list' of available calendar scheme to select. This sub-statement is optional but, unless the scheme is to be hidden, it would normally be included.

base Sub-Statement

The HistoryCal library has, at its heart, the ability to work with a number of basic calendar schemes. Once created these schemes can then be used to create variants.

Base Calendars
Name	Base-name	Description	Reference Scheme
Julian Day Number	jdn	A day count calendar used internally by HistoryCal.	jdn
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.	isow
ISO Ordinal	isoordinal	A solar calendar with numbered days, based on Gregorian.	isoo
French Republic	french	The calendar used for a while by the French Republic.	fr
Hebrew	hebrew	The calendar used by Jewish communities.	h
Islamic Tabular	islamic	A tabular version of the calendar used by Muslim communities.	i
Chinese	chinese	The lunisolar calendar used by China and other Asian countries.	c

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. There may also be a number of optional fields which can be used with the built-in calendar, using the optional sub-statement.

There are some optional fields which may be used with any base calendar scheme.

Global Optional Fields
Description	Field-name	Default Script
7 Day week, Monday start.	wday	7 Day Week
7 Day week, Sunday start.	wsday	7 Day Week
Julian Week Number. (Week version of jdn.)	jwn

In addition, there are astronomical optional fields that hold the Julian day number of relative astronomical events.

Astronomical Optional Fields
Description	Field-name
The jdn day of the next Northward (Mar) Equinox.	nequinox
The jdn day of the next Northern (Jun) Solstice.	nsolstice
The jdn day of the next Southward (Sep) Equinox.	sequinox
The jdn day of the next Southern (Dec) Solstice.	ssolstice
The jdn day of the next New Moon.	newmoon

Example Script
scheme A { name "Astronomical Events Calendar"; base jdn; grammar { optional newmoon; } } set inout g:dmy; let d = date "19sep1948"; writeln "The New Moon after " + string d + " is " + string (d[A:newmoon]);
Output:- The New Moon after 19 Sep 1948 is 2 Oct 1948

base jdn Sub-Statement

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 a script, then by default it is a Julian Day Number.

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.

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 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 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 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 very 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 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 produces two possible results. An additional element is required to indicate the required day, for example, the 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.

style Sub-Statement

Set style attributes for the Scheme. The default is style none.

style Sub-Statement
Description	Switch
No style settings.	style none;
Do not show the scheme in the scheme list.	style hide;