Programmer's manual

1. Overview

  Figure 1 shows the general idea of a host application using the ABCp library.

fig. 1

  ABCp is an ANSI C library so it should be easy to statically link it to the host application. All C/C++ compilers will be able to do it and also many compiler for other languages offer this possibility.

  ABCp could also be compiled as a shared library opening it up to other languages.

2. Interaction with the library

  Figure 2 shows how the ABCp scanner reads the abc file and translate it in a sequence of tokens that the host program will handle.

fig. 2

  The sequence diagram in figure 3 should clarify the way the host application interacts with the library.

fig. 3

There is a rather important point to bear in mind. The ABCp scanner only deals with "token", it does not check the meaningfulness of the context in which they appear. For example "A-B" is reported as: "the note A, a tie, the note B". It's up to the host application to decide if this is interpretable in any way or is to be considered an error.

3. The scanner

As shown in the figure 3 above, the host application interfaces the library through a scanner object. There are two functions to create a scanner:

abcScanner *abcFileScanner(char *filename,unsigned long bufsize);

abcScanner *abcStringcanner(unsigned char *abctext, unsigned long bufsize);

The first one reads the music from a file, the second one from a text buffer.

4. An example

The following example shows a tipical usage of ABCp.

001: #include "abcp.h"
 002: int main(int argc,char **argv)
 003: {
 004:   abcScanner *s; unsigned short tok;
 005:   s = abcFileScanner(argv[1],0);
 006:   if (s != NULL) {
 007:     while ((tok = abcNextToken(s)) != T_EOF)
 008:       if (tok == T_NOTE)
 009:         printf("Note: %c%d\n",abcNote(s,pitch),abcNote(s,octave));
 010:   }
 011:   abcClose(s);
 012: }

The code above, creates a scanner and get tokens one at a time from the file whose name has been given as the first argument. For each note, its pitch and octave are printed. The file main.c in the distribution archive provide a complete example.

An effort has been made to keep an OO resemblance in the syntax. Would the above example be in C++, one would have read: s.NextToken() and s.Note.pitch (or something similar).

5. Tokens

The ABC file is read "token by token". The following functions will help dealing with tokens:

Note that abcTokenStart(s) does not return a pointer to a zero terminated string! If you are really interested in the string itself you should copy it in a local buffer using, for example, strncpy().

This is the list of the different tokens abcNextToken() may return.

5.1 T_UNKNOWN

Returned when the scanner has been unable to recognize a piece of input. It is normally a sign of a syntax error; for example:

A , B,

Will report the token T_UNKNOWN  on the stray comma after the note A.

This could also be used to enrich the ABC syntax. You could, for instance, assign a meaning to '$' and being able to handle the following:

A $ B

5.2 T_NONE

This token should never been reported by the scanner. In case you get it , you can safely ignore it.

5.3 T_EOF

Marks the end of the ABC input. Any other call to abcNextToken() will return T_EOF.

5.4 T_EMPTYLINE

A line made by 0 or more spaces (ASCII 32 or ASCII 9 characters) followed by a return. It's used to mark the end of an ABC Tune.

5.5 T_ENDLINE

The end of a physical line. Normally marks the point where a staff should be broken.

5.6 T_BREAK

An explicit request to break the line (!).

5.7 T_CONTINUE

An indication that the input line ends but the logical lines actually continues (\). It may be followed by a comment (\ %...) in which case the functions defined for T_COMMENT will return a non-null value.

5.8 T_COMMENT

A comment (%....). The following functions will help retrieving the comment string:

5.9 T_PRAGMA

A line starting with '#'. This may be used by host applications to introduce extended functions.

5.10 T_FIELD

An information field. The following functions will help with fields. 

5.10.1 General functions

5.10.2 String fields

The string that appears after the field specifier.

This is can be used with any field and it's all that you need for fields like T:, A:, O: etc.

5.10.3 L: Notes length

The length is specified as a fraction:

5.10.4 M: Meter

The meter is specified as a fraction (e.g. 4/4):

If  abcMeter(s,num) returns 0, you can check if it's a special meter using the following functions:

If  abcMeter(s,den) returns 1, it's an ancient meter (M:3).

ABCp also accepts different meters for playing eg: M:3=6/4

To retrieve addends of a complex meters (e.g. M:2+2+3/8) the following array is available:  

The meter, its numerator or its denominator can be parenthesized.

5.10.5 Q: Tempo

Tempo can be expressed in many ways. The one proposed in the ABC 2.0 standard draft is Q:n/d=b to express that there are b notes of length n/d per minute.

The following functions help with this syntax:

Older ABC syntax allowed a tempo specification that was dependent from the default note length: Q:C=120 or Q:120 means that there are 120 notes of the default length in a minute. ABCp detects it and set the isRelative field accordingly:

For printing purpose up to four beats can be specified (Q:1/4 3/8 1/4 3/8=40). The num and den fields will report the correct sum (i.e. as if it was Q:5/4=40) and the numerators and denominators to print will be in the nums and dens arrays.

5.10.6 r: Remarks

See T_COMMENT.

5.10.7 K: Key

The key field can also contain clef specifiers:

 Transposition specifiers:

Staff parameters:

5.10.8 V: Voice

The Voice field can also contain clef specifiers:
 

Transposition specifiers:
  

Staff parameters:

5.10.9 P: Parts

5.11 T_NOTE

 Returned each time a note is encountered.

short abcNote(s,bend)	Accidentals and microtones are treated as bending the note pitch. A semitone is equivalent to a pitch bend of 8192. The image below shows a progression by quarters of tone (microtones notation is just one of the many used, there's no standard!).
unsigned char abcNote(s,bending)	May have three values:  \0 no bending  b  bending  p  cautionary (parentesized) bend (see image on the right)

5.12 T_REST

5.13 T_SPACE

White space is used to separate notes that should not be beamed. Black space (obtained with `) is used to make the suorce ABC file more readable.

5.14 T_SPACER

A spacer (y) is used to insert typographical white space in the line.

5.15 T_DECORATION

ABCp is able to recognize many commonly used decorations and also allows synonyms (e.g. "pp" and "pianissimo" are considered the same).

It returns a unique code for each:

5.15.1 Dynamic signs

5.15.2 Articulation

5.15.3 Fingering

5.15.4 Pedals

5.15.5 Pause

5.15.6 Percussion

5.15.7 Misc 

5.15.8 Decoration range

Some decoration has a "range".

Examples might be pedal duration: "A +ped(+ B C D E +ped)+ F"

or temporary transposition: "... A | +8va(+ B C D +8va)+ E | F ..."

To check if braces are present, use the following function:

5.16 T_BAR

5.17 T_TUPLET

5.18 T_GCHORD

An auxiliary function helps with guitar chords. Each chord is made by three or more notes played togheter, the following function helps determine which notes are in a chord

For example, abcGChordNotes(1,notes), will fill the notes array with the values: 7,4,0 because the major chord contains the root note, the 3rd (that is at 4 semitones from the root note) and the 5th (that is at 7 semitones from the root note). Similarly, abcGChordNotes(8,notes) will fill notes with 10,7,3,0 because the 7th minor is made by the root note, the flat 3rd (3 semitones), the 5th (7 semitones) and the flat 7th (10 semitones).

5.19 T_CHORDSTART

Marks the start of a chord as in [CEG]. Chord notes will be reported one at the time.

5.20 T_CHORDEND

Marks the start of a chord as in [CEG]. 

5.21 T_GRACEAPP

Marks the start of an appoggiatura as in {acg}. Grace notes will be reported one at the time.

5.22 T_GRACEACC

Marks the start of an appoggiatura as in {/acg}.  Grace notes will be reported one at the time.

5.23 T_GRACEEND

Marks the end of grace notes as in {acg}.

5.24 T_SLURSTART

Marks the start of a slur as in (C D ^F). 

5.25 T_SLUREND

Marks the start of a slur as in (C D ^F). 

5.26 T_TIE

A tie as in C2-C.

5.27 T_ANNOTATION

5.28 T_INCLUDE

Signal the beginning of an inclusion.

You may want not to include that files (for example if you're searching for a tune within a file). In that case you may use the following function:

5.29 T_INCLUDE_EOF

Signal the end of the included file.

5.30 T_LYR_SYLLABLE

A syllable in a w: field.

5.31 T_LYR_BLANK

An empty syllable (*)
 

5.32 T_LYR_BAR

A bar occuring in a w: field.

5.33 T_LYR_SPACE

A space in a w: field.

5.34 T_LYR_HOLD

Holding the last syllable (_).

5.35 T_LYR_VERSE

5.36 T_LYR_CONTINUE

A continuation happened in a w: field. Use function in T_COMMENT to check the existance of comments.

5.37 T_SYM_BLANK

An empty symbol (*).

5.38 T_SYM_BAR

A bar occuring in a s: field.

5.39 T_SYM_VERSE

5.40 T_SYM_CONTINUE

A continuation happened in a s: field. Use function in T_COMMENT to check the existance of comments.

5.41 T_SYM_GCHORD

5.42 T_SYM_DECORATION

5.43 T_SYM_ANNOTATION

5.44 T_BROKENRIGHT

5.45 T_BROKENLEFT

5.46 T_XFIELD

Extended field (%%...).

5.47 T_OVERLAY

5.48 T_OVERLAYSTART

5.49 T_OVERLAYEND

5.50 T_DOVERLAY

5.51 T_DOVERLAYSTART

5.52 T_DOVERLAYEND

6. Builiding ABCp library

6.1 Makefile

TBW

6.2 Strings

ABCp is able to recognise and return unique codes for many strings used in the ABC syntax. In some case the usefulness of this has been challenged.

 For example, if you are using ABCp to create MIDI files, you are not interested in instructions like topmargin or setfont-1, having those string included in the library is nothing but a waste of space.

The strings.c file contain a mechanism to exclude sets of strings. If this is the case you can add -- EXCLUDE :PRINT: at the beginning of strings.c and those strings won't be included in the library.

6.3 yrx

To ease the creation of ABCp, I wrote a tool to match  regular expression based on the public domain regular expression package by Yigit Ozan.

You can find it in the tools directory.