unitracker-grammar 0.3.0__py3-none-any.whl

unitracker_grammar/__init__.py

@@ -0,0 +1,15 @@
+"""The canonical unitracker document as a Lark grammar, with its note table."""
+
+from unitracker_grammar.canonical import GRAMMAR, CanonicalError, parse, parser
+from unitracker_grammar.notes import NTSC_HZ, PAL_HZ, frequency, table
+
+__all__ = [
+    "GRAMMAR",
+    "NTSC_HZ",
+    "PAL_HZ",
+    "CanonicalError",
+    "frequency",
+    "parse",
+    "parser",
+    "table",
+]

unitracker_grammar/canonical.lark

@@ -0,0 +1,178 @@
+// The canonical unitracker document: format 1.20 with the init row (anarkiwi/unitracker#165),
+// value-or-expression command arguments (anarkiwi/unitracker#172) and no fixed record types
+// (anarkiwi/unitracker#126, anarkiwi/unitracker#165). A document names no player: everything it
+// plays is in it, and its only constants are the note table F(k) (notes.py) at its clock.
+// Whitespace is exact, but a space inside a flow collection or a block scalar may be a line
+// wrap (a newline and the continuation indentation); a flow expression that contains a comma
+// is written in single quotes. Every block line ends with its newline.
+
+start: "unitracker: " VERSION _NL meta _NL (clock _NL)? (voices _NL)? (tempo _NL)? tables? (init _NL)? "song:" _NL row+ ending
+
+// ---- header: clock, voices and tempo only where they differ from PAL, 3 and 6 ---------------
+
+meta: "meta: " _LC meta_item (_SEP meta_item)* "}"
+meta_item: META_KEY ": " text
+text: TEXT | SQUOTED | DQUOTED
+
+clock: "clock: {cycles_per_tick: " INT ", clock_hz: " INT "}"
+voices: "voices: " INT
+tempo: "tempo: " (INT | "[" INT ", " INT "]")
+
+// the tables expressions index as T[k]: 0 outside the list
+tables: "tables:" _NL ("  " XTABLE ": " intlist _NL)+
+intlist: _LB INT (_SEP INT)* "]"
+
+// one event per voice: the state after init, a step of no duration before the first tick
+init: "init: " _LB event (_SEP event)* "]"
+
+// ---- timeline ---------------------------------------------------------------------------
+
+row: "  - def:" _NL section+ "    play: " plays _NL
+   | "  - play: " plays _NL
+ending: "  - end" _NL | "  - {loop: " INT "}" _NL
+plays: _LB play (_SEP play)* "]"
+play: PHRASE SIGNED? | CONT | END
+
+// ---- definitions: each record type once per row, names in first-use order --------------
+
+section: "      restart:" _NL ("        " RESTART ": " program _NL)+
+       | "      ins:" _NL ("        " INS ": " instrument _NL)+
+       | "      ctrl:" _NL ("        " CTRL ": " program _NL)+
+       | "      pw:" _NL ("        " PW ": " modulation _NL)+
+       | "      filter:" _NL ("        " FILTER ": " modulation _NL)+
+       | "      x:" _NL ("        " X ": " expr _NL)+
+       | "      phrase:" _NL ("        " PHRASE ": " phrase _NL)+
+
+instrument: _LC ins_ad "}"
+ins_ad: "ad: " (INT) (_SEP ins_sr)? | ins_sr
+ins_sr: "sr: " (INT) (_SEP ins_ctrl)? | ins_ctrl
+ins_ctrl: "ctrl: " (CTRL | program) (_SEP ins_pw)? | ins_pw
+ins_pw: "pw: " (PW | modulation) (_SEP ins_filter)? | ins_filter
+ins_filter: "filter: " (FILTER | modulation) (_SEP ins_freq)? | ins_freq
+ins_freq: "freq: " (fexpr) (_SEP ins_fn)? | ins_fn
+ins_fn: "mod: " NAME (_WB param_bag)? (_SEP ins_restart)? | ins_restart
+param_bag: "{" pname_val (_SEP pname_val)* "}"
+pname_val: NAME _BSC (SIGNED | INT | NAME | pname_list)
+pname_list: "[" (SIGNED | INT) (_SEP (SIGNED | INT))* "]"
+_WB: /(?: |\n +)/          // a flow space that may be a line wrap
+_BSC: /:(?: |\n +)/        // a bag's colon, a space or a line wrap before its value
+ins_restart: "restart: " (RESTART | program)
+
+// a program: its rows in the order they run, then its end or its loop
+program: _LB (row_ _SEP)* (END | _LC LOOP INT "}") "]"
+// a pulse or filter program that is one expression (a constant is one) is written as that
+modulation: program | fexpr
+
+row_: _LC "}" | _LC row_wait "}"
+row_wait: "wait: " (INT) (_SEP row_hold)? | row_hold
+row_hold: "hold: " (INT) (_SEP row_ctrl)? | row_ctrl
+row_ctrl: "ctrl: " (ctrl_value) (_SEP row_gate)? | row_gate
+row_gate: "gate: " (INT) (_SEP row_note)? | row_note
+row_note: "note: " (note_value) (_SEP row_ad)? | row_ad
+row_ad: "ad: " (INT) (_SEP row_sr)? | row_sr
+row_sr: "sr: " (INT) (_SEP row_pw)? | row_pw
+row_pw: "pw: " (pw_value) (_SEP row_cut)? | row_cut
+row_cut: "cut: " (fexpr) (_SEP row_res)? | row_res
+row_res: "res: " (INT) (_SEP row_route)? | row_route
+row_route: "route: " (route_value) (_SEP row_mode)? | row_mode
+row_mode: "mode: " (INT) (_SEP row_freq)? | row_freq
+row_freq: "freq: " (fexpr) (_SEP row_run)? | row_run
+row_run: "run: " (program_name) (_SEP row_filter)? | row_filter
+row_filter: "filter: " (NONE) (_SEP row_vol)? | row_vol
+row_vol: "vol: " (INT)
+
+ctrl_value: INT | CTRLMASK
+note_value: SIGNED | NOTE
+pw_value: fexpr | NONE
+route_value: INT | ROUTE_ADD | ROUTE_ADD_MASK INT | ROUTE_REMOVE | ROUTE_REMOVE_MASK INT "'"
+program_name: CTRL | PW | FILTER
+
+// ---- events -----------------------------------------------------------------------------
+
+phrase: _LB event (_SEP event)* "]"
+event: NOTE_ATOM ("." INS)? cmd_run keep_pw keep_filter ("*" INT)?
+cmd_run: "!run:" (program_name | NONE) cmd_pw | cmd_pw
+cmd_pw: "!pw:" (INT | X | NONE) cmd_filter | cmd_filter
+cmd_filter: FILTER_NONE cmd_ad | cmd_ad
+cmd_ad: "!ad:" INT cmd_sr | cmd_sr
+cmd_sr: "!sr:" INT cmd_ctrl | cmd_ctrl
+cmd_ctrl: "!ctrl:" INT cmd_resfilt | cmd_resfilt
+cmd_resfilt: "!resfilt:" INT "/" INT cmd_mode | cmd_mode
+cmd_mode: "!mode:" INT cmd_vol | cmd_vol
+cmd_vol: "!vol:" INT cmd_cut | cmd_cut
+cmd_cut: "!cut:" (INT | X) cmd_tempo | cmd_tempo
+cmd_tempo: "!tempo:" INT ("/" INT)? cmd_vtempo | cmd_vtempo
+cmd_vtempo: "!vtempo:" INT ("/" INT)? cmd_freq | cmd_freq
+cmd_freq: "!freq:" (X | NONE | SIGNED | INT) cmd_set | cmd_set
+cmd_set: ("!set " NAME " " (SIGNED | INT))+ cmd_legato | cmd_legato
+cmd_legato: LEGATO | 
+keep_pw: KEEP_PW |
+keep_filter: KEEP_FILTER |
+
+// ---- expressions (docs/modulation/expressions.md) ---------------------------------------
+
+// plain in a block mapping; in a flow collection plain, or in quotes when it contains a comma
+fexpr: expr | "'" expr "'"
+expr: term (ADD term)*
+term: factor (MUL factor | FLOORDIV factor | MOD factor)*
+factor: INT | SIGNED | V | PHI | N
+      | F expr ")" | XTABLE "[" expr "]"
+      | ABS expr ")" | MIN expr _SEP expr ")" | MAX expr _SEP expr ")"
+      | "(" expr ")" | "(" expr CMP expr ")"
+      | NEG factor
+
+// ---- terminals --------------------------------------------------------------------------
+
+VERSION: /\d+\.\d+/
+META_KEY: "title" | "author" | "released"
+XTABLE: /[A-EG-MO-Z][A-Za-z]*/
+INT: /\d+/
+SIGNED: /[+-]\d+/
+CTRLMASK: /\d*\^\d+/
+NOTE: /[A-G]#?-?\d+/
+NOTE_ATOM: /[A-G]#?-?\d+|-|off|on/
+INS: /i\d+/
+CTRL: /c\d+/
+PW: /pw\d+/
+FILTER: /f\d+/
+RESTART: /r\d+/
+X: /x\d+/
+PHRASE: /p\d+/
+TEXT: /[^\s,\[\]{}'"#&*!|>%@`][^,\[\]{}]*/
+SQUOTED: /'(?:[^']|'')*'/
+DQUOTED: /"(?:[^"\\]|\\.)*"/
+NAME: /[a-z][a-z0-9_]*/
+
+CONT: "~"
+END: "end"
+LOOP: "loop: "
+NONE: "none"
+ROUTE_ADD: "+"
+ROUTE_ADD_MASK: "+ "
+ROUTE_REMOVE: "'-'"
+ROUTE_REMOVE_MASK: "'- "
+FILTER_NONE: "!filter:none"
+LEGATO: "!legato"
+KEEP_PW: "!pw"
+KEEP_FILTER: "!filter"
+OSC_MOD: "symmetric" | "ramp" | "approach"
+V: "v"
+PHI: "φ"
+N: "N"
+F: "F("
+ABS: "abs("
+MIN: "min("
+MAX: "max("
+NEG: "-"
+MUL: "*"
+
+_NL: "\n"
+// a flow collection may wrap after its opening bracket
+_LB: /\[(?:\n +)?/
+_LC: /\{(?:\n +)?/
+_SEP: /,(?: |\n +)/
+
+ADD: /(?: |\n +)[+-](?: |\n +)/
+FLOORDIV: /(?: |\n +)\/\/(?: |\n +)/
+MOD: /(?: |\n +)%(?: |\n +)/
+CMP: /(?: |\n +)(?:==|!=|<=|>=|<|>)(?: |\n +)/

unitracker_grammar/canonical.py

@@ -0,0 +1,28 @@
+"""The canonical document grammar, ``canonical.lark``, and a parser for it."""
+
+import functools
+from importlib import resources
+
+from lark import Lark, Tree, exceptions
+
+GRAMMAR = resources.files("unitracker_grammar") / "canonical.lark"
+
+
+class CanonicalError(ValueError):
+    """A text that is not a canonical document."""
+
+
+@functools.lru_cache(maxsize=1)
+def parser() -> Lark:
+    """The LALR parser of the canonical grammar."""
+    return Lark(GRAMMAR.read_text(encoding="utf-8"), parser="lalr", lexer="contextual")
+
+
+def parse(text: str) -> Tree:
+    """The parse tree of canonical document ``text``."""
+    try:
+        return parser().parse(text)
+    except exceptions.UnexpectedInput as exc:
+        raise CanonicalError(
+            f"line {exc.line} column {exc.column}: {str(exc).splitlines()[0]}"
+        ) from exc

unitracker_grammar/expr.py

@@ -0,0 +1,292 @@
+"""Modulator expressions: checked, printed in their one text and compiled to Python.
+
+Integer literals, ``+ - *``, ``//`` (floor division), ``%`` (floor modulo), ``abs``, ``min``,
+``max``, a comparison ``(a op b)`` as 1 or 0 (op one of ``== != < <= > >=``), ``v``, ``φ``,
+``N``, ``F(k)`` (the frequency of note k) and ``T[k]`` for a named table ``T``. An expression is
+a stdlib :mod:`ast` node, read from a text by :func:`tree` or from a canonical parse tree by
+:class:`Nodes`.
+"""
+
+import ast
+import functools
+
+from lark import Token, Transformer
+
+PHI = "φ"
+NAMES = {"v": "v", PHI: "phi", "N": "N"}
+CALLS = {"abs": 1, "min": 2, "max": 2, "F": 1}
+_CALLED = {"F": "_F"}
+_BINARY = {ast.Add: "+", ast.Sub: "-", ast.Mult: "*", ast.FloorDiv: "//", ast.Mod: "%"}
+_COMPARE = {ast.Eq: "==", ast.NotEq: "!=", ast.Lt: "<", ast.LtE: "<=", ast.Gt: ">", ast.GtE: ">="}
+_OPERATOR = {text: op for op, text in (_BINARY | _COMPARE).items()}
+_GUARDED = {"//": "_div", "%": "_mod"}
+_ATOMS = {"V": "v", "PHI": PHI, "N": "N"}
+
+
+class ExpressionError(ValueError):
+    """A text is not an expression of the modulator grammar."""
+
+
+def written(text: str):
+    """The written value of an expression text: an integer literal as an int."""
+    try:
+        return int(text)
+    except ValueError:
+        return text
+
+
+def _python(node, tables, zero: bool) -> str:
+    """Python source of a parsed expression reading ``tables`` (see :func:`source`)."""
+    # pylint: disable=too-many-return-statements
+    if (
+        isinstance(node, ast.Constant)
+        and isinstance(node.value, int)
+        and not isinstance(node.value, bool)
+    ):
+        return str(node.value)
+    if isinstance(node, ast.Name) and node.id in NAMES:
+        return NAMES[node.id]
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
+        return f"(-{_python(node.operand, tables, zero)})"
+    if isinstance(node, ast.BinOp) and type(node.op) in _BINARY:
+        op = _BINARY[type(node.op)]
+        left, right = _python(node.left, tables, zero), _python(node.right, tables, zero)
+        if (
+            zero
+            and op in _GUARDED
+            and not (isinstance(node.right, ast.Constant) and node.right.value)
+        ):
+            return f"{_GUARDED[op]}({left}, {right})"
+        return f"({left} {op} {right})"
+    if isinstance(node, ast.Compare):
+        return _comparison(node, tables, zero)
+    if isinstance(node, ast.List):
+        raise ExpressionError(
+            f"{ast.unparse(node)!r} is outside the grammar: a comparison is written (a op b)"
+        )
+    if isinstance(node, ast.Call):
+        name = node.func.id if isinstance(node.func, ast.Name) else None
+        if node.keywords or name not in CALLS:
+            raise ExpressionError(f"{ast.unparse(node)!r} calls no grammar function")
+        if len(node.args) != CALLS[name]:
+            raise ExpressionError(f"{name} takes {CALLS[name]} argument(s)")
+        args = ", ".join(_python(a, tables, zero) for a in node.args)
+        return f"{_CALLED.get(name, name)}({args})"
+    if isinstance(node, ast.Subscript) and isinstance(node.value, ast.Name):
+        name = node.value.id
+        if name not in tables:
+            raise ExpressionError(f"unknown table {name!r}")
+        return f"_T[{name!r}]({_python(node.slice, tables, zero)})"
+    raise ExpressionError(f"{ast.unparse(node)!r} is outside the grammar")
+
+
+def _comparison(node, tables, zero: bool) -> str:
+    """One comparison, 1 when it holds, else 0."""
+    if len(node.ops) != 1:
+        raise ExpressionError(f"({ast.unparse(node)}) is not one comparison")
+    op = _COMPARE.get(type(node.ops[0]))
+    if op is None:
+        raise ExpressionError(f"({ast.unparse(node)}) compares with no grammar operator")
+    left, right = _python(node.left, tables, zero), _python(node.comparators[0], tables, zero)
+    return f"(1 if {left} {op} {right} else 0)"
+
+
+def tree(text: str) -> ast.expr:
+    """The node of an expression text, unchecked."""
+    try:
+        return ast.parse(text.strip(), mode="eval").body
+    except SyntaxError as exc:
+        raise ExpressionError(f"bad expression {text!r}: {exc.msg}") from exc
+
+
+def source(expr: str | ast.expr, tables=(), zero: bool = False) -> str:
+    """Python source over ``v``, ``phi``, ``N``, ``_F`` and ``_T`` of an expression text or node;
+    ``zero``: ``//`` and ``%`` by a divisor that is no nonzero literal call ``_div`` and ``_mod``,
+    0 by a divisor of 0, else they raise ZeroDivisionError."""
+    return _python(tree(expr) if isinstance(expr, str) else expr, set(tables), zero)
+
+
+def canonical(text: str) -> str:
+    """The one text of expression ``text`` (see :func:`printed`)."""
+    return printed(tree(text))
+
+
+def printed(node) -> str:
+    """The one text of expression node ``node``: sums and products as linear forms (constant
+    terms and factors folded, like terms merged), terms in one order, parentheses only where the
+    grammar needs them, and decimal literals."""
+    return _sum(*_linear(node))
+
+
+def _linear(node) -> tuple[int, dict]:
+    """``(constant, {factors: coefficient})`` of ``node`` as a sum of products."""
+    if isinstance(node, ast.Constant):
+        return int(node.value), {}
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
+        const, terms = _linear(node.operand)
+        return -const, {f: -c for f, c in terms.items()}
+    if isinstance(node, ast.BinOp) and isinstance(node.op, (ast.Add, ast.Sub)):
+        sign = 1 if isinstance(node.op, ast.Add) else -1
+        (a, at), (b, bt) = _linear(node.left), _linear(node.right)
+        terms = dict(at)
+        for f, c in bt.items():
+            terms[f] = terms.get(f, 0) + sign * c
+        return a + sign * b, {f: c for f, c in terms.items() if c}
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Mult):
+        return _product(_linear(node.left), _linear(node.right))
+    return 0, {(_factor(node),): 1}
+
+
+def _product(left: tuple, right: tuple) -> tuple[int, dict]:
+    (a, at), (b, bt) = left, right
+    if not at or not bt:
+        const, terms, k = (b, bt, a) if not at else (a, at, b)
+        return const * k, {f: c * k for f, c in terms.items() if c * k}
+    factors = []
+    coef = 1
+    for const, terms in (left, right):
+        if not const and len(terms) == 1:
+            ((f, c),) = terms.items()
+            factors += f
+            coef *= c
+        else:
+            factors.append(f"({_sum(const, terms)})")
+    return 0, {tuple(sorted(factors, key=_order)): coef}
+
+
+def _factor(node) -> str:
+    """The text of a node that is no sum or product, as a factor."""
+    # pylint: disable=too-many-return-statements
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Compare):
+        op = _COMPARE[type(node.ops[0])]
+        return f"({printed(node.left)} {op} {printed(node.comparators[0])})"
+    if isinstance(node, ast.Call):
+        args = [printed(a) for a in node.args]
+        if node.func.id in ("min", "max"):
+            args.sort(key=_order)
+        return f"{node.func.id}({', '.join(args)})"
+    if isinstance(node, ast.Subscript):
+        return f"{node.value.id}[{printed(node.slice)}]"
+    if isinstance(node, ast.BinOp):
+        left, right = _linear(node.left), _linear(node.right)
+        return f"{_operand(*left, True)} {_BINARY[type(node.op)]} {_operand(*right)}"
+    raise ExpressionError(f"{ast.unparse(node)!r} is outside the grammar")
+
+
+def _operand(const: int, terms: dict, left: bool = False) -> str:
+    """An operand of ``%`` or ``//``: a term on the left, a factor on the right."""
+    text = _sum(const, terms)
+    if not terms or (len(terms) == 1 and not const and (left or _atomic(terms))):
+        return text
+    return f"({text})"
+
+
+def _sum(const: int, terms: dict) -> str:
+    out = []
+    for factors, coef in sorted(terms.items(), key=lambda t: _order("*".join(t[0]))):
+        body = "*".join(
+            f"({f})" if _divides(f) and (len(factors) > 1 or abs(coef) != 1) else f for f in factors
+        )
+        if abs(coef) != 1:
+            body = f"{abs(coef)}*{body}"
+        if not out:
+            lead = "-" if coef < 0 else ""
+            if coef == -1 and len(factors) == 1 and _divides(factors[0]):
+                body = f"({body})"
+            out.append(lead + body)
+        else:
+            out.append((" - " if coef < 0 else " + ") + body)
+    if const or not out:
+        out.append(str(const) if not out else (" - " if const < 0 else " + ") + str(abs(const)))
+    return "".join(out)
+
+
+def _divides(factor: str) -> bool:
+    """Whether a factor's text is a ``%`` or ``//`` at its top level."""
+    depth = 0
+    for k, ch in enumerate(factor):
+        depth += {"(": 1, "[": 1, ")": -1, "]": -1}.get(ch, 0)
+        if not depth and factor[k : k + 3] in (" % ", " //"):
+            return True
+    return False
+
+
+def _atomic(terms: dict) -> bool:
+    ((factors, coef),) = terms.items()
+    return coef == 1 and len(factors) == 1 and not _divides(factors[0])
+
+
+def _order(text: str) -> tuple:
+    """The order of terms and factors: integers, names, then the rest, each by its text."""
+    return (0 if text.lstrip("-").isdigit() else 1 if text in NAMES else 2, text)
+
+
+def _div(a: int, b: int) -> int:
+    return a // b if b else 0
+
+
+def _mod(a: int, b: int) -> int:
+    return a % b if b else 0
+
+
+def compile_expr(expr: str | ast.expr, namespace: dict, zero: bool = False):
+    """A function ``(v, phi, N) -> int`` of an expression text or node (``zero`` as in
+    :func:`source`).
+
+    ``namespace``, the function's globals, holds ``_F(k)``, the frequency of format note k, and
+    ``_T``, each named table's function of its index.
+    """
+    body = source(expr, namespace["_T"], zero)
+    if zero:
+        # pylint: disable-next=eval-used
+        return eval(f"lambda _div, _mod: lambda v, phi, N: {body}", namespace)(_div, _mod)
+    return eval(f"lambda v, phi, N: {body}", namespace)  # pylint: disable=eval-used
+
+
+def _at(values: tuple, k: int) -> int:
+    return values[k] if 0 <= k < len(values) else 0
+
+
+def indexed(values) -> functools.partial:
+    """A table's function of its index: ``values[k]``, 0 outside them."""
+    return functools.partial(_at, tuple(values))
+
+
+class Nodes(Transformer):
+    """The expressions of a canonical parse tree (rules ``fexpr``, ``expr``, ``term`` and
+    ``factor``) as nodes; ``-`` before a literal is a negative literal."""
+
+    # pylint: disable=missing-function-docstring
+
+    def fexpr(self, children):
+        return children[0]
+
+    def expr(self, children):
+        out = children[0]
+        for op, operand in zip(children[1::2], children[2::2]):
+            out = ast.BinOp(out, _OPERATOR[op.strip()](), operand)
+        return out
+
+    term = expr
+
+    def factor(self, children):
+        # pylint: disable=too-many-return-statements
+        head, *rest = children
+        if not isinstance(head, Token):
+            if not rest:
+                return head
+            return ast.Compare(head, [_OPERATOR[rest[0].strip()]()], [rest[1]])
+        if head.type in ("INT", "SIGNED"):
+            return ast.Constant(int(head))
+        if head.type in _ATOMS:
+            return ast.Name(_ATOMS[head.type])
+        if head.type == "XTABLE":
+            return ast.Subscript(ast.Name(str(head)), rest[0])
+        if head.type == "NEG":
+            (inner,) = rest
+            if isinstance(inner, ast.Constant):
+                return ast.Constant(-inner.value)
+            return ast.UnaryOp(ast.USub(), inner)
+        return ast.Call(ast.Name(head[:-1]), rest, [])

unitracker_grammar/notes.py

@@ -0,0 +1,25 @@
+"""The note table: ``F(k)``, the SID frequency word of format note ``k`` at a clock."""
+
+PAL_HZ = 985248
+NTSC_HZ = 1022727
+A4 = 57
+A4_HZ = 440
+WORD = 1 << 16
+PHASE = 1 << 24
+
+
+def frequency(note: int, clock_hz: int = PAL_HZ) -> int:
+    """``F(k)``: the frequency word of format note ``k`` (C2 is 24) in equal temperament from
+    A4 at 440 Hz, rounded to the nearest word; 0 below C0 and where the word overflows."""
+    if note < 0:
+        return 0
+    word = round(A4_HZ * 2 ** ((note - A4) / 12) * PHASE / clock_hz)
+    return word if word < WORD else 0
+
+
+def table(clock_hz: int = PAL_HZ) -> list[int]:
+    """``F(k)`` for every note whose word fits, from C0."""
+    out = []
+    while (word := frequency(len(out), clock_hz)) > 0:
+        out.append(word)
+    return out

unitracker_grammar-0.3.0.dist-info/METADATA

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: unitracker-grammar
+Version: 0.3.0
+Summary: The canonical unitracker document as a Lark grammar, with its note table and modulator expression language
+Author: Josh Bailey
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright [yyyy] [name of copyright owner]
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+Project-URL: Homepage, https://github.com/anarkiwi/unitracker-grammar
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark>=1.2
+Provides-Extra: dev
+Requires-Dist: black>=24; extra == "dev"
+Requires-Dist: pylint>=3; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Dynamic: license-file
+
+# unitracker-grammar
+
+The canonical [unitracker](https://github.com/anarkiwi/unitracker) document as a
+[Lark](https://github.com/lark-parser/lark) grammar, with an LALR parser for it and the note
+table its expressions read as `F(k)`, and the modulator expression language: checked, printed
+in its one text and compiled to Python.
+
+A document names no player. It holds everything it plays: instruments, programs, expressions,
+phrases and the tables its expressions index. Its only constants are the note table at its clock
+and the header defaults (PAL clock, 3 voices, tempo 6).
+
+## Install
+
+```sh
+pip install "unitracker-grammar @ git+https://github.com/anarkiwi/unitracker-grammar"
+```
+
+## Use
+
+```python
+from unitracker_grammar import parse, CanonicalError, frequency, table
+tree = parse(text)        # a lark.Tree, or CanonicalError naming the line and column
+frequency(57)             # F(57): A4 at the PAL clock
+table(clock_hz=1022727)   # F(k) for every note whose word fits, from C0, at NTSC
+```
+
+`parser()` is the cached `lark.Lark` parser and `GRAMMAR` the grammar file resource.
+
+## Expressions
+
+`unitracker_grammar.expr` owns the modulator expression language. An expression is a stdlib
+`ast` node, read from a text by `tree` or from a parse tree's `expr` and `fexpr` rules by the
+`Nodes` transformer.
+
+```python
+from unitracker_grammar import expr, frequency
+expr.canonical("1024 + 16*min(3, φ)")       # '16*min(3, φ) + 1024', its one text
+fn = expr.compile_expr("v + W[φ]", {"_F": frequency, "_T": {"W": expr.indexed([1, 2])}})
+fn(10, 1, 48)                               # (v, φ, N) -> 12
+```
+
+`source` is the Python source of an expression (`ExpressionError` outside the grammar),
+`printed` the one text of a node and `written` an integer literal as an int. `//` and `%` raise
+`ZeroDivisionError` on a divisor of 0; with `zero=True` they are 0.
+
+## Grammar
+
+[`src/unitracker_grammar/canonical.lark`](src/unitracker_grammar/canonical.lark); the document
+format and the meaning of each construct are described in unitracker's
+[docs/format](https://github.com/anarkiwi/unitracker/blob/main/docs/format/document.md).

unitracker_grammar-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+unitracker_grammar/__init__.py,sha256=MBnQeRCM5uvzkKB6KgU18QdxnhXih5sCeNUG0t0C2Io,370
+unitracker_grammar/canonical.lark,sha256=1gJgRhXB8qqk4qzs8a8WKDut6DHYDB7TSHzmpTXHEl4,6947
+unitracker_grammar/canonical.py,sha256=EEvyyA6d2-HhNFN8K0zVjGBPk4xyc8qiKtq-QKIc_xY,829
+unitracker_grammar/expr.py,sha256=iZQMttmy2zS-g60gqES6diDLW_m_EMnPuWyNwL6Dej0,11541
+unitracker_grammar/notes.py,sha256=utJEOzxWHr5xUOYBmjXloCgqnYCocr5kuheBPNc4iQE,777
+unitracker_grammar-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+unitracker_grammar-0.3.0.dist-info/METADATA,sha256=uf6xCZhyhpJvUFPG-qBWrsAeLHS5NkN92hvRaH5WCDY,15794
+unitracker_grammar-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+unitracker_grammar-0.3.0.dist-info/top_level.txt,sha256=c4ag8vMWGjSRQ-YkRoGfcKkFJshnXm0pXm4fgTZ1wRo,19
+unitracker_grammar-0.3.0.dist-info/RECORD,,

unitracker_grammar-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

unitracker_grammar-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

unitracker_grammar-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+unitracker_grammar