simfile.tidy.behaviors
======================

.. py:module:: simfile.tidy.behaviors


Classes
-------

.. autoapisummary::

   simfile.tidy.behaviors.Preset
   simfile.tidy.behaviors.Whitespace
   simfile.tidy.behaviors.LineEndings
   simfile.tidy.behaviors.ChangeComments
   simfile.tidy.behaviors.CreateMissingProperties
   simfile.tidy.behaviors.DestructivelyRemoveProperties
   simfile.tidy.behaviors.SortProperties


Module Contents
---------------

.. py:class:: Preset(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   A predefined set of behaviors for use with :func:`~.tidy`.


   .. py:attribute:: NO_OP

      Leave all optional behaviors off by default.

      This is equivalent to not specifying a preset, except it allows you to
      leave all optional behaviors ``False``.



   .. py:attribute:: SM5

      Emulate the StepMania 5 editor's output (nondestructively).



   .. py:attribute:: SM5_DESTRUCTIVE

      Emulate the StepMania 5 editor's output (including removing unknown
      properties).



   .. py:attribute:: RECOMMENDED

      Same as SM5, but keep the preamble & add or update the library version.



   .. py:method:: behaviors() -> DefaultBehaviors


.. py:class:: Whitespace(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Normalize all whitespace in the file.


   .. py:attribute:: SM5

      Normalize whitespace to match StepMania 5's output:

      * Properties are separated by a newline.
      * Each chart is prefixed by a blank line.
      * Each SM chart property (before note data) is prefixed by 5 spaces.

      Currently, this option removes comments inside of SM charts
      if their whitespace is adjusted. Combine with :class:`.ChangeComments`
      to regenerate measure comments if desired.



   .. py:method:: run(sim: simfile.types.Simfile) -> bool


.. py:class:: LineEndings(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Normalize all line endings in the file.


   .. py:attribute:: LF

      Normalize all line endings to '\n'.



   .. py:attribute:: CRLF

      Normalize all line endings to '\r\n'.



   .. py:attribute:: HEURISTIC

      Use the heuristic-determined line ending.

      This typically matches the first line ending seen in the file.



   .. py:method:: run(sim: simfile.types.Simfile) -> bool


.. py:class:: ChangeComments(*args, **kwds)

   Bases: :py:obj:`enum.Flag`


   Add or remove comments from various parts of the simfile.


   .. py:attribute:: REMOVE_PREAMBLE

      Remove any preamble (comment at the start of the file).



   .. py:attribute:: REMOVE_CHART_PREAMBLE

      Remove any chart preamble (comment before the first property signaling
      a chart, i.e. ``NOTES`` for SM and ``NOTEDATA`` for SSC).



   .. py:attribute:: REMOVE_CHART_INNER

      Remove any comments inside a chart, such as (but not limited to)
      measure indicators.



   .. py:attribute:: REMOVE_OTHER

      Remove any other comments that don't match the above definitions.



   .. py:attribute:: REMOVE_ALL

      Remove all comments.

      This is equivalent to combining all of the above flags using the
      bitwise ``|`` operator.



   .. py:attribute:: ADD_LIBRARY_VERSION_PREAMBLE

      Create a comment at the start of the file with the following string::

          // Generated by simfile {VERSION} for Python

      :code:`{VERSION}` is replaced with the library's version specifier.
      If such a comment already exists, it will be updated with the
      library's current version.



   .. py:attribute:: ADD_CHART_PREAMBLE

      Create a comment before each chart with the following string::

          //---------------{STEPSTYPE} - {DESCRIPTION}----------------

      :code:`{STEPSTYPE}` is replaced with :attr:`~.BaseChart.stepstype`
      and :code:`{DESCRIPTION}` is replaced with
      :attr:`~.BaseChart.description`. If such a comment already exists,
      it will be updated to reflect the chart's current properties.



   .. py:attribute:: ADD_CHART_MEASURES

      Create comments before each measure to indicate the measure number::

          #NOTES:
          // measure 0
          0000
          0000
          0000
          0000
          ,  // measure 1
          (etc.)



   .. py:attribute:: ADD_ALL

      Create all available types of supported comments.

      This is equivalent to combining all of the above flags using the
      bitwise ``|`` operator.



   .. py:method:: run(sim: simfile.types.Simfile) -> bool


.. py:class:: CreateMissingProperties(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Fill in any missing properties in the simfile with a default value.


   .. py:attribute:: SM5

      Create the same default properties that the StepMania 5 editor creates,
      if they don't already exist.

      Most properties' default values are an empty string, but some have a
      specific non-empty default value, such as ``OFFSET`` and ``BPMS``.



   .. py:method:: run(sim: simfile.types.Simfile) -> bool


.. py:class:: DestructivelyRemoveProperties(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Remove any unknown properties (a destructive operation).


   .. py:attribute:: SM5

      Remove all properties that are unknown to the StepMania 5 editor.



   .. py:method:: run(sim: simfile.types.Simfile) -> bool


.. py:class:: SortProperties(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Sort the properties in the simfile.


   .. py:attribute:: SM5

      Sort known properties to match the StepMania 5 editor's output.

      Unknown properties, if not removed, are sorted alphabetically after
      known properties.



   .. py:method:: run(sim: simfile.types.Simfile) -> bool