Documents‎ > ‎

Tokens


The following code fragment shows how to extract tokens from a string containing a piece of ABC music:

abcScanner *scn;

scn = abcScannerNew(str,"X:1\nABC");
while
((tok = abcNextToken(scn)) != T_EOF) {
...
your code here ...
}

scn = abcScannerFree(scn);


The token components can be retrieved the following functions:

abcTokenStart(scn,k)  returns a pointer to the beginning of the token text
abcTokenLen(scn,k)    returns the length of the token text
abcTokenEnd(scn,k)    returns a pointer to the end of the token text

A value of 0 for k always refer to the entire matched text. What is returned on other values of k depends on the token. For example for a T_NOTE token, 5 gives you the base pitch (A-G or a-g).

Details for each tokens,  including the helpers functions that can be called to get more information on the token, are given below:


T_ANNOTATION T_BAR T_INCLUDEPATH
T_BEGINTEXT
T_BREAKLINE T_BROKENLEFT T_BROKENRIGHT T_CHORD
T_CHORDEND
T_MEASUREREPEAT
T_CONTINUE T_DECORATION
T_EMPTYLINE T_ENDHISTORY T_ENDING T_ENDLINE
T_ENDTEXT T_EOF T_EXTFIELD T_FIELD
T_GCHORD T_GRACE T_GRACEEND T_IGNORE
T_INFIELD T_LYRICS T_NONE T_NOTE
T_OVLEND T_OVLRESET T_OVLSTART T_PRAGMA
T_REST T_SLUREND T_SLURSTART T_SPACER
T_SYLLABLE T_SYMBOLS T_TEXT T_TIE
T_TUPLET T_UNKNOWN T_USERSYMBOL T_VERSE
T_WHITESPACE



T_ANNOTATION (top)

Strings

 1 The positioning character ('<', '>', '^', '_' or '@'). May be empty.
 2 If the position character is '@', the x coordinate. May be empty.
 3 If the position character is '@', the y coordinate. May be empty.
 4 The annotation text

Functions

char *abcAnnotationTextStart(abcScanner *s)
int abcAnnotationTextLen(abcScanner *s)

  Get the annotation text

float abcAnnotationPosX(abcScanner *s)
float abcAnnotationPosY(abcScanner *s)
  Get the annotation position coordinates. If the position character is not '@', 0.0 is returned

char abcAnnotationPos(abcScanner *s)
  The positioning character. It may be '>', '<', '^', '_', '@' or '?' if there's none.


T_BAR (top)

Strings

 1 The repetition characters (':') before the bar. May be empty.
 2 The dot, if the bar is dotted. May be empty.
 3 The sequence of '[', '|', and ']' that makes the bar. May be empty.
 4 The repetition characters (':') after the bar. May be empty.

Functions

char *abcBarStart(abcScanner *s)
int abcBarLen(abcScanner *s)
  Get the bar string.

int abcBarRepeatBefore(abcScanner *s) int abcBarRepeatAfter(abcScanner *s)
  The number of dots before and after the bar.

int abcBarRepeatBefore(abcScanner *s) int abcBarRepeatAfter(abcScanner *s)
  The number of dots before and after the bar.

int abcBarDotted(abcScanner *s)
  Returns a non zero value if the bar is dotted ('.|',' .[|', ':', ...)

int abcBarInvisible(abcScanner *s)
  Returns a non zero value if the bar one of the invisible bars ('[|]', '[]')


T_BEGINTEXT (top)

Strings

 1 The text attributes (e.g. "justify")

Functions


T_BREAKLINE (top)

None

T_BROKENLEFT (top)

Functions

int abcBroken(abcScanner *s)
  Returns the number of '<' symbols


T_BROKENRIGHT (top)

Functions

int abcBroken(abcScanner *s)
  Returns the number of '>' symbols


T_CHORD (top)

Represent the start of a chord (e.g. '[CEG]'). Each note will be reported separately as T_NOTE tokens.


T_CHORDEND (top)

Represent the end of a chord. It may be followed by a duration like notes (e.g. '[CEG]3/2' ).

Strings

 1 The numerator for chord duration
 2 The list of '/' for duration
 3 The denominator for chord duration

Functions

abcFraction abcChordDuration(abcScanner *scn)
  Returns a fraction representing the duration of the chord. Use the abcNumerator() and abcDenominator() functions to get the actual numbers.


T_CONTINUE (top)

None

T_DECORATION (top)

 1 The decoration name. '*' is blank in a line of symbols.
 2 The character ')' or '(' if present as in:  +trill(+  ... +trill)+


T_EMPTYLINE (top)

 1 Spaces before the end of the line. May be empty.


T_ENDHISTORY (top)

 1 The string "H:"


T_ENDING (top)

 1 The numbers representing the times the ending should be played (e.g. 1-3) or a quoted string (e.g. "in ultimo"). In case of a string the quotes are included.


T_ENDLINE (top)

None


T_ENDTEXT (top)

This is compatible with T_TEXT

 1 The character '%' if it's a line comment, or 'r' if it's an inline field remark
 2 The text without trailing blank


T_EOF (top)

None


T_EXTFIELD (top)

 1 The name of the field (e.g. MIDI or abc-version) or the name of the application if string 2 is defined (see section 11.5)
 2 The name of the field if it's an application specific field
 3 The field parameters


T_FIELD (top)

 1 The field character (e.g. 'K')
 2 The field parameters


T_GCHORD (top)

 1 The chord string (excluding quotes).


T_GRACE (top)

 1 The character '/' if it's an acciaccatura


T_GRACEEND (top)

None



T_IGNORE (top)

 1 The string to be ignored. Always use this one rather that the string 0.


T_INCLUDE (top)

 1 The name of the file to include (if not enclosed in quotes)
 2 The name of the file to include (if enclosed in quotes)
 3 Any other text on the field line
 4 The end of the line



T_INCLUDEND (top)

None


T_INCLUDPATH (top)


 1 The character '+' if the path is to be added to the current one
 2 The path




T_INFIELD (top)

 1 The field letter
 2 The field parameters (with leading blanks and ending newline removed)


T_LYRICS (top)

None

T_MEASUREREPEAT (top)

None

T_NONE (top)

None


T_NOTE (top)

 1 The accidentals ('^','_' and '='). Includes microtones
 2 The base pitch (A-G or a-g)
 3 The octave (list of ',' and ''' )
 4 The numerator for note duration
 5 The list of '/' for duration
 6 The denominator for note duration


T_OVLEND (top)

 1 The list of '&'


T_OVLRESET (top)

 1 The list of '&'


T_OVLSTART (top)

 1 The list of '&'


T_PRAGMA (top)

 1 The pragma directive (e.g. ifdef)
 2 The parameters (excluding leading blanks and ending newline)


T_REST (top)

 1 The rest type ('z', 'Z' or 'x')
 2 The numerator for rest duration
 3 The list of '/' for duration
 4 The denominator for rest duration


T_SLUREND (top)

None


T_SLURSTART (top)

 1 The dot, if the slur is dotted. May be empty.
 2 The slur direction (',' or '''). May be empty.


T_SPACER (top)

 1 The space amount. May be empty.


T_SYLLABLE (top)

 1 The syllable characters (it any)   
 2 A dash ('-')  if present    
 3 A sequence of holding symbols ('_')


T_SYMBOLS (top)

None



T_TEXT (top)

 1 A strings that depends on the the type of the text and on the state it is found
 2 The actual text line with no trailing blanks and ending newline
 3 The new line. May be empty.


T_TIE (top)

 1 The dot, if the tie is dotted. May be empty.
 2 The tie direction (',' or '''). May be empty.



T_TUPLET (top)
A generic tuplet "(p:q:r"

 1  p
 2  q
 3  r


T_UNKNOWN (top)

None



T_USERSYMBOL (top)

None



T_VERSE (top)

 1 The verse number   
 2 The separator (':', '.' or ')')


T_WHITESPACE (top)

 1 The sequence of blank characters