== The TaskJuggler Syntax ==

=== Understanding the Syntax Reference ===

This manual provides a comprehensive reference of the TaskJuggler
syntax. It is automatically generated from the same data that the
parser uses to read your project files. This ensures that the
software and the manual always match.

The syntax reference is organized based on the keywords of the
TaskJuggler syntax. There is an entry for every keyword. In some
cases, a keyword can appear in different contexts with potentially
different meanings. In this case, the context is provided in brackets
after the keyword for at least one of them. That way, every keyword
is uniquely referenced.

The syntax for each keyword is described in the syntax section of the
table that is provided for each keyword. The syntax always starts
with the keyword. Keywords are then followed by arguments.
In some cases, an argument can be automatically generated.  In such
cases, the argument is enclosed in square brackets. 

 keyword [<id>]

Arguments can be variable or picked from a predefined list of options.
Variable arguments are listed with their names enclosed in angle
brackets.

 keyword <name>

List of predefined options are enclosed in brackets, the
options separated by a vertical bar.

 keyword ( foo | bar | foobar )

Some keywords take one or more arguments. These are known as list
attributes. The arguments are comma separated. The three dots in the
syntax description mean that the sequence before the dots can be
repeated if needed. Inheritable list attributes will append the new
list values to the inherited list. Use can use the [[purge]]
attribute to clear the list before assigning new values to the list
attribute.

 keyword arg1 [, arg2 ... ]

Variable arguments are further described in the ''Arguments'' section of
the keyword syntax table. The name is listed immediately followed by
the type of the variable argument. The supported types and their
meaning is described in the following sections.

==== ABSOLUTE_ID ====

An absolute identifier is composed of identifiers that are
concatenated by dots, e. g. ''''foo.bar''''. It is used to reference
a TaskJuggler property that lives in a hierarchical name space.
Accounts, Tasks, Reports are examples for such hierarchical name
spaces. To reference the sub-task ''''bar'''' of task ''''foo'''' the
absolute ID ''''foo.bar'''' is used.

==== ID ====

An identifier is composed of the letters ''''a'''' to ''''z'''',
''''A'''' to ''''Z'''', the underscore and the digits ''''0'''' to
''''9''''. There are no limits for the number of characters, but it
may not begin with a digit.

==== INTEGER ====

An integer is any natural number, e. g. ''''0'''', ''''1'''',
''''2'''' and so on.

==== STRING ====

Strings are character sequences that are enclosed by special
character marks. There are three different marks supported. For
short strings that fit on one line, you can either use single or
double quotes.

 'This is a single quoted string.'
 "This is a double quoted string."

Single quoted strings may contain double quotes and vice versa.
Alternatively, you can prefix the quote mark with a backslash to use
it within a string.

 'It\'s a string with a quote included.'

If you want to use a backslash right before the included quote you
need to escape the backslash with another backslash. Backslashes that
aren't followed by a quote mark don't need to be escaped.

 'A backslash \\\' followed by a quote.'

For multi-line strings or strings with many included quotes cut mark
strings are recommended. A cut-mark-string starts with
''''<nowiki>-8<-</nowiki>'''' (scissor on a dotted line) and ends with
''''->8-''''(scissors looking the other way). The start mark must be
immediately followed by a line break. The indentation of the first
line after the opening scissors must be repeated for all following
lines of the string and is not included in the resulting strings. The
terminating cut mark must only be preceded by white spaces in that
line. When considering the indentation, tabs are not identical with
some number of spaces. Each indented line must be prefixed by the
exact same combination of tabs and spaces.

 -8<-
   This is a
   multi-line
   string.
   ->8-

=== Predefined Macros ===

TaskJuggler supports a few predefined macros. These are available
after the project header. Their values correspond to the values
provided in the project header.

* ''''projectstart'''' The start date of the project.
* ''''projectend'''' The end date of the project.
* ''''now'''' The current date. If the user does not provide a date
with the [[now]] keyword, the moment of the processing of the file
will be inserted. Keep in mind that this will change every time you
process your project.  The current setting of [[timeformat]] has no
impact on the expansion of the macro.
* ''''today'''' Identical to ''''now'''' but formatted according to
the [[timeformat]] setting of the current context.

=== Environment Variable Expansions ===

By using the $(VAR) syntax, you can insert the value of the
environment variable name VAR. The name of the variable must consist
only of uppercase ASCII letters, underscores or decimal digits.

