Added named block and file insertion code to lexer/parser.

[ahxm.git] / doc / language.txt

Markup language description - DRAFT
===================================

Overview
--------

Ann Hell Ex Machina scripts consist of a sequence of commands and their
possible arguments which run from the top to the bottom. Formatting and
indentation can be used in a free-form way.

At any time, comments can be inserted in C or C++ style as in the following
example:

 /* this is a C style comment,
        that spans multiple
        lines */
 // this is a C++ style comment, from the double / to the end of the line

Whitespace separation is not mandatory and commands can be conveniently
joined together if they are unambiguous.

For example:

 T120 M4/4 o5 c4 d8 e% f4 g8 a%16 b% c'1

can also be written as

 T120M4/4o5c4d8e%f4g8a%16b%c'1

or, grouped by measures,

 T120 M4/4 o5 c4d8e% f4g8a%16b% c'1

Includes
--------

Script files can be included from each other by enclosing filenames between
backticks, as in the example:

 `path/to/file`

The referenced file will be inserted at that exact point.

Tempo
-----

Tempo is expressed in Beats Per Minute (bpm) as in the next example:

 T120   /* sets tempo to 120 Beats Per Minute */

Obviously, tempo changes are global to all tracks. Though it's normally set
at the beginning of a song, it can be used anywhere. You can use marks to
be sure that tempo changes occur exactly where you want in all tracks (see
documentation for marks). The tempo can be a non-integer number.

Measure
-------

Measure is expressed as in standard music. For example:

 M4/4   /* classic 4 quarter notes measure */

Measure settings are global to all tracks as tempo.

Notes
-----

Syntax:

 pitch[length][volume]

pitch
~~~~~

Syntax:

 letter[alteration][octave]

Letter is any from a to g for english notation notes in the currently selected
octave, r for rests, or z for a zero-note, that allows setting the length
for subsequent notes.

The alteration is optional, and is any of # (sharp) or % (flat). If not
specified, natural note is assumed.

The octave is also optional, and is one or more ocurrencies of ' (one octave
higher for each one) or , (one octave lower for each one). If none is
specified, note is assumed to belong to the current octave.

Examples:

 a#     /* A sharp */
 g%     /* G flat */
 a      /* normal A */
 c'     /* C, one octave above */
 f#,,   /* F sharp, two octaves below */

length
~~~~~~

Optional, with the following syntax:

 figure[tuplet][mult]

Figure is any of 1, 2, 4, 8, 16, 32, 64 measure partitions. Tuplet, if present,
is a / followed by a numeric divisor (3 for triplets, etc.). Currently, only 3
or 5 tuplets are supported. Mult, if present, can be expressed as an *
followed by a numeric multiplier of the figure meaning the final length is
that times longer, or as a more music-standard series of dots, adding each
one half the length.

If no length is present, the note length is inherited from the last one
previously defined.

Examples:

 a4     // an A longing one beat
 r4.    // a rest, longing one beat and a half
 g8/3   // a G, in triplets of eighths
 f1*6   // an F longing 6 complete 4/4 measures
 r4*1.5 // same as r4.
 z2     // sets note lengths to a half note (no note inserted)

Immediate volume
~~~~~~~~~~~~~~~~

Optional, can be expressed as a ~ followed by a real number. Numbers below
1 will result in quieter notes, and above 1 in louder ones, as this number
will be multiplied by the global volume.

If no volume is specified, the full global one is used.

Examples:

 a4~0.8 // a quarter note of A at 80% of global volume

Measure marks
-------------

Measure marks help when writing music by asserting that measures last
exactly what the key says. They are the equivalent of measure bars in
standard music notation and are expressed by the character |. Unlike in
standard music, though, they are optional. Apart from checking, these marks
do not modify the resulting music in any way.

This piece of music will trigger an error in the second mark, just before
the c2, because it does not fall in a measure boundary.

 M3/4 a4 b c | c1 | c2

Permanent octave changes
------------------------

Permanent octave changing can be expressed as an absolute or
relative change. Examples:

 o2     /* sets octave number 2 (absolute) */
 o+1    /* sets one octave higher (relative) */
 o-2    /* sets two octaves lower (relative) */

Absolute octave numbers range from 0 to 10. Otherwise, for relative
changes, a signed integer number can be used.

A complete note trip up can be done this way, using absolute and
relative changes and blocks:

 o0 z16 (cdefgab o+1)*10

Octaves can be out of range (the previous example will end with
an invalid octave number of 11), but inserting a note after it
will generate an error. This is done purposely to allow block
repetitions like this one; just change to a valid octave
before inserting a new note.

Permanent volume changes
------------------------

Permament volume can be expressed as an absolute or relative change.
Examples:

 v0.75  /* sets global volume to 0.75 (75%) */
 v+0.1  /* increments current volume by 0.1 */
 v-0.3  /* decrements current volume by 0.3 */

Absolute volume range from 0 (silence) to 1 (full volume for current
samples). Values bigger than 1 can also be used.

Transpose
---------

Transposition is expressed as a negative or positive number of
semitones. By default, each track has an initial transposition
of 0. This is an example:

 t5     /* transpose a fifth up */

Note that transpose, as octave changing, can lead to out-of-bound
notes. No error will be reported until an invalid note is inserted.

Staccato
--------

The staccato is expressed as the partial time of the total note
length that the note will really sound. By default, each track
has an initial value of 0.8 (80%). Usual values range from 0.5 (staccato)
to 1 (tenuto). For example:

 s0.9   /* sets staccato to 90%: notes sound more tied together */

Groups
------

To form chords or more complicated sequences of polyphonic notes,
groups can be used. They are enclosed by < and > and separated
by semicolons. The group's duration is that of the longest of the parts.

The simplest example is a basic chord like this one:

 <c1 ; e% ; g>  /* a C minor chord for a whole 4/4 measure */

Each part of the group can contain more than one note:

 // the classic bass drum, snare, close and open hat beat
 <c8rrr crrr ; rrdr rrdr ; g#g#g#a# g#g#g#a#>

Glissando
~~~~~~~~~

By default, each part of a group start at exactly the same time. To
implement strumming (as, for example, in guitar chords, where each note
is played slightly after the previous one), the glissando command is used,
with an argument expressed as a note length:

 l16 <c;e;g> /* delay each chord note by a sixteenth */

Multipliers and tuplets can also be used (see the note length sections
for more information).

To disable glissando, use a glissando command with a value of 0.

Arpeggiator
-----------

The arpeggiator allows the programming of automatic repetitions for
each note, probably modifying some of its features. It's expressed
by the x command followed by a comma separated list of repetition
specifications with the following syntax:

 offset[volume][transpose][track]

Offset is a length specification (see Notes) and is the delay of
the repetition after the start of the original note (it does NOT express
the length of the repeated note; each arpeggiated note last the same as
the original one). It can be zero for notes that sound at the same time
as the original note.

Volume, if specified, is a ~ followed by a real number (see also Notes).
This volume is relative to the original volume of the note. If none is
specified, the note is repeated at its original volume.

Transpose, if specified, is a signed number of semitones to transpose
the original note. If no transpose is specified, the pitch of the repeated
note will be the same as the original.

Track, if specified, is a @ followed by a track number, meaning the note
will be inserted in that track (and not in the current one). This allows
generating stereo or multichannel arpeggios by having different channel
maps on each track.

An x command with no repetition specifications effectively disables
the arpeggiator.

Examples:

 x4~0.6                 // repeats each note a quarter later at 60% of vol.
 x4~0.6,2~0.4           // the same, but another repetition later at 40%
 x8-1,4-2,8*3-3         // 3 chromatic repetitions after each eighth
 x                      // disable arpeggiator

Marks
-----

To create a mark, use

 ^name-of-the-mark

and, in tracks defined later, you can set the cursor at the mark by using

 @name-of-the-mark

The mark name can use alphanumeric characters and hyphens. An error
is generated if a move to mark command is used but the current track's
cursor is already beyond that position (i.e. you cannot move 'backwards').

Marks can also be used for synchronization by using

 !name-of-the-mark

if the track's cursor does not match that of the mark position, an
error is returned reporting the difference in measures.

Blocks
------

Blocks are marked using pairs of parentheses. The closing one should
be followed by a character indicating the operation to do with the
block.

Repeating blocks
~~~~~~~~~~~~~~~~

Blocks that should be repeated a defined number of times can be
specified as

 (code)*times

Where code can be anything, from notes to track information, and
times the number of times the block will repeat.

Named blocks (patterns)
~~~~~~~~~~~~~~~~~~~~~~~

A block can be assigned a name to be later inserted. To name it:

 (code)=name-of-the-block

Where code can be anything, from notes to track information, and
name-of-the-block the name to be assigned. The name should not
contain spaces. The block is not inserted where it's defined; to
insert it, the following notation should be used:

 $name-of-the-block

So, for example:

 (c16defgab)=scale      // define a named block
 $scale $scale $scale   // insert several times
 ($scale)*8             // blocks can be nested

Named blocks can be redefined anytime:

 (($drumloop)*8)=phrase         // valid even though drumloop is still undef
 (cdcdcdcd)=drumloop $phrase    // drumloop resolved when inserting phrase
 (cdcccdcc)=drumloop $phrase    // inserts now 8 copies of the new drumloop

Time specifications
-------------------

Time should be followed by a unit. That unit can be ms (for milliseconds),
b (for beats) or s (for samples). So, for example, sustain can be expressed
as:

 :sustain=100ms         // sets sustain to 100 milliseconds
 :sustain=2b            // sets sustain to two quarter notes
 :sustain=44100s        // sets sustain to 44100 samples

Specifying a time in number of samples is not recommended, as it's
dependent of the current output frequency; use it only when you know what
you are doing.

instrument / track options
--------------------------

 :sustain=100ms         // sets instr. sustain to 100 milliseconds

Command reference table
-----------------------

Note commands
~~~~~~~~~~~~~

 a      Insert note A
 b      Insert note B
 c      Insert note C
 d      Insert note D
 e      Insert note E
 f      Insert note F
 g      Insert note G
 r      Insert rest (silence)
 z      Zero note (set length for future notes)
 o      Set default octave
 t      Set transpose
 s      Set staccato
 v      Set volume

Group commands
~~~~~~~~~~~~~~

 <      Start of group
 ;      Group delimiter
 >      End of group
 l      Set glissando delay

Block commands
~~~~~~~~~~~~~~

 (      Start of block
 )      End of block
 *      Block repetition if following )
 =      Named block assignment if following )
 $      Named block insertion
 `      Include script

Mark commands
~~~~~~~~~~~~~

 ^      Set mark
 @      Move to mark
 !      Mark assertion

Global commands
~~~~~~~~~~~~~~~

 T      Set tempo
 M      Set measure

Special commands
~~~~~~~~~~~~~~~~

 |      Measure mark
 x      Arpeggiator