Parsing
=======

Abjad provides a growing number of language parsers. 
The most important of these is a sophisticate LilyPond parser.

LilyPond Parsing
----------------

``lilypondparsertools.LilyPondParser`` parses a large, although incomplete, subset of LilyPond's syntax:

<abjad>
parser = lilypondparsertools.LilyPondParser()
</abjad>

The LilyPond parser understands notes, chords, skips and rests, 
including default durations and the ``q`` chord-repeat construct:

<abjad>
string = r"{ c'\longa r4. <d' fs' bff'> g q8 s1 c''\breve. }"
result = parser(string)
</abjad>

<abjad>
f(result)
</abjad>

<abjad>
show(result)
</abjad>

The LilyPond parser understands most spanners, articulations and dynamics too:

<abjad>
string = r'''\new Staff {
    c'8 \f \> (
    d' -_ [
    e' ^>
    f' \ppp \<
    g' \startTrillSpan \(
    a' \)
    b' ] \stopTrillSpan
    c'' ) \accent \sfz
}
'''
result = parser(string)
</abjad>

<abjad>
f(result)
</abjad>

<abjad>
show(result)
</abjad>

The LilyPond parser understands contexts and markup:

<abjad>
string = r'''\new Score <<
    \new Staff = "Treble Staff" {
        \new Voice = "Treble Voice" {
            c' ^\markup { \bold Treble! }
        }
    }
    \new Staff = "Bass Staff" {
        \new Voice = "Bass Voice" {
            \clef bass
            c, _\markup { \italic Bass! } 
        }
    }
>>
'''
result = parser(string)
</abjad>

<abjad>
f(result)
</abjad>

<abjad>
show(result)
</abjad>

The LilyPond parser even understands certain aspects of LilyPond file layouts, like header blocks:

<abjad>
string = r'''
\header {
    name = "Foo von Bar"
    composer = \markup { by \bold \name }
    title = \markup { The ballad of \name }
    tagline = \markup { "" }
}
\score {
    \new Staff {
        \time 3/4
        g' ( b' d'' )
        e''4. ( c''8 c'4 )
    }
}
'''
result = parser(string)
</abjad>

<abjad>
f(result)
</abjad>

<abjad>
show(result)
</abjad>

A small number of music functions are also supported, such as ``\relative``. Music functions which mutate 
the score during compilation, result in a normalized Abjad score structure.  That is, the resulting Abjad 
structure corresponds to the music as it appears on the page:

<abjad>
string = r'''\new Staff \relative c { c32 d e f g a b c d e f g a b c d e f g a b c }'''
result = parser(string)
</abjad>

<abjad>
f(result)
</abjad> 

<abjad>
show(result)
</abjad>

RhythmTree Parsing
------------------

``rhythmtreetools.RhythmTreeParser`` parses a microlanguage resembling Ircam's RTM-style LISP syntax, and 
generates a sequence of RhythmTree structures, which can be furthered manipulated by composers, before 
being converted into Abjad score object:

<abjad>
parser = rhythmtreetools.RhythmTreeParser()
</abjad>

<abjad>
string = '(1 (1 (2 (1 1 1)) 2))'
result = parser(string)
result[0]
</abjad>

<abjad>
tuplet = result[0]((1, 4))[0]
f(tuplet)
</abjad>

<abjad>
staff = stafftools.RhythmicStaff([tuplet])
</abjad>

<abjad>
show(staff, docs=True)
</abjad>

"Reduced-Ly" Parsing
--------------------

``lilypondparsertools.ReducedLyParser`` parses the "reduced-ly" microlanguage, whose syntax combines a very 
small subset of LilyPond syntax, along with affordances for generating various types of Abjad containers, and 
speedups for rapidly notating notes and rests without needing to specify pitches.  It used mainly for creating
Abjad documentation:

<abjad>
parser = lilypondparsertools.ReducedLyParser()
</abjad>

<abjad>
string = "| 4/4 c' d' e' f' || 3/8 r8 g'4 |"
result = parser(string)
</abjad>

<abjad>
f(result)
</abjad>

<abjad>
show(result)
</abjad>
