.. _moduleScala.base:

music21.scala.base
==================

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

.. module:: music21.scala.base


This module defines classes for representing Scala scale data, including Scala pitch representations, storage, and files.

The Scala format is defined at the following URL:
http://www.huygens-fokker.org/scala/scl_format.html
We thank Manuel Op de Coul for allowing us to include the repository (as of May 11, 2011) with music21

Utility functions are also provided to search and find scales in the Scala scale archive. File names can be found with the :func:`~music21.scala.search` function.

To create a :class:`~music21.scale.ScalaScale` instance, simply provide a root pitch and the name of the scale. Scale names are given as a the scala .scl file name.



>>> from music21 import *
>>> mbiraScales = scala.search('mbira')
>>> mbiraScales
['mbira_banda.scl', 'mbira_banda2.scl', 'mbira_gondo.scl', 'mbira_kunaka.scl', 'mbira_kunaka2.scl', 'mbira_mude.scl', 'mbira_mujuru.scl', 'mbira_zimb.scl']


For most people you'll want to do something like this:



>>> sc = scale.ScalaScale('a4', 'mbira_banda.scl')
>>> sc.pitches
[A4, B4(-15c), C#5(-11c), D#5(-7c), E~5(+6c), F#5(+14c), G~5(+1c), B-5(+2c)]





.. function:: getPaths()

    Get all scala scale paths. This is called once or the module and cached as SCALA_PATHS, which should be used instead of calls to this function.



    >>> from music21 import scala
    >>> a = scala.getPaths()
    >>> len(a) >= 3800
    True



.. function:: parse(target)

    Get a :class:`~music21.scala.ScalaStorage` object from the bundled SCL archive or a file path.



    >>> from music21 import scala
    >>> ss = scala.parse('balafon6')
    >>> ss.description
    u'Observed balafon tuning from Burma, Helmholtz/Ellis p. 518, nr.84'
    >>> [str(i) for i in ss.getIntervalSequence()]
    ['<music21.interval.Interval m2 (+14c)>', '<music21.interval.Interval M2 (+36c)>', '<music21.interval.Interval M2>', '<music21.interval.Interval m2 (+37c)>', '<music21.interval.Interval M2 (-49c)>', '<music21.interval.Interval M2 (-6c)>', '<music21.interval.Interval M2 (-36c)>']




    >>> scala.parse('incorrectFileName.scl') == None
    True




    >>> ss = scala.parse('barbourChrom1')
    >>> ss.description
    u"Barbour's #1 Chromatic"
    >>> ss.fileName
    'barbour_chrom1.scl'




    >>> ss = scala.parse('blackj_gws.scl')
    >>> ss.description
    u'Detempered Blackjack in 1/4 kleismic marvel tuning'



.. function:: search(target)

    Search the scala archive for matches based on a string



    >>> from music21 import *
    >>> mbiraScales = scala.search('mbira')
    >>> mbiraScales
    ['mbira_banda.scl', 'mbira_banda2.scl', 'mbira_gondo.scl', 'mbira_kunaka.scl', 'mbira_kunaka2.scl', 'mbira_mude.scl', 'mbira_mujuru.scl', 'mbira_zimb.scl']



ScalaFile
---------



.. class:: ScalaFile(data=None)


    Interface for reading and writing scala files. On reading, returns a :class:`~music21.scala.ScalaStorage` object.



    >>> from music21 import *
    >>> sf = scala.ScalaFile()



    **ScalaFile** **attributes**

        Attributes without Documentation: `data`, `file`, `fileName`

    **ScalaFile** **methods**

        .. method:: close()

            No documentation.


        .. method:: open(fp, mode='r')

            Open a file for reading



        .. method:: openFileLike(fileLike)

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



        .. method:: read()

            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)

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



        .. method:: write()

            No documentation.


        .. method:: writestr()

            No documentation.



ScalaPitch
----------



.. class:: ScalaPitch(sourceString=None)

    Representation of a scala pitch notation



    >>> from music21 import *
    >>> sp = scala.ScalaPitch(' 1066.667 cents')
    >>> print sp.parse()
    1066.667
    ⁠ 
    >>> sp = scala.ScalaPitch(' 2/1')
    >>> sp.parse()
    1200.0
    >>> sp.parse('100.0 C#')
    100.0
    >>> [sp.parse(x) for x in ['89/84', '55/49', '44/37', '63/50', '4/3', '99/70', '442/295', '27/17', '37/22', '98/55', '15/8', '2/1']]
    [100.09920982..., 199.9798432913..., 299.973903610..., 400.108480470..., 498.044999134..., 600.08832376157..., 699.9976981706..., 800.90959309..., 900.02609638..., 1000.020156708..., 1088.268714730..., 1200.0]



    **ScalaPitch** **attributes**

        Attributes without Documentation: `cents`, `src`

    **ScalaPitch** **methods**

        .. method:: parse(sourceString=None)

            Parse the source string and set self.cents.




ScalaStorage
------------



.. class:: ScalaStorage(sourceString=None, fileName=None)

    Object representation of data stored in a Scale scale file. This objeject is used to access Scala information stored in a file. To create a music21 scale with a Scala file, use :class:`~music21.scale.ScalaScale`.

    This is not called ScalaScale, as this name clashes with the :class:`~music21.scale.ScalaScale` that uses this object.



    **ScalaStorage** **attributes**

        Attributes without Documentation: `src`, `pitchCount`, `pitchValues`, `description`, `fileName`

    **ScalaStorage** **methods**

        .. method:: getAdjacentCents()

            Get cents values between adjacent intervals.



        .. method:: getCentsAboveTonic()

            Return a list of cent values above the implied tonic.



        .. method:: getFileString()

            Return a string suitable for writing a Scale file



        .. method:: getIntervalSequence()

            Get the scale as a list of Interval objects.



        .. method:: parse()

            Parse a scala file delivered as a long string with line breaks



        .. method:: setAdjacentCents(centList)

            Given a list of adjacent cent values, create the necessary ScalaPitch  objects and update the



        .. method:: setIntervalSequence(iList)

            Set the scale from a list of Interval objects.




