@leafo/lml 0.1.0 → 0.2.0

package/README.md

@@ -18,8 +18,8 @@ import SongParser from "@leafo/lml"
 // Parse and compile LML to a song
 const song = SongParser.load(`
   ks0 ts4/4
-  c5 d5 e5 f5
-  g5.2 g5.2
+  c5 d e f
+  g.2 g.2
 `)
 
 // Access the notes
@@ -40,42 +40,94 @@ import SongParser from "@leafo/lml"
 const parser = new SongParser()
 
 // Phase 1: Parse text to AST
-const ast = parser.parse("c5 d5 e5")
-// [["note", "C5"], ["note", "D5"], ["note", "E5"]]
+const ast = parser.parse("c5 d e")
+// [["note", "C5"], ["note", "D"], ["note", "E"]]
 
 // Phase 2: Compile AST to song
 const song = parser.compile(ast)
 ```
 
+### Parser Options
+
+Both `SongParser.load()` and `parser.compile()` accept an options object:
+
+```typescript
+const song = SongParser.load("c d e f g", {
+  defaultOctave: 4,  // Default octave for relative notes (default: 5)
+})
+```
+
+This is useful for bass clef or other instruments that typically play in different registers.
+
 ## LML Syntax
 
 ### Notes
 
-A note is written as the note name followed by the octave. Notes are placed sequentially and must be separated by whitespace.
+Notes are written as letter names (`a` through `g`) and placed sequentially, separated by whitespace. The octave is automatically determined by finding the closest one to the previous note. The first note defaults to octave 5 (configurable via `defaultOctave` option).
 
 ```
-c5 d5 e5
+c d e f g a b c    # c5 d5 e5 f5 g5 a5 b5 c6
 ```
 
-A duration multiplier can be specified by appending a period and a number. The default duration is 1 beat.
+The algorithm picks the octave that minimizes the distance in semitones:
 
 ```
-c5.2 d5 d5 e5.4
+c d e f g a b c    # Ascending: c5 → c6
+c6 b a g f e d c   # Descending: c6 → c5
 ```
 
-Notes can be made sharp with `+`, flat with `-`, or natural with `=`. These modifiers appear after the note name but before the octave.
+Duration can be modified with `.` (multiply) or `/` (divide). The default duration is 1 beat.
 
 ```
-c+5 c-5 b=4
+c.2 d d e.4        # c is 2 beats, d is 1 beat each, e is 4 beats
+c/2 d/2 e/4        # c and d are 0.5 beats, e is 0.25 beats
+```
+
+An explicit start position can be specified with `@` followed by the beat number. This places notes at absolute positions rather than sequentially.
+
+```
+c@0 d@4 e@8        # Notes at beats 0, 4, and 8
+c.2@0 d.2@2        # Duration 2, at beats 0 and 2
+```
+
+Notes can be made sharp with `+`, flat with `-`, or natural with `=`:
+
+```
+c c+ d- e          # c c# db e
+```
+
+### Explicit Octaves
+
+When you need precise control, add an octave number (0-9) after the note name:
+
+```
+c5 d5 e5           # Explicit octaves
+c3 d e f           # Start at c3, then continue relatively: c3 d3 e3 f3
+g4 c               # Jump to g4, then c5 (closest to g4)
+```
+
+This is useful for:
+- Setting the starting octave
+- Jumping to a different register
+- Writing music that spans multiple octaves
+
+```
+# Two octave arpeggio
+c4 e g c5 e g c6
+
+# Jump between registers
+c5 d e g3 a b
 ```
 
 ### Rests
 
-Insert silence using the rest command `r`, optionally with a duration multiplier.
+Insert silence using the rest command `r`, optionally with a duration multiplier. Like notes, rests can also use `@` for explicit positioning.
 
 ```
-c5 r d5.2
-d5 r2 a4
+c r d.2
+d r2 a
+r@4         # Rest at beat 4
+r2@4        # Rest with duration 2 at beat 4
 ```
 
 ### Time Commands
@@ -88,13 +140,15 @@ Change the base duration using time commands. These take effect until the end of
 
 ```
 dt
-c5 d5 c5 d5 c5 d5 e5.2
+c d c d c d e.2
 ```
 
-Time commands stack when repeated:
+Time commands stack when repeated. You can also add a number to apply the effect multiple times:
 
 ```
-dt dt c5 d5  # Each note is 0.25 beats
+dt dt c d    # Each note is 0.25 beats
+dt2 c d      # Same as above
+ht3 c        # Note is 8 beats (2^3)
 ```
 
 ### Position Restore
@@ -102,14 +156,14 @@ dt dt c5 d5  # Each note is 0.25 beats
 Move the position back to the start using `|`. This is useful for writing chords or multiple voices.
 
 ```
-c5 | e5 | g5   # C major chord
+c5 | e | g     # C major chord (c5 e5 g5)
 ```
 
 Two voices:
 
 ```
-| c5 g5 e5.2
-| c4.2 f4.2
+| c5 g e.2
+| c4.2 f.2
 ```
 
 ### Blocks
@@ -123,42 +177,51 @@ Blocks are delimited with `{` and `}`. They affect how commands work:
 ```
 {
   dt
-  c5 { dt e5 f5 } d5.2 e5 g5 a5 c6
+  c5 { dt e f } d.2 e g a c
 }
 |
-{ ht g4 f4 }
+{ ht g4 f }
 ```
 
 ### Measures
 
-The `m` command moves the position to a specific measure. Commonly used with blocks:
+The `m` command moves the position to the start of a measure boundary, useful for aligning notes. Measure boundaries are determined by the current time signature. Use `m` alone to auto-increment to the next measure, or `m0`, `m1`, etc. for explicit positioning:
 
 ```
-m0 {
-  | c5 c5 a5 g5
+m {
+  | c5 c a g
   | g4.4
 }
 
-m1 {
-  | d5 d5 a5 e5
+m {
+  | d5 d a e
   | f4.4
 }
 ```
 
+The first `m` goes to measure 0, then each subsequent `m` increments. Explicit measure numbers also update the counter:
+
+```
+m { c d }      # measure 0
+m { e f }      # measure 1
+m5 { g a }     # measure 5
+m { b c }      # measure 6
+```
+
 ### Key Signature
 
 Set the key signature with `ks` followed by the number of sharps (positive) or flats (negative). Notes are automatically adjusted to match the key.
 
 ```
-ks2      # D major (2 sharps: F#, C#)
-c5 d5 e5 f5   # F becomes F#, C becomes C#
+ks2          # D major (2 sharps: F#, C#)
+c d e f      # F becomes F#, C becomes C#
 ```
 
 Use `=` to override the key signature with a natural:
 
 ```
 ks-2
-b5 c5 b=5   # B natural
+b c b=       # B natural
 ```
 
 ### Time Signature
@@ -167,18 +230,69 @@ Set the time signature with `ts`:
 
 ```
 ts3/4
-c5 d5 e5
+c d e
 ```
 
 This affects beats per measure and where measure lines appear.
 
+Time signatures can change mid-song. Notes are placed sequentially regardless of time signature changes:
+
+```
+ts4/4
+c d e f      # 4 beats in 4/4
+ts3/4
+g a b        # 3 beats in 3/4
+ts4/4
+c d e f      # 4 beats in 4/4
+```
+
+Time signature changes are tracked and accessible via `song.timeSignatures`:
+
+```typescript
+const song = SongParser.load("ts3/4 c d e ts4/4 f g a b")
+console.log(song.timeSignatures)
+// [[0, 3], [3, 4]]  // [beat_position, beats_per_measure]
+```
+
+### Measures API
+
+Measures are implicitly created based on the time signature and the duration of notes in the song. Use `getMeasures()` to get an array of measure boundaries, useful for drawing grid lines or measure markers:
+
+```typescript
+const song = SongParser.load("c5 d e f g a b c")  // 8 beats in 4/4
+const measures = song.getMeasures()
+// [{ start: 0, beats: 4 }, { start: 4, beats: 4 }]
+```
+
+This correctly handles time signature changes:
+
+```typescript
+const song = SongParser.load(`
+  ts4/4 c d e f    # 4 beats
+  ts3/4 g a b      # 3 beats
+  ts4/4 c d e f    # 4 beats
+`)
+const measures = song.getMeasures()
+// [
+//   { start: 0, beats: 4 },
+//   { start: 4, beats: 3 },
+//   { start: 7, beats: 4 }
+// ]
+```
+
+Each measure object contains:
+- `start`: Beat position where the measure begins
+- `beats`: Number of beats in this measure
+
+Note: The `m` command (see [Measures](#measures)) is used to align notes to measure boundaries during composition, but is not required—`getMeasures()` computes measure boundaries from the time signature regardless of whether `m` was used.
+
 ### Chords
 
 The `$` command specifies a chord symbol for auto-chord generation:
 
 ```
-{$G c5.2 a5 d5}
-{$Dm e5 f5 g5.2}
+{$G c5.2 a d}
+{$Dm e f g.2}
 ```
 
 Supported chord types: `M`, `m`, `dim`, `dim7`, `dimM7`, `aug`, `augM7`, `M6`, `m6`, `M7`, `7`, `m7`, `m7b5`, `mM7`
@@ -188,8 +302,8 @@ Supported chord types: `M`, `m`, `dim`, `dim7`, `dimM7`, `aug`, `augM7`, `M6`, `
 Songs can have multiple tracks, numbered starting from 0. Use `t` to switch tracks:
 
 ```
-t0 c5 d5 e5
-t1 g3 g3 g3
+t0 c5 d e
+t1 g3 g g
 ```
 
 ### Clefs
@@ -197,8 +311,52 @@ t1 g3 g3 g3
 Set the clef with `/g` (treble), `/f` (bass), or `/c` (alto):
 
 ```
-/g c5 d5 e5
-/f c3 d3 e3
+/g c5 d e
+/f c3 d e
+```
+
+Clefs are stored as track metadata, not on individual notes. They hint to renderers which staff to use for displaying the track. Each track supports a single clef assignment. When no clef is specified, the staff is auto-detected based on the note range:
+
+- Notes primarily above middle C → treble staff
+- Notes primarily below middle C → bass staff
+- Notes spanning both ranges → grand staff (treble + bass)
+
+Clefs are accessible via `track.clefs`:
+
+```typescript
+const song = SongParser.load("/f c3 d e")
+console.log(song.tracks[0].clefs)
+// [[0, "f"]]  // [position, clefType]
+```
+
+### Strings
+
+Quoted strings can be placed anywhere in a song. They are tagged with their position in beats and stored separately from notes. This is useful for lyrics or annotations.
+
+```
+c "hel" d "lo" e "world"
+```
+
+Both single and double quotes are supported. Strings can span multiple lines:
+
+```
+c.2 'First verse
+continues here' d.2
+```
+
+Escape sequences are supported: `\"`, `\'`, `\\`, `\n`.
+
+```
+"say \"hello\""
+'it\'s working'
+```
+
+Strings are accessible via `song.strings`:
+
+```typescript
+const song = SongParser.load('c "la" d "la"')
+console.log(song.strings)
+// [[1, "la"], [2, "la"]]  // [position, text]
 ```
 
 ### Comments
@@ -206,11 +364,44 @@ Set the clef with `/g` (treble), `/f` (bass), or `/c` (alto):
 Text after `#` is ignored:
 
 ```
-c5 d5  # this is a comment
+c d    # this is a comment
 # full line comment
-e5 f5
+e f
+```
+
+### Frontmatter
+
+Metadata can be embedded at the start of a file using comment-style frontmatter. Lines matching `# key: value` at the very beginning (before any commands) are parsed as metadata:
+
+```
+# title: Moonlight Sonata
+# author: Beethoven
+# bpm: 120
+# difficulty: intermediate
+
+ts4/4 ks-3
+c d e f
 ```
 
+The convention is to use lowercase key names. Frontmatter is accessible via `song.metadata.frontmatter`:
+
+```typescript
+const song = SongParser.load(`
+# title: My Song
+# bpm: 90
+c d e
+`)
+
+console.log(song.metadata.frontmatter)
+// { title: "My Song", bpm: "90" }
+```
+
+Notes:
+- Frontmatter must appear at the start of the file, before any music commands
+- Keys are case-sensitive
+- All values are stored as strings
+- Once a non-frontmatter line is encountered, subsequent `# key: value` lines are treated as regular comments
+
 ## Music Theory Utilities
 
 The library also exports music theory utilities:
@@ -243,6 +434,34 @@ key.name()  // "D"
 key.accidentalNotes()  // ["F", "C"]
 ```
 
+## Limitations
+
+Current limitations that may be addressed in future versions:
+
+- **Clefs are per-track**: Each track supports only a single clef. Mid-track clef changes are not supported.
+
+- **Key signature metadata is global**: While key signatures (`ks`) can change mid-song and correctly affect note parsing, the metadata only stores the final value. Renderers cannot determine where key signature changes occur within the song. (Time signature changes are tracked via `song.timeSignatures` and `song.getMeasures()`.)
+
+- **Time signature changes should be placed at measure boundaries**: Time signatures are recorded at the cursor position when parsed. When combined with measure markers (`m`) and notes that extend past measure boundaries, the recorded position may not align with where the measure actually starts. For predictable behavior, place time signature changes immediately after a measure marker (which positions the cursor at the boundary):
+
+```
+# Recommended: time signature is always applied at start of measure
+m ts4/4 c d e f
+m ts3/4 g a b
+
+# Although you can also write it before the m command, if the previous measure
+# accidentally pushed the cursor into the next measure then the time signature
+# application will be delayed a measure:
+
+ts3/4
+m g.4       # extends 1 beat past 3-beat measure
+ts4/4       # recorded at beat 4, but next measure starts at beat 3
+m a b c d
+
+```
+
+- **No explicit grand staff**: Grand staff is only available through auto-detection when notes span both treble and bass registers. There is no syntax to explicitly request a grand staff.
+
 ## License
 
 MIT

package/dist/grammar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../src/grammar.js"],"names":[],"mappings":"AAg2CA,8CAEE;AA71CF;IAwCE,uDA2GC;IAlJD,oEAMC;IAJC,cAAwB;IACxB,WAAkB;IAClB,cAAwB;IAI1B,6BA6BC;CA8GF;AAED,0DAmsCC"}
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../src/grammar.js"],"names":[],"mappings":"AAuoEA,8CAGE;AAroEF;IAwCE,uDA2GC;IAlJD,oEAMC;IAJC,cAAwB;IACxB,WAAkB;IAClB,cAAwB;IAI1B,6BA6BC;CA8GF;AAED,0DA0+DC"}