HistoryCal - V0.0.7 Manual
Script Language

Home Development V0.0.7 Manual Script

Section Under Construction


The HistoryCal program has a built-in script language called HistoryCal Script. This is different from the input that has been described at the beginning of this manual, which is called a HistoryCal Date Expression. The Date Expression is similar to the script but is simplified and designed for easier input. The Date Expression is converted into a HistoryCal Script to be evaluated.

The script is designed to serve two main purposes.

The scripts for the default calendar definitions are shown in the calendar definitions section.

Hello World

A script consists of one or more statements. As is usual in these circumstances, we present a hello world script.

Hello Script
// Hello world script. writeln "Hello world!";
Hello World message screen print

Using a text editor, copy the script and save as "hello.hcs". Run the HistoryCal Script by starting the HistoryCal program. Under the menu option "File > Run Script ..." find the file and select it. This should then result in the message shown.

Scripts should always use the UTF-8 character set.

Comments and White Space

// A single line comment /* This is a multi-line comment. */

The first line is a single line comment. Every thing from the "//" token to the end of the line taken to be a comment.

Multi-line comments are included by placing them between the "/*" and "*/" tokens. Multi-line comments cannot be nested.

Tabs, spaces, newlines and comments can appear anywhere within a script without its meaning being affecting. They are required only when necessary to separate tokens.


The tokens that make up the script can be categorised into three groups, operators, literals and names.

Operators are used to construct expressions. Mostly they are non-alphanumeric characters but they also include some text words. A complete list is given in the Operator List table. Where words are used, they are reserved and cannot be used as names.

Literals can be numbers or text strings. Numbers (usually called fields) consist of just the numeric characters '0-9'. At this time, only integer numbers can be used. Text strings are placed between '"' double quote characters. If you need to include a double quote in the text, use two together, as in "Say ""Hello""".

Names are constructed from alphanumeric, '_' underline, ':' colon and '.' dot characters. They can not start with a numeric or dot character. The meaning of a name is dependant on the context and the same name can be used for different purposes in a script, although this is not recommended. Names are used as statements, sub-statements, statements arguments and variables.

Entities and Codes

The Cal code library is used by defining scheme entities. This is done by using the scheme statement in the script language. The scheme entity makes use of vocab (vocabulary), format and grammar entities. These are all identified by a code name. Because the script always knows, by context, which type of entity is being referred to, the different types can reuse the same code name.

A code name can use any character except white space and the characters ':' colon and '#' hash. (More characters may be added to the excluded list in the future.) If the code conforms to the script name token definition it can be written directly, otherwise it must be written as a literal (i.e. in double quotes).

When the HistoryCal program starts, it reads the default script which make the default schemes available to the program. The default script for the various schemes are shown with their technical descriptions here.

Expressions and Variables

Values in the HistoryCal Script can exist as one of a number of types:-

Variables are defined by using the let statement, but their type is determined by their context. There are a number of operators which are used in expressions and the types of these expressions are automatically converted, wherever possible.


A script consists of one or more of the following Statements:-

Statement List
callRun a predefined function.call today.fr;
clearDelete all variables.clear;
doRun script until a condition is met.do while y <= 2015 writeln "1 Jan " + y; y += 1; loop
endStop running the script.end;
formatDefine a Format for a grammarformat j:ydm, "(Year)| (Day)| (Month:m)";
functionDefine a Function which can be called later.function today.fr { write string,fr:out today; }
grammarDefine a Grammar for a calendar.grammar J { inherit j; format ydm, "(Year)| (Day)| (Month:m)"; }
ifRun code depending on condition.if value = today write "<b>" + string value + "</b>"; else write string value; endif
letInitialise or change a variable.let d = 1;
markSet a named mark in the script.mark "test1";
schemeDefine a calendar Scheme.scheme j { name "Julian"; base julian; }
setSet a global default setting.set output g:iso;
vocabDefine a Vocabulary for a calendar field.vocab ce { name "Historic Era"; tokens { 0, "Before Christ", "BC"; 1, "anno Domini", "AD"; } }
writeCreate output.write value + ", ";
writelnCreate output, followed by a new line.writeln "Today is " + string today;

Valid XHTML 1.0 Strict

10th March 2014