abc.parser (abc4j API Documentation)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

abc4j API Specification

PREV PACKAGE NEXT PACKAGE

FRAMES NO FRAMES

Package abc.parser

This package contains classes for parsing tunes in abc notation.

See:
Description

Interface Summary
AbcFileParserListenerInterface	The interface to be implemented when parsing abc files.
TuneBookListenerInterface	This is the interface that should be implemented by any object that wants to listens to changes occured in a tunebook.
TuneParserListenerInterface	Interface that should be implemented by any object that listens to tunes parsing.

Class Summary
AbcFileParser	This class provides instances to parse files and streams using abc notation.
AbcFileParserAdapter	A default implementation of a file parser listener that does nothing.
AbcHeadersParser	This class provides parser instances that reduce the parsing scope to tunes headers (music is excluded).
AbcParserAbstract	Abstract class from which all abc notation parsers inherit.
AbcTokenType	This class defines all types of token that can be encountered while parsing a tune written using abc notation.
AbcToolkit	A class that provides convenience methods to manipulate abc related strings and their representation using objects from the `abc.notation` package.
AbcToolkit.DurationDescription
AsynchronousTuneParser	A parser that parses abc gammar into its own thread context.
InvalidTokenEvent	Event generated when an invalid token is encountered by a parser.
PositionableMultiNote	A multinote that encapsulates the information needed to locate where the abc information describing this multinote was positioned in the parsed stream.
PositionableNote	A note that encapsulates the information needed to locate where the abc information describing this note was positioned in the parsed stream.
TuneBook	This class provides an object representation of a tunebook.
TuneChangeEvent	Event used when a state changed occured on a tune.
TuneParser	A convenient class to ease the parsing of ONE tune.
TuneParserAdapter	An empty implementation of a tune parser listener that does nothing.

Package abc.parser Description

This package contains classes for parsing tunes in abc notation. It needs both scanner and abc.notation packages to work. The purpose of classes from this package is to extract from the abc notation all the necessary information needed to represent the music with objects belonging to the abc.notation.

abc4j propose several classes to instantiate abc parsers :

AbcFileParser : This class parses the abc stream and provides you Tune instances with header information (such as title, key etc...) and music part.
AbcHeadersParser : This class restricts the parsing to abc headers. This enables a faster parsing compared to the one done using AbcFileParser.
TuneParser : This class is usefull when you want to parse only one tune : you get the Tune result in a synchronous manner without any listener mechanism. Quite convenient in some cases...

Beside those standard ways to use parser, another class provides a more high level abstraction :

TuneBook : This class abstract an abc file as an object and encpasulates the parsing phasis in its implementation (hidden from client perspective). For a first use of the abc4j library, this class is the best starting point.

Some specific points should be pointed out during the translation from abc music notation to "standard" music notation :

Several different ways to express music using abc can lead to the same music.
For instance, the two following tunes :
```
X:1
T:dots example
L:1/8
K:D
d3d

X:2
T:dots example
L:1/4
K:D
d>d
```
describe the same melody : a dotted quarter note followed by eighth note. The consequence of this is that their representation in Note objects will be the same : the first note is a Note instance whose strict duration is Note.QUARTER and its countDots() will return 1.
The second note is a Note.EIGHTH without any dot.
Some abc note lengths may be impossible to translate into standard music notation.
For instance, let's consider the following tune :
```
X:1
T:impossible duration
L:1/8
K:D
d5
```
In such tune, the first note has a duration equals to 5 x eighth note. Such duration cannot be expressed in standard music notation with one single note : a quarter note is 4 times a eighth note, and a dotted quarter is 6 times a eighth note.
For now, the resulting note will be an instance of the Note class but with an "exotic" duration. One possible alternative would be to decompose this duration into several notes, but for now, the translation sticks to the approach "one abc note -> one Note instance".