.. _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 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'] 
>>> sc = scale.ScalaScale('a4', mbiraScales[0])
>>> 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('junk') == 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 = 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. 

            >>> fileLikeOpen = StringIO.StringIO()

        .. 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 = ScalaPitch(' 1066.667 cents')
    >>> print sp.parse()
    1066.667 
    >>> sp = 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. 


