.. _stdlib_strudel_mini:

============================================================
Mini-notation tokenizer, parser, and fluent-DSL entry points
============================================================

.. das:module:: strudel_mini

Module strudel_mini



++++++++++++
Enumerations
++++++++++++

.. _enum-strudel_mini-TokenKind:

.. das:attribute:: TokenKind

:Values: * **WORD** = 0 - Identifier: sound name, note name, or keyword.

         * **NUMBER** = 1 - Numeric literal.

         * **TILDE** = 2 - Silence `~`.

         * **LBRACKET** = 3 - Opening bracket `[` — start of a subsequence.

         * **RBRACKET** = 4 - Closing bracket `]` — end of a subsequence.

         * **LANGLE** = 5 - Opening angle `<` — start of an alternation (slowcat).

         * **RANGLE** = 6 - Closing angle `>` — end of an alternation.

         * **LPAREN** = 7 - Opening parenthesis `(` — reserved.

         * **RPAREN** = 8 - Closing parenthesis `)` — reserved.

         * **COMMA** = 9 - Comma `,` — stack separator.

         * **STAR** = 10 - Star `*` — fast modifier (`x*n` = `x` played `n` times).

         * **SLASH** = 11 - Slash `/` — slow modifier (`x/n` = `x` stretched over `n` cycles).

         * **BANG** = 12 - Bang `!` — replicate modifier.

         * **AT** = 13 - At `@` — weight modifier (`x@n` occupies `n` units of the parent sequence).

         * **QUESTION** = 14 - Question `?` — degrade modifier (random drop).

         * **COLON** = 15 - Colon `:` — sample-index modifier (`bd:1` picks variation 1).

         * **PIPE** = 16 - Pipe `|` — bar separator in `seq(...)`.

         * **EOF_TOKEN** = 17 - End-of-input marker.




++++++++++
Structures
++++++++++

.. _struct-strudel_mini-Token:

.. das:attribute:: Token

:Fields: * **kind** :  :ref:`TokenKind <enum-strudel_mini-TokenKind>` - Token kind.

         * **text** : string - Source text of the token.

         * **pos** : int - Byte offset of the token in the original input string.




++++++++++++++++++++
Tokenizer and parser
++++++++++++++++++++

  *  :ref:`parse_note_name (name: string) : float <function-strudel_mini_parse_note_name_string>`
  *  :ref:`parse_note_name_default (name: string; default_oct: int) : float <function-strudel_mini_parse_note_name_default_string_int>`
  *  :ref:`tokenize (input: string) : array\<Token\> <function-strudel_mini_tokenize_string>`

.. _function-strudel_mini_parse_note_name_string:

.. das:function:: parse_note_name(name: string) : float

Parse a note name with explicit octave (`"c3"`, `"eb4"`, `"fs2"`) into a MIDI
number. Returns `-1.0` on miss. Bare letters without an octave return -1 —
this is intentional so `s("a e i")` parses as sound names, not notes.


:Arguments: * **name** : string

.. _function-strudel_mini_parse_note_name_default_string_int:

.. das:function:: parse_note_name_default(name: string; default_oct: int) : float

Parse a note name allowing the octave to be omitted (falls back to `default_oct`).
Accepts `"d"`, `"d#"`, `"d#3"`, `"eb"`. Returns `-1.0` on miss.


:Arguments: * **name** : string

            * **default_oct** : int

.. _function-strudel_mini_tokenize_string:

.. das:function:: tokenize(input: string) : array<Token>

Tokenize a mini-notation string into an array of `Token`. Uses `peek_data` for
O(1) per-character access. An `EOF_TOKEN` is always appended at the end.


:Arguments: * **input** : string


+++++++++++++++++++++++
Fluent DSL constructors
+++++++++++++++++++++++

  *  :ref:`n (notation: string) : Pattern <function-strudel_mini_n_string>`
  *  :ref:`note (notation: string; sound: string = "sine") : Pattern <function-strudel_mini_note_string_string>`
  *  :ref:`note_pattern (notation: string; sound: string = "sine") : Pattern <function-strudel_mini_note_pattern_string_string>`
  *  :ref:`s (notation: string) : Pattern <function-strudel_mini_s_string>`
  *  :ref:`seq (notation: string; sound: string = "sine") : Pattern <function-strudel_mini_seq_string_string>`
  *  :ref:`set_s (var pat: Pattern; notation: string) : Pattern <function-strudel_mini_set_s_Pattern_string>`
  *  :ref:`set_vowel (var pat: Pattern; var vowel_pat: Pattern) : Pattern <function-strudel_mini_set_vowel_Pattern_Pattern>`
  *  :ref:`set_vowel (var pat: Pattern; notation: string) : Pattern <function-strudel_mini_set_vowel_Pattern_string>`
  *  :ref:`vowel (var pat: Pattern; var vowel_pat: Pattern) : Pattern <function-strudel_mini_vowel_Pattern_Pattern>`
  *  :ref:`vowel (var pat: Pattern; notation: string) : Pattern <function-strudel_mini_vowel_Pattern_string>`

.. _function-strudel_mini_n_string:

.. das:function:: n(notation: string) : Pattern

Parse mini-notation as numeric values (each atom's `note` field holds the number).
Useful as a patternified parameter, e.g. `slow(pat, n("<2 16>"))`.


:Arguments: * **notation** : string

.. _function-strudel_mini_note_string_string:

.. das:function:: note(notation: string; sound: string = "sine") : Pattern

Alias for `note_pattern`. Example: `note("c3 e3 g3")`.


:Arguments: * **notation** : string

            * **sound** : string

.. _function-strudel_mini_note_pattern_string_string:

.. das:function:: note_pattern(notation: string; sound: string = "sine") : Pattern

Parse mini-notation for note patterns. Example: `note_pattern("c3 ~ e3 g3")`
plays C3, silence, E3, G3 with the default `"sine"` sound. Any atom whose
token looks like a note name is converted via default-octave parsing.


:Arguments: * **notation** : string

            * **sound** : string

.. _function-strudel_mini_s_string:

.. das:function:: s(notation: string) : Pattern

Parse mini-notation and return a `Pattern` of sound events. Example:
`s("bd sd [hh hh] cp")` plays kick, snare, two hats in one step, clap.


:Arguments: * **notation** : string

.. _function-strudel_mini_seq_string_string:

.. das:function:: seq(notation: string; sound: string = "sine") : Pattern

Parse mini-notation with `|` bar separators for sequential melodies. Each bar
plays for one cycle with its notes evenly subdivided. Example:
`seq("e4 e4 f4 g4 | g4 f4 e4 d4")` plays two bars of four quarter-notes each.


:Arguments: * **notation** : string

            * **sound** : string

.. _function-strudel_mini_set_s_Pattern_string:

.. das:function:: set_s(pat: Pattern; notation: string) : Pattern

Strudel-style `.s()` with mini-notation. Example: `pat |> set_s("<supersaw sawtooth>")`.
Single-token input goes through `set_sound` directly; mini-notation is parsed
and sampled at each event's onset.


:Arguments: * **pat** :  :ref:`Pattern <alias-Pattern>`

            * **notation** : string


set_vowel
^^^^^^^^^

.. _function-strudel_mini_set_vowel_Pattern_Pattern:

.. das:function:: set_vowel(pat: Pattern; vowel_pat: Pattern) : Pattern

Set vowel from a pre-built pattern. Use when the vowel pattern needs transforms
(`slow`, `fast`, `rev`) before applying — e.g. `pat |> set_vowel(s("<a e i o u>") |> slow(5.0lf))`.


:Arguments: * **pat** :  :ref:`Pattern <alias-Pattern>`

            * **vowel_pat** :  :ref:`Pattern <alias-Pattern>`

.. _function-strudel_mini_set_vowel_Pattern_string:

.. das:function:: set_vowel(pat: Pattern; notation: string) : Pattern

----


vowel
^^^^^

.. _function-strudel_mini_vowel_Pattern_Pattern:

.. das:function:: vowel(pat: Pattern; vowel_pat: Pattern) : Pattern

Alias for `set_vowel` (Pattern overload). Use when the vowel pattern needs
transforms. Example: `pat |> vowel(s("<a e i>") |> slow(4.0lf))`.


:Arguments: * **pat** :  :ref:`Pattern <alias-Pattern>`

            * **vowel_pat** :  :ref:`Pattern <alias-Pattern>`

.. _function-strudel_mini_vowel_Pattern_string:

.. das:function:: vowel(pat: Pattern; notation: string) : Pattern


+++++++++++++++++++
Cycle-rate variants
+++++++++++++++++++

  *  :ref:`every_degrade (n: int; prob: float; notation: string) : Pattern <function-strudel_mini_every_degrade_int_float_string>`
  *  :ref:`every_fast (n: int; factor: double; notation: string) : Pattern <function-strudel_mini_every_fast_int_double_string>`
  *  :ref:`every_slow (n: int; factor: double; notation: string) : Pattern <function-strudel_mini_every_slow_int_double_string>`

.. _function-strudel_mini_every_degrade_int_float_string:

.. das:function:: every_degrade(n: int; prob: float; notation: string) : Pattern

Randomly drop events from the pattern every `n`th cycle. Example:
`every_degrade(4, 0.5, "bd sd hh cp")` drops ~half the events on cycles 4, 8, ...


:Arguments: * **n** : int

            * **prob** : float

            * **notation** : string

.. _function-strudel_mini_every_fast_int_double_string:

.. das:function:: every_fast(n: int; factor: double; notation: string) : Pattern

Apply `fast(factor)` to the pattern every `n`th cycle. Example:
`every_fast(4, 2.0, "bd sd hh cp")` plays at double speed on cycles 4, 8, 12, ...


:Arguments: * **n** : int

            * **factor** : double

            * **notation** : string

.. _function-strudel_mini_every_slow_int_double_string:

.. das:function:: every_slow(n: int; factor: double; notation: string) : Pattern

Apply `slow(factor)` to the pattern every `n`th cycle. Example:
`every_slow(4, 2.0, "bd sd hh cp")` plays at half speed on cycles 4, 8, 12, ...


:Arguments: * **n** : int

            * **factor** : double

            * **notation** : string