Parser

Parse .chart source strings into typed song trees.

Functions

parseBar

parseBar(input: string): Bar

Parse a single bar expression (e.g. `'| C . G |'`).

parseChord

parseChord(input: string): Chord

Parse a single chord token (e.g. `'Bbm7'`). Useful for one-off chord parsing outside of a full chart.

parseFrontMatter

parseFrontMatter(input: string): FrontMatter

Parse only the front-matter block of a `.chart` file.

parseRow

parseRow(input: string): Row

Parse a single row (one line of bars).

parseSong

parseSong(input: string): Song

Parse a complete `.chart` source string into a `Song` tree. Throws a `PeggyError` on parse failure.

Types

Bar interface

A bar containing beat cells. `cells` always contains at least one chord cell. `timeSignature` is set only when the bar carries an explicit `(n/d)` annotation.

cells: BeatCell[]

closeBarline: Barline

loc?: SourceRange

timeSignature?: TimeSignature

Explicit time-signature annotation on this bar, e.g. `(6/8)`.

tonalityHints?: TonalityHintItem[]

type: "bar"

Barline interface

A barline with an optional explicit repeat count. `repeatCount` is only set when the source carries an explicit `x3`-style count.

kind: BarlineKind

repeatCount?: number

Explicit repeat count (e.g. `3` from `x3`). Only present when the source includes a count.

Chord interface

A single chord as parsed. `root` is the letter name including any accidentals (e.g. `'Bb'`, `'F#'`). `bass` is the optional slash-chord bass note.

bass?: string

Optional slash-chord bass note.

loc?: SourceRange

quality: Quality

root: string

Letter name including any accidentals (e.g. `'Bb'`, `'F#'`).

type: "chord"

ChordCell interface

A chord occupying one beat cell within a bar.

chord: Chord

loc?: SourceRange

type: "chord"

CommentLine interface

A comment line in the source. `text` includes the leading `#` character.

loc?: SourceRange

text: string

Raw comment text including the leading `#` character.

type: "comment"

DotCell interface

`type: 'dot'` — a sustain mark (`.`) that holds the previous chord for one beat.

loc?: SourceRange

type: "dot"

FrontMatter interface

Parsed front-matter block from the top of a `.chart` file.

key: string | null

loc?: SourceRange

meter: string | null

Raw meter string from front matter (e.g. `'4/4'`, `'mixed'`, or `null`).

title: string | null

type: "frontMatter"

Row interface

A horizontal line of bars sharing an opening barline.

bars: Bar[]

loc?: SourceRange

openBarline: Barline

type: "row"

Section interface

A labelled section of the chart. `rows` contains only `Row` nodes; `content` interleaves rows and comment lines in document order and is more useful for display.

content?: SectionItem[]

Rows and inline comments in document order (more useful for display than `rows` alone).

key: string | null

label: string | null

loc?: SourceRange

preamble?: CommentLine[]

Comment lines appearing before the section label.

rows: Row[]

type: "section"

Song interface

Top-level parse result for a `.chart` file. `key` comes from front matter; `meter` is the raw string from front matter (e.g. `'4/4'`, `'mixed'`, or `null`).

key: string | null

Key string from front matter (e.g. `'Am'`, `'G mixolydian'`).

loc?: SourceRange

meter: string | null

Raw meter string from front matter (e.g. `'4/4'`, `'mixed'`, or `null`).

sections: Section[]

title: string | null

type: "song"

SourceRange interface

LSP-style source location (0-based line/character). Present on most tree nodes when the input was parsed with location tracking.

end: { character: number; line: number }

start: { character: number; line: number }

TimeSignature interface

Numerator/denominator pair (e.g. 6/8 → `{ numerator: 6, denominator: 8 }`).

denominator: number

numerator: number

TonalityHintItem interface

Inline key annotation in the source (e.g. `[Am]`), placed between beat cells. `beforeCellIndex` is the cell index the hint precedes.

beforeCellIndex: number

Index of the cell this hint precedes.

key: string

loc?: SourceRange

BarlineKind type

Barline variant. - `'single'` — plain `|` - `'double'` — `||` - `'final'` — `||.` - `'startRepeat'` — `||:` - `'endRepeat'` — `:||` - `'endRepeatStartRepeat'` — `:||:`

type BarlineKind = "single" | "double" | "final" | "startRepeat" | "endRepeat" | "endRepeatStartRepeat"

BeatCell type

Discriminated union of the two cell kinds inside a bar.

type BeatCell = ChordCell | DotCell

Quality type

Chord quality. The source syntax that maps to each variant is shown in the renderer-interface guide.

type Quality = "major" | "minor" | "dominant7" | "halfDiminished" | "diminished" | "maj7" | "min7" | "dim7" | "dom7flat5" | "dom9" | "dom11" | "dom13" | "dom7flat9" | "dom7sharp9" | "dom7sharp5" | "dom7flat13" | "sus4" | "sus2" | "add6"

SectionItem type

type SectionItem = Row | CommentLine