.. _moduleAbc.base:

music21.abc.base
================

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED.  Edit the .py file directly

.. module:: music21.abc.base

Objects and resources for processing ABC data. ABC conversion from a file or URL to a :class:`~music21.stream.Stream` is available through the music21 converter module's :func:`~music21.converter.parse` function. 

>>> from music21 import *
>>> abcScore = converter.parse('/users/ariza/myScore.abc')


Low level ABC conversion is facilitated by the objects in this module and :func:`music21.abc.translate.abcToStreamScore`. 


.. function:: mergeLeadingMetaData(barHandlers)

    Given a list of ABCHandlerBar, ruturn a list of ABCHandlerBar objects, where leading metadata is merged, if possible, with the bar data preceding. This is often needed for processing measures. 

ABCBar
------

Inherits from: :class:`~music21.abc.base.ABCToken`

.. class:: ABCBar(src)


    **ABCBar** **methods**

        .. method:: getBarObject()

            Return a music21 bar object 

            >>> from music21 import *
            >>> ab = abc.ABCBar('|:')
            >>> ab.parse()
            >>> post = ab.getBarObject()

        .. method:: isRegular()

            Return True if this is a regular, single, light bar line. 

            >>> from music21 import *
            >>> ab = abc.ABCBar('|')
            >>> ab.parse()
            >>> ab.isRegular()
            True 

        .. method:: isRepeat()

            No documentation. 

        .. method:: parse()

            Assign the bar-type based on the source string. 

            >>> from music21 import *
            >>> ab = abc.ABCBar('|')
            >>> ab.parse()
            >>> ab.barType
            'barline' 
            >>> ab.barStyle
            'regular' 
            >>> ab = abc.ABCBar('||')
            >>> ab.parse()
            >>> ab.barType
            'barline' 
            >>> ab.barStyle
            'light-light' 
            >>> ab = abc.ABCBar('|:')
            >>> ab.parse()
            >>> ab.barType
            'repeat' 
            >>> ab.barStyle
            'heavy-light' 
            >>> ab.repeatForm
            'start' 

        Methods inherited from :class:`~music21.abc.base.ABCToken`: :meth:`~music21.abc.base.ABCToken.preParse`, :meth:`~music21.abc.base.ABCToken.stripComment`


ABCBrokenRhythmMarker
---------------------

Inherits from: :class:`~music21.abc.base.ABCToken`

.. class:: ABCBrokenRhythmMarker(src)



ABCChord
--------

Inherits from: :class:`~music21.abc.base.ABCNote`, :class:`~music21.abc.base.ABCToken`

.. class:: ABCChord(src)

    A representation of an ABC Chord, which contains within its delimiters individual notes. A subclass of ABCNote. 

    


ABCFile
-------



.. class:: ABCFile()

    ABC File access 

    

    **ABCFile** **methods**

        .. method:: close()

            No documentation. 

        .. method:: extractReferenceNumber(strSrc, number)

            Extract a single reference number from many defined in a file. This permits loading a single work from a collection/opus without parsing the entire file. 

        .. method:: open(filename)

            Open a file for reading 

        .. method:: openFileLike(fileLike)

            Assign a file-like object, such as those provided by StringIO, as an open file object. 

            >>> fileLikeOpen = StringIO.StringIO()

        .. method:: read(number=None)

            Read a file. Note that this calls readstring, which processes all tokens. If `number` is given, a work number will be extracted if possible. 

        .. method:: readstr(strSrc, number=None)

            Read a string and process all Tokens. Returns a ABCHandler instance. 


ABCHandler
----------



.. class:: ABCHandler()


    **ABCHandler** **properties**

        .. attribute:: tokens

            Get or set tokens for this Handler 

    **ABCHandler** **methods**

        .. method:: definesMeasures()

            Return True if this token structure defines Measures in a normal Measure form. 

            >>> from music21 import *
            >>> abcStr = 'M:6/8\nL:1/8\nK:G\nV:1 name="Whistle" snm="wh"\nB3 A3 | G6 | B3 A3 | G6 ||\nV:2 name="violin" snm="v"\nBdB AcA | GAG D3 | BdB AcA | GAG D6 ||\nV:3 name="Bass" snm="b" clef=bass\nD3 D3 | D6 | D3 D3 | D6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> True == ah.definesMeasures()
            True 
            >>> abcStr = 'M:6/8\nL:1/8\nK:G\nB3 A3 G6 B3 A3 G6'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> False == ah.definesMeasures()
            True 

            

        .. method:: definesReferenceNumbers()

            Return True if this token structure defines more than 1 reference number. 

            >>> from music21 import *
            >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> ah.definesReferenceNumbers() # only one returns false
            False 
            >>> from music21 import *
            >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||\nX:6\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> ah.definesReferenceNumbers() # only one returns false
            True 

        .. method:: getReferenceNumber()

            If tokens are processed, get the first reference number defined. 

            >>> from music21 import *
            >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> ah.getReferenceNumber()
            '5' 

        .. method:: getTitle()

            If tokens are processed, get the first title tag. Used for testing. 

        .. method:: hasNotes()

            If tokens are processed, return True of ABCNote or ABCChord classes are defined 

            >>> from music21 import *
            >>> abcStr = 'M:6/8\nL:1/8\nK:G\n'
            >>> ah1 = abc.ABCHandler()
            >>> junk = ah1.process(abcStr)
            >>> ah1.hasNotes()
            False 
            >>> abcStr = 'M:6/8\nL:1/8\nK:G\nc1D2'
            >>> ah2 = abc.ABCHandler()
            >>> junk = ah2.process(abcStr)
            >>> ah2.hasNotes()
            True 

        .. method:: process(strSrc)

            No documentation. 

        .. method:: splitByMeasure()

            Divide a token list by Measures, also defining start and end bars of each Measure. If a component does not have notes, leave as an empty bar. This is often done with leading metadata. Returns a list of ABCHandlerBar instances. The first usually defines only Metadata 

        .. method:: splitByReferenceNumber()

            Split tokens by reference numbers. Returns a dictionary of ABCHandler instances, where the reference number is used to access the music. If no reference numbers are defined, the tune is available under the dictionary entry None. 

            >>> from music21 import *
            >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> len(ah)
            14 
            >>> ahDict = ah.splitByReferenceNumber()
            >>> len(ahDict[5].tokens)
            14 

        .. method:: splitByVoice()

            Given a processed token list, look for voices. If voices exist, split into parts: common metadata, then next voice, next voice, etc. Each part is returned as a ABCHandler instance. 

            >>> from music21 import *
            >>> abcStr = 'M:6/8\nL:1/8\nK:G\nV:1 name="Whistle" snm="wh"\nB3 A3 | G6 | B3 A3 | G6 ||\nV:2 name="violin" snm="v"\nBdB AcA | GAG D3 | BdB AcA | GAG D6 ||\nV:3 name="Bass" snm="b" clef=bass\nD3 D3 | D6 | D3 D3 | D6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> tokenColls = ah.splitByVoice()
            >>> [t.src for t in tokenColls[0].tokens] # common headers are first
            ['M:6/8', 'L:1/8', 'K:G'] 
            >>> # then each voice
            >>> [t.src for t in tokenColls[1].tokens]
            ['V:1 name="Whistle" snm="wh"', 'B3', 'A3', '|', 'G6', '|', 'B3', 'A3', '|', 'G6', '||'] 
            >>> [t.src for t in tokenColls[2].tokens]
            ['V:2 name="violin" snm="v"', 'B', 'd', 'B', 'A', 'c', 'A', '|', 'G', 'A', 'G', 'D3', '|', 'B', 'd', 'B', 'A', 'c', 'A', '|', 'G', 'A', 'G', 'D6', '||'] 
            >>> [t.src for t in tokenColls[3].tokens]
            ['V:3 name="Bass" snm="b" clef=bass', 'D3', 'D3', '|', 'D6', '|', 'D3', 'D3', '|', 'D6', '||'] 

            

        .. method:: tokenProcess()

            Process all token objects. First, call preParse(), then do cointext assignments, then call parse(). 

        .. method:: tokenize(strSrc)

            Walk the abc string, creating ABC objects along the way. This may be called separately from process(), in the case that pre/post parse processing is not needed. 


ABCHandlerBar
-------------

Inherits from: :class:`~music21.abc.base.ABCHandler`

.. class:: ABCHandlerBar()

    A Handler specialized for storing bars. All left and right bars are collected and assigned to attributes. 

    **ABCHandlerBar** **attributes**

        Attributes without Documentation: `leftBarToken`, `rightBarToken`

    **ABCHandlerBar** **properties**

        Properties inherited from :class:`~music21.abc.base.ABCHandler`: :attr:`~music21.abc.base.ABCHandler.tokens`

    **ABCHandlerBar** **methods**

        Methods inherited from :class:`~music21.abc.base.ABCHandler`: :meth:`~music21.abc.base.ABCHandler.definesMeasures`, :meth:`~music21.abc.base.ABCHandler.definesReferenceNumbers`, :meth:`~music21.abc.base.ABCHandler.getReferenceNumber`, :meth:`~music21.abc.base.ABCHandler.getTitle`, :meth:`~music21.abc.base.ABCHandler.hasNotes`, :meth:`~music21.abc.base.ABCHandler.process`, :meth:`~music21.abc.base.ABCHandler.splitByMeasure`, :meth:`~music21.abc.base.ABCHandler.splitByReferenceNumber`, :meth:`~music21.abc.base.ABCHandler.splitByVoice`, :meth:`~music21.abc.base.ABCHandler.tokenProcess`, :meth:`~music21.abc.base.ABCHandler.tokenize`


ABCMetadata
-----------

Inherits from: :class:`~music21.abc.base.ABCToken`

.. class:: ABCMetadata(src=)


    **ABCMetadata** **attributes**

        Attributes without Documentation: `tag`, `data`

        Attributes inherited from :class:`~music21.abc.base.ABCToken`: :attr:`~music21.abc.base.ABCToken.src`

    **ABCMetadata** **methods**

        .. method:: getClefObject()

            Extract any clef parameters stored in the key metadata token. Assume that a clef definition suggests a transposition. Return both the Clef and the transposition. 

            >>> from music21 import *
            >>> am = abc.ABCMetadata('K:Eb Lydian')
            >>> am.preParse()
            >>> am._getKeySignatureParameters()
            (-2, 'lydian') 

            

        .. method:: getDefaultQuarterLength()

            If there is a quarter length representation available, return it as a floating point value 

            >>> from music21 import *
            >>> am = abc.ABCMetadata('L:1/2')
            >>> am.preParse()
            >>> am.getDefaultQuarterLength()
            2.0 
            >>> am = abc.ABCMetadata('L:1/8')
            >>> am.preParse()
            >>> am.getDefaultQuarterLength()
            0.5 
            >>> am = abc.ABCMetadata('M:C|')
            >>> am.preParse()
            >>> am.getDefaultQuarterLength()
            0.5 
            >>> am = abc.ABCMetadata('M:2/4')
            >>> am.preParse()
            >>> am.getDefaultQuarterLength()
            0.25 
            >>> am = abc.ABCMetadata('M:6/8')
            >>> am.preParse()
            >>> am.getDefaultQuarterLength()
            0.5 

            

        .. method:: getKeySignatureObject()

            Return a music21 :class:`~music21.key.KeySignature` object for this metadata tag. 

            >>> from music21 import *
            >>> am = abc.ABCMetadata('K:G')
            >>> am.preParse()
            >>> ks = am.getKeySignatureObject()
            >>> ks
            <music21.key.KeySignature of 1 sharp> 

        .. method:: getTimeSignatureObject()

            Return a music21 :class:`~music21.meter.TimeSignature` object for this metadata tag. 

            >>> from music21 import *
            >>> am = abc.ABCMetadata('M:2/2')
            >>> am.preParse()
            >>> ts = am.getTimeSignatureObject()
            >>> ts
            <music21.meter.TimeSignature 2/2> 

        .. method:: isComposer()

            Returns True if the tag is "C" for composer, False otherwise. 

        .. method:: isDefaultNoteLength()

            Returns True if the tag is "L", False otherwise. 

        .. method:: isKey()

            Returns True if the tag is "K", False otherwise. Note that in some cases a Key will encode clef information. 

        .. method:: isMeter()

            Returns True if the tag is "M" for meter, False otherwise. 

        .. method:: isOrigin()

            Returns True if the tag is "O" for origin, False otherwise. This value is set in the Metadata `localOfComposition` of field. 

        .. method:: isReferenceNumber()

            Returns True if the tag is "X", False otherwise. 

            >>> from music21 import *
            >>> x = abc.ABCMetadata('X:5')
            >>> x.preParse()
            >>> x.tag
            'X' 
            >>> x.isReferenceNumber()
            True 

        .. method:: isTitle()

            Returns True if the tag is "T" for title, False otherwise. 

        .. method:: isVoice()

            Returns True if the tag is "V", False otherwise. 

        .. method:: parse()

            No documentation. 

        .. method:: preParse()

            Called before contextual adjustments and needs to have access to data.  Divides a token into .tag (a single capital letter or w) and .data representations. 

            >>> from music21 import *
            >>> x = abc.ABCMetadata('T:tagData')
            >>> x.preParse()
            >>> x.tag
            'T' 
            >>> x.data
            'tagData' 

        Methods inherited from :class:`~music21.abc.base.ABCToken`: :meth:`~music21.abc.base.ABCToken.stripComment`


ABCNote
-------

Inherits from: :class:`~music21.abc.base.ABCToken`

.. class:: ABCNote(src=)

    A model of an ABCNote. General usage requires multi-pass processing. After being tokenized, each ABCNote needs a number of attributes updates. Attributes to be updated after tokenizing, and based on the linear sequence of tokens: `inBar`, `inBeam`, `inSlur`, `inGrace`, `activeDefaultQuarterLength`, `brokenRhythmMarker`, and `activeKeySignature`. The `chordSymbols` list stores one or more chord symbols (ABC calls these guitar chords) associated with this note. This attribute is updated when parse() is called. 

    **ABCNote** **attributes**

        Attributes without Documentation: `brokenRhythmMarker`, `quarterLength`, `activeKeySignature`, `inGrace`, `chordSymbols`, `inBeam`, `pitchName`, `inSlur`, `activeTuplet`, `inBar`, `isRest`, `accidentalDisplayStatus`, `activeDefaultQuarterLength`

        Attributes inherited from :class:`~music21.abc.base.ABCToken`: :attr:`~music21.abc.base.ABCToken.src`

    **ABCNote** **methods**

        .. method:: parse(forceDefaultQuarterLength=None, forceKeySignature=None)

            No documentation. 

        Methods inherited from :class:`~music21.abc.base.ABCToken`: :meth:`~music21.abc.base.ABCToken.preParse`, :meth:`~music21.abc.base.ABCToken.stripComment`


ABCToken
--------



.. class:: ABCToken(src=)

    ABC processing works with a multi-pass procedure. The first pass breaks the data stream into a list of ABCToken objects. ABCToken objects are specialized in subclasses. The multi-pass procedure is conducted by an ABCHandler object. The ABCHandler.tokenize() method breaks the data stream into ABCToken objects. The :meth:`~music21.abc.base.ABCHandler.tokenProcess` method first calls the :meth:`~music21.abc.base.ABCToken.preParse` method on each token, then does contextual adjustments to all tokens, then calls :meth:`~music21.abc.base.ABCToken.parse` on all tokens. The source ABC string itself is stored in self.src 

    

    **ABCToken** **attributes**

        Attributes without Documentation: `src`

    **ABCToken** **methods**

        .. method:: parse()

            Dummy method that reads self.src and loads attributes. It is called after contextual adjustments. It is designed to be subclassed or overridden. 

        .. method:: preParse()

            Dummy method that is called before contextual adjustments. Designed to be subclassed or overridden. 

        .. method:: stripComment(strSrc)

            removes ABC-style comments from a string: 

            >>> from music21 import *
            >>> ao = abc.ABCToken()
            >>> ao.stripComment('asdf')
            'asdf' 
            >>> ao.stripComment('asdf%234')
            'asdf' 
            >>> ao.stripComment('asdf  %     234')
            'asdf  ' 
            >>> ao.stripComment('[ceg]% this chord appears 50% more often than other chords do')
            '[ceg]' 


ABCTuplet
---------

Inherits from: :class:`~music21.abc.base.ABCToken`

.. class:: ABCTuplet(src)

    ABCTuplet tokens always precede the notes they describe. In ABCHandler.tokenProcess(), rhythms are adjusted. 

    

    **ABCTuplet** **methods**

        .. method:: updateNoteCount(durationActual=None, durationNormal=None)

            Update the note count of notes that are affected by this tuplet. 

        .. method:: updateRatio(keySignatureObj=None)

            Cannot be called until local meter context is established 

            >>> from music21 import *
            >>> at = abc.ABCTuplet('(3')
            >>> at.updateRatio()
            >>> at.numberNotesActual, at.numberNotesNormal
            (3, 2) 
            >>> at = abc.ABCTuplet('(5')
            >>> at.updateRatio()
            >>> at.numberNotesActual, at.numberNotesNormal
            (5, 2) 
            >>> at = abc.ABCTuplet('(5')
            >>> at.updateRatio(meter.TimeSignature('6/8'))
            >>> at.numberNotesActual, at.numberNotesNormal
            (5, 3) 

        Methods inherited from :class:`~music21.abc.base.ABCToken`: :meth:`~music21.abc.base.ABCToken.parse`, :meth:`~music21.abc.base.ABCToken.preParse`, :meth:`~music21.abc.base.ABCToken.stripComment`


