loma-lang 1.1.0__tar.gz

loma_lang-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Lomartire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

loma_lang-1.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: loma-lang
+Version: 1.1.0
+Summary: LOMA: a deterministic text language for music that compiles to MIDI
+Author: Manuel Lomartire
+License: MIT
+Project-URL: Homepage, https://manuellomartire.github.io/loma/
+Project-URL: Repository, https://github.com/manuellomartire/loma
+Project-URL: Documentation, https://github.com/manuellomartire/loma/blob/main/SPEC.md
+Project-URL: Changelog, https://github.com/manuellomartire/loma/blob/main/CHANGELOG.md
+Keywords: music,midi,compiler,llm
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# LOMA
+
+*English · [Italiano](README.it.md)*
+
+LOMA is a text language for describing music, designed to be **written by an AI** and **compiled deterministically to a MIDI file**: the same `.loma` file gives the same `.mid`, byte for byte, every time and with any conforming compiler.
+
+- Full specification: [SPEC.md](SPEC.md) (English), [SPEC.it.md](SPEC.it.md) (Italian)
+- Formal grammar: [spec/grammar.ebnf](spec/grammar.ebnf)
+- Changes by version: [CHANGELOG.md](CHANGELOG.md)
+- Playground: https://manuellomartire.github.io/loma/
+
+## An example
+
+```loma
+loma 1.0
+title "First example"
+tempo 100
+meter 4/4
+key Cm
+
+track RH ch=1 program=0
+track LH ch=2 program=0
+
+pattern arp8 base=3 dur=/8 : 1 3 5 3 1 3 5 3
+
+section verse
+  bar Cm
+    RH{v=78}: Eb5/8 D5/8 C5/4 G4/4 r/4
+    LH{v=60}: use arp8
+  bar Ab
+    RH{v=70>88}: C5/4 Eb5/4{o=-6} Ab4/2{a=leg}
+    LH{v=60}: use arp8
+end
+
+play verse x2
+```
+
+The AI writes intentions (chord `Cm`, the left hand plays the arpeggio, the melody grows from 70 to 88); the compiler expands them into notes on integer ticks. `/8` is an eighth note, `r` a rest, `{o=-6}` plays 6 ticks early, `x2` repeats the section.
+
+## Playground
+
+Try it online: **https://manuellomartire.github.io/loma/**
+
+`docs/index.html` is a web page that runs entirely in the browser: paste or edit LOMA, press Compile (or Ctrl/⌘+Enter), read the errors next to their lines (and copy them for the AI that wrote the file), play the result on a piano roll, download the MIDI file, open a `.mid` file to turn it into LOMA, or copy a link that contains the piece. It embeds the JavaScript compiler, so there is no server. It is published with GitHub Pages: in a fork, choose the `docs` folder of the main branch in the repository settings.
+
+The sound comes from a small synthesizer inside the page, not from real instruments. After changing `js/loma.js`, the examples or `docs/playground.src.html`, rebuild the page with `python3 tools/build_web.py`.
+
+## Usage
+
+Python 3.9 or later, no dependencies. The tests run on Linux, Windows and macOS; the second implementation needs Node.js 18 or later.
+
+```
+python3 -m loma compile song.loma -o song.mid       # compile
+python3 -m loma check song.loma --json              # validate only, errors as JSON
+python3 -m loma expand song.loma --json             # events in ticks, canonical JSON
+python3 -m loma hash song.loma                      # SHA-256 of the MIDI file
+python3 -m loma test-determinism song.loma          # compile 100 times and compare
+python3 -m loma decompile song.mid -o song.loma     # from MIDI to LOMA
+```
+
+After `pip install .` the command is `loma`. The file name may be `-` to read standard input. Exit status: 0 success, 1 errors in the file, 2 usage or I/O problem.
+
+An error says where and what to fix, and a mistyped name proposes the right one. Syntax errors and bar errors are reported in the same round, so that an AI can fix them all at once:
+
+```
+E005 line 9: unknown chord 'Cmaj'. Did you mean 'C'?
+E003 line 14 bar 2 (Ab) track RH: bar length mismatch. Expected 1920 ticks, got 1680. Missing 240 ticks (= /8).
+```
+
+## What is in the repository
+
+| Folder | Content |
+|---|---|
+| `loma/` | Reference compiler in Python: parser, expansion, events, MIDI writer, decompiler, command line |
+| `js/` | Second implementation in JavaScript (Node.js and browser), used to check conformance |
+| `docs/` | The playground web page: `index.html` is self-contained and can be served with GitHub Pages |
+| `conformance/` | Conformance suite: 95 valid files with the expected bytes, 116 files with the expected errors, and the program that compares them |
+| `spec/` | EBNF grammar |
+| `tests/` | Automated tests |
+| `tools/` | Regeneration of the suite, comparison of the two implementations on random files, build of the web page |
+| `examples/` | Example pieces, including `showcase.loma`, which uses every construct |
+| `experiment/` | Material for the experiment with several AIs: assignment, collection of the files, measurements |
+| `editors/vscode/` | Syntax highlighting for Visual Studio Code |
+
+## Checks
+
+```
+python3 -m unittest discover -s tests                       # all tests
+python3 conformance/run.py --cmd "python3 -m loma"          # suite on the Python compiler
+python3 conformance/run.py --cmd "node js/loma.js"          # suite on the JavaScript compiler
+python3 tools/fuzz_compare.py --count 5000                  # random files: Python against JavaScript
+```
+
+What is verified:
+
+- **Same bytes from two implementations.** The Python and the JavaScript compilers produce the same events and the same bytes on all 211 cases of the suite and on thousands of randomly generated files, valid and invalid.
+- **Bytes worked out by hand.** The minimal file in [SPEC.md §16.1](SPEC.md#161-example-with-the-expected-bytes) was computed by hand from the specification and matches the output.
+- **Round trip.** Every MIDI file of the suite, decompiled and compiled again, comes back identical.
+
+What is **not** verified:
+
+- Both implementations have the same author. A misreading of the specification may be present in both: the decisive proof is still a compiler written by someone else from `SPEC.md` alone.
+- Nobody has yet listened critically to the example pieces: LOMA guarantees that the MIDI is always the same, not that it sounds good.
+- The experiment with several AIs (`experiment/`) so far contains only the three pieces written by the author of the specification.
+
+## Writing LOMA with an AI
+
+[experiment/prompt.md](experiment/prompt.md) (English) and [experiment/prompt.it.md](experiment/prompt.it.md) (Italian) contain a compact reference of the language and the assignments for the three test pieces, ready to paste. The intended loop: the AI writes the file, `loma check --json` returns the errors, the AI fixes only the lines indicated.
+
+## Roadmap status
+
+| Phase | Status |
+|---|---|
+| 0.1 — deterministic core | Done |
+| 0.1 — EBNF grammar and second implementation | Done (same author) |
+| 0.1 — experiment with AIs | Tools ready; pieces written by other models are missing |
+| 0.2 — expression and variety | Done |
+| 0.3 — advanced harmony | Done |
+| 1.0 — stable specification, documentation, public suite | Done |
+| MIDI to LOMA, lyrics, syntax highlighting | Done |
+| Compiler 1.1 — errors in one round, suggestions, playground links | Done |
+
+## Contributing
+
+A change must keep the bytes: run the tests before opening a pull request. Regenerating the expected files of the suite (`tools/make_conformance.py`) is a change of the specification and must be deliberate.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

loma_lang-1.1.0/README.md

@@ -0,0 +1,129 @@
+# LOMA
+
+*English · [Italiano](README.it.md)*
+
+LOMA is a text language for describing music, designed to be **written by an AI** and **compiled deterministically to a MIDI file**: the same `.loma` file gives the same `.mid`, byte for byte, every time and with any conforming compiler.
+
+- Full specification: [SPEC.md](SPEC.md) (English), [SPEC.it.md](SPEC.it.md) (Italian)
+- Formal grammar: [spec/grammar.ebnf](spec/grammar.ebnf)
+- Changes by version: [CHANGELOG.md](CHANGELOG.md)
+- Playground: https://manuellomartire.github.io/loma/
+
+## An example
+
+```loma
+loma 1.0
+title "First example"
+tempo 100
+meter 4/4
+key Cm
+
+track RH ch=1 program=0
+track LH ch=2 program=0
+
+pattern arp8 base=3 dur=/8 : 1 3 5 3 1 3 5 3
+
+section verse
+  bar Cm
+    RH{v=78}: Eb5/8 D5/8 C5/4 G4/4 r/4
+    LH{v=60}: use arp8
+  bar Ab
+    RH{v=70>88}: C5/4 Eb5/4{o=-6} Ab4/2{a=leg}
+    LH{v=60}: use arp8
+end
+
+play verse x2
+```
+
+The AI writes intentions (chord `Cm`, the left hand plays the arpeggio, the melody grows from 70 to 88); the compiler expands them into notes on integer ticks. `/8` is an eighth note, `r` a rest, `{o=-6}` plays 6 ticks early, `x2` repeats the section.
+
+## Playground
+
+Try it online: **https://manuellomartire.github.io/loma/**
+
+`docs/index.html` is a web page that runs entirely in the browser: paste or edit LOMA, press Compile (or Ctrl/⌘+Enter), read the errors next to their lines (and copy them for the AI that wrote the file), play the result on a piano roll, download the MIDI file, open a `.mid` file to turn it into LOMA, or copy a link that contains the piece. It embeds the JavaScript compiler, so there is no server. It is published with GitHub Pages: in a fork, choose the `docs` folder of the main branch in the repository settings.
+
+The sound comes from a small synthesizer inside the page, not from real instruments. After changing `js/loma.js`, the examples or `docs/playground.src.html`, rebuild the page with `python3 tools/build_web.py`.
+
+## Usage
+
+Python 3.9 or later, no dependencies. The tests run on Linux, Windows and macOS; the second implementation needs Node.js 18 or later.
+
+```
+python3 -m loma compile song.loma -o song.mid       # compile
+python3 -m loma check song.loma --json              # validate only, errors as JSON
+python3 -m loma expand song.loma --json             # events in ticks, canonical JSON
+python3 -m loma hash song.loma                      # SHA-256 of the MIDI file
+python3 -m loma test-determinism song.loma          # compile 100 times and compare
+python3 -m loma decompile song.mid -o song.loma     # from MIDI to LOMA
+```
+
+After `pip install .` the command is `loma`. The file name may be `-` to read standard input. Exit status: 0 success, 1 errors in the file, 2 usage or I/O problem.
+
+An error says where and what to fix, and a mistyped name proposes the right one. Syntax errors and bar errors are reported in the same round, so that an AI can fix them all at once:
+
+```
+E005 line 9: unknown chord 'Cmaj'. Did you mean 'C'?
+E003 line 14 bar 2 (Ab) track RH: bar length mismatch. Expected 1920 ticks, got 1680. Missing 240 ticks (= /8).
+```
+
+## What is in the repository
+
+| Folder | Content |
+|---|---|
+| `loma/` | Reference compiler in Python: parser, expansion, events, MIDI writer, decompiler, command line |
+| `js/` | Second implementation in JavaScript (Node.js and browser), used to check conformance |
+| `docs/` | The playground web page: `index.html` is self-contained and can be served with GitHub Pages |
+| `conformance/` | Conformance suite: 95 valid files with the expected bytes, 116 files with the expected errors, and the program that compares them |
+| `spec/` | EBNF grammar |
+| `tests/` | Automated tests |
+| `tools/` | Regeneration of the suite, comparison of the two implementations on random files, build of the web page |
+| `examples/` | Example pieces, including `showcase.loma`, which uses every construct |
+| `experiment/` | Material for the experiment with several AIs: assignment, collection of the files, measurements |
+| `editors/vscode/` | Syntax highlighting for Visual Studio Code |
+
+## Checks
+
+```
+python3 -m unittest discover -s tests                       # all tests
+python3 conformance/run.py --cmd "python3 -m loma"          # suite on the Python compiler
+python3 conformance/run.py --cmd "node js/loma.js"          # suite on the JavaScript compiler
+python3 tools/fuzz_compare.py --count 5000                  # random files: Python against JavaScript
+```
+
+What is verified:
+
+- **Same bytes from two implementations.** The Python and the JavaScript compilers produce the same events and the same bytes on all 211 cases of the suite and on thousands of randomly generated files, valid and invalid.
+- **Bytes worked out by hand.** The minimal file in [SPEC.md §16.1](SPEC.md#161-example-with-the-expected-bytes) was computed by hand from the specification and matches the output.
+- **Round trip.** Every MIDI file of the suite, decompiled and compiled again, comes back identical.
+
+What is **not** verified:
+
+- Both implementations have the same author. A misreading of the specification may be present in both: the decisive proof is still a compiler written by someone else from `SPEC.md` alone.
+- Nobody has yet listened critically to the example pieces: LOMA guarantees that the MIDI is always the same, not that it sounds good.
+- The experiment with several AIs (`experiment/`) so far contains only the three pieces written by the author of the specification.
+
+## Writing LOMA with an AI
+
+[experiment/prompt.md](experiment/prompt.md) (English) and [experiment/prompt.it.md](experiment/prompt.it.md) (Italian) contain a compact reference of the language and the assignments for the three test pieces, ready to paste. The intended loop: the AI writes the file, `loma check --json` returns the errors, the AI fixes only the lines indicated.
+
+## Roadmap status
+
+| Phase | Status |
+|---|---|
+| 0.1 — deterministic core | Done |
+| 0.1 — EBNF grammar and second implementation | Done (same author) |
+| 0.1 — experiment with AIs | Tools ready; pieces written by other models are missing |
+| 0.2 — expression and variety | Done |
+| 0.3 — advanced harmony | Done |
+| 1.0 — stable specification, documentation, public suite | Done |
+| MIDI to LOMA, lyrics, syntax highlighting | Done |
+| Compiler 1.1 — errors in one round, suggestions, playground links | Done |
+
+## Contributing
+
+A change must keep the bytes: run the tests before opening a pull request. Regenerating the expected files of the suite (`tools/make_conformance.py`) is a change of the specification and must be deliberate.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

loma_lang-1.1.0/loma/__init__.py

@@ -0,0 +1,3 @@
+"""LOMA 1.0 reference compiler (Python 3, standard library only, integer arithmetic only)."""
+__version__ = "1.1.0"
+SPEC_VERSION = "1.0"

loma_lang-1.1.0/loma/__main__.py

@@ -0,0 +1,12 @@
+import os
+import sys
+
+from .cli import main
+
+try:
+    code = main()
+    sys.stdout.flush()
+except BrokenPipeError:        # e.g. `loma expand song.loma | head`
+    os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+    code = 0
+sys.exit(code)

loma_lang-1.1.0/loma/api.py

@@ -0,0 +1,34 @@
+"""Public API of the reference compiler."""
+import hashlib
+
+from .decompiler import decompile
+from .events import canonical_json
+from .errors import LomaErrors
+from .expander import check_bars, compile_song
+from .midi_writer import write_midi
+from .parser import parse_partial
+
+__all__ = ["compile_text", "expand_json", "sha256", "decompile"]
+
+
+def _compile(text):
+    song, errors, checkable = parse_partial(text)
+    if errors:
+        raise LomaErrors(errors + (check_bars(song) if checkable else []))
+    return compile_song(song)
+
+
+def compile_text(text):
+    """LOMA source -> (compiled, midi_bytes). Raises LomaErrors."""
+    compiled = _compile(text)
+    return compiled, write_midi(compiled)
+
+
+def expand_json(text):
+    """LOMA source -> canonical JSON of the expanded events. Raises LomaErrors."""
+    compiled = _compile(text)
+    return canonical_json(compiled.events, compiled.track_names)
+
+
+def sha256(data):
+    return hashlib.sha256(data).hexdigest()

loma_lang-1.1.0/loma/cli.py

@@ -0,0 +1,129 @@
+"""Command line interface. Exit status: 0 success, 1 errors in the input, 2 usage or I/O problem."""
+import argparse
+import json
+import sys
+
+from . import __version__, SPEC_VERSION
+from .api import compile_text, expand_json, sha256
+from .decompiler import decompile, DecompileError
+from .errors import LomaError, LomaErrors
+from .events import canonical_json
+from .midi_reader import MidiError
+
+
+def _read_source(path):
+    if path == "-":
+        data = sys.stdin.buffer.read()
+    else:
+        with open(path, "rb") as f:
+            data = f.read()
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        raise LomaErrors([LomaError("E001", "the file is not valid UTF-8", 1)])
+
+
+def _report(errors, as_json):
+    if as_json:
+        print(json.dumps([e.to_dict() for e in errors], sort_keys=True, ensure_ascii=False))
+    else:
+        for e in errors:
+            print(e.format(), file=sys.stderr)
+        print("%d error(s)" % len(errors), file=sys.stderr)
+
+
+def _parser():
+    ap = argparse.ArgumentParser(prog="loma", description="LOMA %s reference compiler" % SPEC_VERSION)
+    ap.add_argument("--version", action="version", version="loma %s (language %s)" % (__version__, SPEC_VERSION))
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("compile", help="compile a .loma file to MIDI")
+    p.add_argument("file", help="source file, or - for standard input")
+    p.add_argument("-o", "--output", required=True)
+    p.add_argument("--json", action="store_true", help="errors as JSON on standard output")
+    p = sub.add_parser("check", help="validate only")
+    p.add_argument("file")
+    p.add_argument("--json", action="store_true")
+    p = sub.add_parser("expand", help="print the expanded events")
+    p.add_argument("file")
+    p.add_argument("--json", action="store_true", help="canonical JSON")
+    p = sub.add_parser("hash", help="SHA-256 of the MIDI output")
+    p.add_argument("file")
+    p = sub.add_parser("test-determinism", help="compile N times and compare the hashes")
+    p.add_argument("file")
+    p.add_argument("--runs", type=int, default=100)
+    p = sub.add_parser("decompile", help="convert a MIDI file to LOMA")
+    p.add_argument("file")
+    p.add_argument("-o", "--output", help="output file (default: standard output)")
+    return ap
+
+
+def _run(args):
+    if args.cmd == "decompile":
+        with open(args.file, "rb") as f:
+            source, warnings = decompile(f.read())
+        for w in warnings:
+            print("warning: " + w, file=sys.stderr)
+        if args.output:
+            with open(args.output, "w", encoding="utf-8", newline="\n") as f:
+                f.write(source)
+        else:
+            sys.stdout.write(source)
+        return 0
+
+    text = _read_source(args.file)
+    if args.cmd == "check":
+        compile_text(text)
+        print("[]" if args.json else "OK")
+    elif args.cmd == "compile":
+        _, midi = compile_text(text)
+        with open(args.output, "wb") as f:
+            f.write(midi)
+        if not args.json:
+            print("wrote %s (%d bytes, sha256 %s)" % (args.output, len(midi), sha256(midi)))
+    elif args.cmd == "expand":
+        if args.json:
+            sys.stdout.write(expand_json(text))
+        else:
+            compiled, _ = compile_text(text)
+            names = compiled.track_names
+            for e in compiled.events:
+                d = e.to_dict(names)
+                rest = " ".join("%s=%s" % (k, d[k]) for k in sorted(d) if k not in ("tick", "type"))
+                print("%9d %-8s %s" % (e.tick, e.kind, rest))
+    elif args.cmd == "hash":
+        print(sha256(compile_text(text)[1]))
+    elif args.cmd == "test-determinism":
+        compiled, midi = compile_text(text)
+        first = (sha256(midi), canonical_json(compiled.events, compiled.track_names))
+        for _ in range(max(args.runs, 1) - 1):
+            compiled, midi = compile_text(text)
+            if (sha256(midi), canonical_json(compiled.events, compiled.track_names)) != first:
+                print("FAIL: outputs differ between runs", file=sys.stderr)
+                return 1
+        print("OK: %d runs, identical output, sha256 %s" % (max(args.runs, 1), first[0]))
+    return 0
+
+
+def _portable_output():
+    """UTF-8 and '\\n' on every system: the output must not depend on the platform (on Windows the
+    default would be the local code page and '\\r\\n')."""
+    for stream, errors in ((sys.stdout, "strict"), (sys.stderr, "backslashreplace")):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors=errors, newline="\n")
+
+
+def main(argv=None):
+    _portable_output()
+    args = _parser().parse_args(argv)
+    try:
+        return _run(args)
+    except LomaErrors as e:
+        _report(e.errors, getattr(args, "json", False))
+        return 1
+    except (OSError, MidiError, DecompileError) as e:
+        print("loma: %s" % e, file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())