Source code for ly.music

# This file is part of python-ly, https://pypi.python.org/pypi/python-ly
#
# Copyright (c) 2014 - 2015 by Wilbert Berendsen
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
# See http://www.gnu.org/licenses/ for more information.

r"""
An api to read music from the tokens of a ly.document.Document into a tree
structure.

This is meant to quickly read music from a document, to perform
modifications on the document, and to interpret music and markup and to
convert or export it to other formats.

All nodes are a subclass of items.Item, (which inherits from node.WeakNode).

Tree structures are created from nested LilyPond structures, markup and
scheme code. Some Item types have special methods to query information. The
Music type, for example, has a length() method that returns the duration of
the music fragment.

Using the Music.events() method and the events module, it is possible to
iterate in musical time over the music tree, e.g. to convert music to
another format.

This package is not yet capable to construct documents entirely from scratch.
This needs to be developed. Until that time, the ly.dom module can be used
instead.

Some Item types can have a list of child items, but the tree structure is as
linear as possible.

A convenience function is available to create a ly.music.items.Document
instance for the specified ly.document.Document.

Here is an example::

    >>> import ly.document
    >>> import ly.music
    >>> d=ly.document.Document(r'''
    \version "2.18.0"

    music = \relative {
      \time 4/4
      \key d \minor
      d4 e f g
      a g f e
      d2
    }

    \score {
      \new Staff <<
        \music
      >>
    }
    ''')
    >>> m=ly.music.document(d)
    >>> print m.dump()
    <Document>
      <Version u'\\version'>
        <String u'"'>
      <Assignment u'music'>
        <Relative u'\\relative'>
          <MusicList u'{'>
            <TimeSignature u'\\time'>
            <KeySignature u'\\key'>
              <Note u'd'>
              <Command u'\\minor'>
            <Note u'd'>
            <Note u'e'>
            <Note u'f'>
            <Note u'g'>
            <Note u'a'>
            <Note u'g'>
            <Note u'f'>
            <Note u'e'>
            <Note u'd'>
      <Score u'\\score'>
        <Context u'\\new'>
          <MusicList u'<<'>
            <UserCommand u'\\music'>
    >>> m[2][0][0]
    <MusicList u'<<'>
    >>> m[2][0][0].length()
    Fraction(5, 2)
    >>>

"""

import ly.document


def document(doc):
    """Return a music.items.Document instance for the ly.document.Document."""
    from . import items
    return items.Document(doc)