.. _moduleText:

music21.text
============

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

.. module:: music21.text

Utility routines for processing text in scores and other musical objects.




.. function:: assembleLyrics(streamIn, lineNumber=1)


    Concatenate text from a stream. The Stream is automatically flattened.

    The `lineNumber` parameter determines which line of text is assembled.



    >>> from music21 import *
    >>> s = stream.Stream()
    >>> n1 = note.Note()
    >>> n1.lyric = "Hi"
    >>> n2 = note.Note()
    >>> n2.lyric = "there"
    >>> s.append(n1)
    >>> s.append(n2)
    >>> text.assembleLyrics(s)
    'Hi there'



.. function:: postpendArticle(src, language=None)

    Given a text string, if an article is found in a leading position, place it at the end with a comma.



    >>> from music21 import *
    >>> text.postpendArticle('The Ale is Dear')
    'Ale is Dear, The'
    >>> text.postpendArticle('The Ale is Dear', 'en')
    'Ale is Dear, The'
    >>> text.postpendArticle('The Ale is Dear', 'it')
    'The Ale is Dear'
    >>> text.postpendArticle('Il Combattimento di Tancredi e Clorinda', 'it')
    'Combattimento di Tancredi e Clorinda, Il'



.. function:: prependArticle(src, language=None)

    Given a text string, if an article is found in a trailing position with a comma, place the article in front and remove the comma.



    >>> from music21 import *
    >>> text.prependArticle('Ale is Dear, The')
    'The Ale is Dear'
    >>> text.prependArticle('Ale is Dear, The', 'en')
    'The Ale is Dear'
    >>> text.prependArticle('Ale is Dear, The', 'it')
    'Ale is Dear, The'
    >>> text.prependArticle('Combattimento di Tancredi e Clorinda, Il', 'it')
    'Il Combattimento di Tancredi e Clorinda'



TextBox
-------

Inherits from: :class:`~music21.base.Music21Object`, :class:`~music21.base.JSONSerializer`, :class:`~music21.text.TextFormat`

.. class:: TextBox(content=None, x=500, y=500)

    A TextBox is arbitrary text that might be positioned anywhere on a page, independent of notes or staffs. A page attribute specifies what page this text is found on; positionVertical and positionHorizontal position the text from the bottom left corner in units of tenths.

    This object is similar to the TextExpression object, but does not have as many position parameters, enclosure attributes, and the ability to convert to RepeatExpressions and TempoTexts.



    >>> from music21 import text, stream
    >>> y = 1000 # set a fixed vertical distance
    >>> s = stream.Stream()
    >>> # specify character, x position, y position
    >>> tb = text.TextBox('m', 250, y)
    >>> tb.size = 40
    >>> tb.alignVertical = 'bottom'
    >>> s.append(tb)
    >>> tb = text.TextBox('u', 300, y)
    >>> tb.size = 60
    >>> tb.alignVertical = 'bottom'
    >>> s.append(tb)
    >>> tb = text.TextBox('s', 550, y)
    >>> tb.size = 120
    >>> tb.alignVertical = 'bottom'
    >>> s.append(tb)
    >>> tb = text.TextBox('ic', 700, y)
    >>> tb.alignVertical = 'bottom'
    >>> tb.size = 20
    >>> tb.style = 'italic'
    >>> s.append(tb)
    >>> tb = text.TextBox('21', 850, y)
    >>> tb.alignVertical = 'bottom'
    >>> tb.size = 80
    >>> tb.weight = 'bold'
    >>> tb.style = 'italic'
    >>> s.append(tb)
    >>> s.show()




    .. image:: images/textBoxes-01.*
            :width: 600





    **TextBox** **attributes**

        .. attribute:: classSortOrder

            Property which returns an number (int or otherwise)
            depending on the class of the Music21Object that
            represents a priority for an object based on its class alone --
            used as a tie for stream sorting in case two objects have the
            same offset and priority.  Lower numbers are sorted to the left
            of higher numbers.  For instance, Clef, KeySignature, TimeSignature
            all come (in that order) before Note.

            All undefined classes have classSortOrder of 20 -- same as note.Note



            >>> from music21 import *
            >>> tc = clef.TrebleClef()
            >>> tc.classSortOrder
            0
            >>> ks = key.KeySignature(3)
            >>> ks.classSortOrder
            1


            New classes can define their own default classSortOrder



            >>> class ExampleClass(base.Music21Object):
            ...     classSortOrderDefault = 5
            ...
            >>> ec1 = ExampleClass()
            >>> ec1.classSortOrder
            5



        Attributes inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.isSpanner`, :attr:`~music21.base.Music21Object.isStream`, :attr:`~music21.base.Music21Object.isVariant`, :attr:`~music21.base.Music21Object.id`, :attr:`~music21.base.Music21Object.groups`, :attr:`~music21.base.Music21Object.hideObjectOnPrint`

    **TextBox** **properties**

        .. attribute:: alignHorizontal


            Get or set the horicontal align.



            >>> from music21 import *
            >>> te = text.TextBox('testing')
            >>> te.alignHorizontal = 'right'
            >>> te.alignHorizontal
            'right'




        .. attribute:: alignVertical


            Get or set the vertical align. Valid values are top, middle, bottom, and baseline



            >>> from music21 import *
            >>> te = text.TextBox('testing')
            >>> te.alignVertical = 'top'
            >>> te.alignVertical
            'top'



        .. attribute:: content

            Get or set the the content.



            >>> from music21 import *
            >>> te = text.TextBox('testing')
            >>> te.content
            'testing'
            >>> te.justify = 'center'
            >>> te.justify
            'center'




        .. attribute:: page

            Get or set the the page number. The first page (page 1) is the default.



            >>> from music21 import *
            >>> te = text.TextBox('testing')
            >>> te.content
            'testing'
            >>> te.page
            1



        .. attribute:: positionHorizontal


            Get or set the vertical position.



            >>> from music21 import *
            >>> te = text.TextBox('testing')
            >>> te.positionHorizontal = 200
            >>> te.positionHorizontal
            200




        .. attribute:: positionVertical


            Get or set the vertical position.



            >>> from music21 import *
            >>> te = text.TextBox('testing')
            >>> te.positionVertical = 1000
            >>> te.positionVertical
            1000



        Properties inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.activeSite`, :attr:`~music21.base.Music21Object.beat`, :attr:`~music21.base.Music21Object.beatDuration`, :attr:`~music21.base.Music21Object.beatStr`, :attr:`~music21.base.Music21Object.beatStrength`, :attr:`~music21.base.Music21Object.classes`, :attr:`~music21.base.Music21Object.derivationHierarchy`, :attr:`~music21.base.Music21Object.duration`, :attr:`~music21.base.Music21Object.isGrace`, :attr:`~music21.base.Music21Object.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`, :attr:`~music21.base.Music21Object.seconds`

        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

        Properties inherited from :class:`~music21.text.TextFormat`: :attr:`~music21.text.TextFormat.justify`, :attr:`~music21.text.TextFormat.letterSpacing`, :attr:`~music21.text.TextFormat.size`, :attr:`~music21.text.TextFormat.style`, :attr:`~music21.text.TextFormat.weight`

    **TextBox** **methods**

        Methods inherited from :class:`~music21.base.Music21Object`: :meth:`~music21.base.Music21Object.searchActiveSiteByAttr`, :meth:`~music21.base.Music21Object.getContextAttr`, :meth:`~music21.base.Music21Object.setContextAttr`, :meth:`~music21.base.Music21Object.addContext`, :meth:`~music21.base.Music21Object.addLocation`, :meth:`~music21.base.Music21Object.addLocationAndActiveSite`, :meth:`~music21.base.Music21Object.freezeIds`, :meth:`~music21.base.Music21Object.getAllContextsByClass`, :meth:`~music21.base.Music21Object.getCommonSiteIds`, :meth:`~music21.base.Music21Object.getCommonSites`, :meth:`~music21.base.Music21Object.getContextByClass`, :meth:`~music21.base.Music21Object.getOffsetBySite`, :meth:`~music21.base.Music21Object.getSiteIds`, :meth:`~music21.base.Music21Object.getSites`, :meth:`~music21.base.Music21Object.getSpannerSites`, :meth:`~music21.base.Music21Object.hasContext`, :meth:`~music21.base.Music21Object.hasSite`, :meth:`~music21.base.Music21Object.hasSpannerSite`, :meth:`~music21.base.Music21Object.hasVariantSite`, :meth:`~music21.base.Music21Object.isClassOrSubclass`, :meth:`~music21.base.Music21Object.mergeAttributes`, :meth:`~music21.base.Music21Object.next`, :meth:`~music21.base.Music21Object.previous`, :meth:`~music21.base.Music21Object.purgeLocations`, :meth:`~music21.base.Music21Object.purgeOrphans`, :meth:`~music21.base.Music21Object.purgeUndeclaredIds`, :meth:`~music21.base.Music21Object.removeLocationBySite`, :meth:`~music21.base.Music21Object.removeLocationBySiteId`, :meth:`~music21.base.Music21Object.setOffsetBySite`, :meth:`~music21.base.Music21Object.show`, :meth:`~music21.base.Music21Object.splitAtDurations`, :meth:`~music21.base.Music21Object.splitAtQuarterLength`, :meth:`~music21.base.Music21Object.splitByQuarterLengths`, :meth:`~music21.base.Music21Object.unfreezeIds`, :meth:`~music21.base.Music21Object.unwrapWeakref`, :meth:`~music21.base.Music21Object.wrapWeakref`, :meth:`~music21.base.Music21Object.write`

        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonAttributes`, :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


TextFormat
----------



.. class:: TextFormat()

    An object for defining text formatting. This object can be multiple-inherited by objects that need storage and i/o of text settings.

    See :class:`music21.expressions.TextExpression` for an example.



    **TextFormat** **properties**

        .. attribute:: justify

            Get or set the the justification.



            >>> from music21 import *
            >>> tf = TextFormat()
            >>> tf.justify = 'center'
            >>> tf.justify
            'center'



        .. attribute:: letterSpacing

            Get or set the letter spacing.



            >>> from music21 import *
            >>> tf = TextFormat()
            >>> tf.letterSpacing = 20
            >>> tf.letterSpacing
            20.0
            >>> tf.letterSpacing = 'normal'



        .. attribute:: size

            Get or set the size.



            >>> from music21 import *
            >>> tf = TextFormat()
            >>> tf.size = 20
            >>> tf.size
            20.0



        .. attribute:: style

            Get or set the style, as normal, italic, bold, and bolditalic.



            >>> from music21 import *
            >>> tf = TextFormat()
            >>> tf.style = 'bold'
            >>> tf.style
            'bold'



        .. attribute:: weight

            Get or set the weight, as normal, or bold.



            >>> from music21 import *
            >>> tf = TextFormat()
            >>> tf.weight = 'bold'
            >>> tf.weight
            'bold'




LanguageDetector
----------------



.. class:: LanguageDetector(text=None)


    Attempts to detect language on the basis of trigrams

    uses code from
    http://code.activestate.com/recipes/326576-language-detection-using-character-trigrams/
    unknown author.  No license given.

    See Trigram docs below...



    **LanguageDetector** **attributes**

        Attributes without Documentation: `languageCodes`, `languageLong`, `text`, `trigrams`

    **LanguageDetector** **methods**

        .. method:: mostLikelyLanguage(excerpt)


            returns the code of the most likely language for a passage, works on unicode or ascii.
            current languages: en, fr, de, it, cn



            >>> from music21 import *
            >>> ld = text.LanguageDetector()
            >>> ld.mostLikelyLanguage("Hello there, how are you doing today? I haven't seen you in a while.")
            'en'



        .. method:: mostLikelyLanguageNumeric(excerpt=None)


            returns a number representing the most likely language for a passage
            or 0 if there is no text.

            Useful for feature extraction.

            The codes are the index of the language name in LanguageDetector.languageCodes + 1



            >>> ld = LanguageDetector()
            >>> for i in range(0, len(ld.languageCodes)):
            ...    print i+1, ld.languageCodes[i]
            1 en
            2 fr
            3 it
            4 de
            5 cn
            >>> numLang = ld.mostLikelyLanguageNumeric("Hello there, how are you doing today? I haven't seen you in a while.")
            >>> numLang
            1
            >>> ld.languageCodes[numLang - 1]
            'en'



        .. method:: readExcerpts()

            No documentation.



Trigram
-------



.. class:: Trigram(excerptList=None)


    See LanguageDector above.  From http://code.activestate.com/recipes/326576-language-detection-using-character-trigrams/

    The frequency of three character
    sequences is calculated.  When treated as a vector, this information
    can be compared to other trigrams, and the difference between them
    seen as an angle.  The cosine of this angle varies between 1 for
    complete similarity, and 0 for utter difference.  Since letter
    combinations are characteristic to a language, this can be used to
    determine the language of a body of text. For example:



    >>> reference_en = Trigram('/path/to/reference/text/english')
    >>> reference_de = Trigram('/path/to/reference/text/german')
    >>> unknown = Trigram('url://pointing/to/unknown/text')
    >>> unknown.similarity(reference_de)
      0.4
    >>> unknown.similarity(reference_en)
      0.95

    would indicate the unknown text is almost cetrtainly English.  As
    syntax sugar, the minus sign is overloaded to return the difference
    between texts, so the above objects would give you:

      >>> unknown - reference_de
      0.6
      >>> reference_en - unknown    # order doesn't matter.
      0.05

    As it stands, the Trigram ignores character set information, which
    means you can only accurately compare within a single encoding
    (iso-8859-1 in the examples).  A more complete implementation might
    convert to unicode first.

    As an extra bonus, there is a method to make up nonsense words in the
    style of the Trigram's text.

      >>> reference_en.makeWords(30)
      My withillonquiver and ald, by now wittlectionsurper, may sequia, tory, I ad my notter. Marriusbabilly She lady for rachalle spen hat knong al elf





    **Trigram** **attributes**

        Attributes without Documentation: `lut`

    **Trigram** **methods**

        .. method:: likely(k)

            Returns a character likely to follow the given string
            two character string, or a space if nothing is found.


        .. method:: makeWords(count)

            returns a string of made-up words based on the known text.


        .. method:: measure()

            calculates the scalar length of the trigram vector and
            stores it in self.length.


        .. method:: parseExcerpt(excerpt)

            No documentation.


        .. method:: similarity(other)


            returns a number between 0 and 1 indicating similarity between
            two trigrams.
            1 means an identical ratio of trigrams;
            0 means no trigrams in common.




