simfile.tidy ============ .. py:module:: simfile.tidy Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/simfile/tidy/behaviors/index Classes ------- .. autoapisummary:: simfile.tidy.Preset simfile.tidy.Whitespace simfile.tidy.LineEndings simfile.tidy.ChangeComments simfile.tidy.CreateMissingProperties simfile.tidy.DestructivelyRemoveProperties simfile.tidy.SortProperties Functions --------- .. autoapisummary:: simfile.tidy.tidy Package 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 .. py:function:: tidy(sim: simfile.types.Simfile, preset: behaviors.Preset | None = None, *, whitespace: behaviors.Whitespace | Literal[False] | None = None, line_endings: behaviors.LineEndings | Literal[False] | None = None, change_comments: behaviors.ChangeComments | Literal[False] | None = None, create_missing_properties: behaviors.CreateMissingProperties | Literal[False] | None = None, destructively_remove_properties: behaviors.DestructivelyRemoveProperties | Literal[False] | None = None, sort_properties: behaviors.SortProperties | Literal[False] | None = None) Tidy up a simfile for future serialization, mutating it in-memory. This function has many optional parameters that toggle various tidying **behaviors**. The simplest way to call it is to pass a preset as the second argument:: import tidy, Preset from simfile.tidy tidy(sim, Preset.RECOMMENDED) # or Preset.SM5 Without a preset, all behaviors default to off. If you don't specify a preset, you must set at least one behavior to a non-empty value, or specify the :data:`~Preset.NO_OP` preset to allow no behaviors. Each optional behavior has an associated enum. Some behaviors' enums are flags that can be combined using bitwise operators, for example:: import tidy, ChangeComments from simfile.tidy tidy( sim, change_comments=ChangeComments.REMOVE_PREAMBLE | ChangeComments.REMOVE_CHART_PREAMBLE, ) Returns `True` only if changes were made to the simfile. Raises `ValueError` if no preset or behaviors are specified.