tocparser 0.1.0__py3-none-any.whl

tocparser/__init__.py

@@ -0,0 +1,88 @@
+"""Parse and write cdrdao TOC files.
+
+>>> from tocparser import parse, dumps
+>>> toc = parse('CD_DA\\nTRACK AUDIO\\nFILE "hurt.wav" 0\\n')
+>>> toc.tracks[0].mode.value
+'AUDIO'
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from tocparser.errors import (
+    Loc,
+    TocError,
+    TocParseError,
+    TocValidationError,
+)
+from tocparser.models import (
+    CdText,
+    CdTextBlock,
+    CdTextEncoding,
+    CdTextItemName,
+    CdTextValue,
+    ContentItem,
+    DataFile,
+    DataMode,
+    DiscType,
+    End,
+    Fifo,
+    File,
+    Silence,
+    Start,
+    SubChannelMode,
+    Toc,
+    Track,
+    TrackMode,
+    TrackStatement,
+    Zero,
+)
+from tocparser.parser import parse, parse_file
+from tocparser.serializer import dump, dumps
+from tocparser.times import (
+    FRAMES_PER_SECOND,
+    SAMPLES_PER_FRAME,
+    SECONDS_PER_MINUTE,
+    Msf,
+    Time,
+)
+
+__version__ = version("tocparser")
+
+__all__ = [
+    "FRAMES_PER_SECOND",
+    "SAMPLES_PER_FRAME",
+    "SECONDS_PER_MINUTE",
+    "CdText",
+    "CdTextBlock",
+    "CdTextEncoding",
+    "CdTextItemName",
+    "CdTextValue",
+    "ContentItem",
+    "DataFile",
+    "DataMode",
+    "DiscType",
+    "End",
+    "Fifo",
+    "File",
+    "Loc",
+    "Msf",
+    "Silence",
+    "Start",
+    "SubChannelMode",
+    "Time",
+    "Toc",
+    "TocError",
+    "TocParseError",
+    "TocValidationError",
+    "Track",
+    "TrackMode",
+    "TrackStatement",
+    "Zero",
+    "__version__",
+    "dump",
+    "dumps",
+    "parse",
+    "parse_file",
+]

tocparser/errors.py

@@ -0,0 +1,80 @@
+"""Exceptions raised by :mod:`tocparser`."""
+
+from __future__ import annotations
+
+from typing import TypeAlias
+
+__all__ = [
+    "Loc",
+    "TocError",
+    "TocParseError",
+    "TocValidationError",
+]
+
+#: A path into a model, made of field names and indexes, e.g.
+#: ``("tracks", 0, "statements", 2)``.
+Loc: TypeAlias = tuple[str | int, ...]
+
+
+class TocError(Exception):
+    """Base class for every error raised by :mod:`tocparser`."""
+
+
+class TocParseError(TocError):
+    """The input is not syntactically valid.
+
+    Mirrors cdrdao's ``file:line: message`` reporting.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        line: int | None = None,
+        column: int | None = None,
+        filename: str | None = None,
+    ) -> None:
+        self.message = message
+        self.line = line
+        self.column = column
+        self.filename = filename
+        super().__init__(_format_location(message, filename, line, column))
+
+
+class TocValidationError(TocError):
+    """The input breaks a rule cdrdao itself enforces.
+
+    ``loc`` locates the problem inside the model that raised it, so an error
+    raised while building models by hand still says where it is. ``line`` is
+    only known when the error comes from parsing text.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        line: int | None = None,
+        filename: str | None = None,
+        loc: Loc = (),
+    ) -> None:
+        self.message = message
+        self.line = line
+        self.filename = filename
+        self.loc = loc
+        super().__init__(_format_location(message, filename, line, None))
+
+
+def _format_location(
+    message: str,
+    filename: str | None,
+    line: int | None,
+    column: int | None,
+) -> str:
+    location = ""
+    if filename is not None:
+        location += f"{filename}:"
+    if line is not None:
+        location += f"{line}:"
+        if column is not None:
+            location += f"{column}:"
+    return f"{location} {message}" if location else message

tocparser/grammar.lark

@@ -0,0 +1,89 @@
+// Grammar for cdrdao TOC files.
+//
+// Derived from cdrdao's own ANTLR grammar, trackdb/TocParser.g at tag
+// rel_1_2_6, and the TOC FILES section of cdrdao(1). Where the two disagree
+// the grammar is the authority: FIRST_TRACK_NO, END, CD_I, MODE0, SWAP,
+// #offset, RESERVED1..RESERVED4, CLOSED, ENCODING_* and the string escapes are
+// all missing from the man page. Rule and token names follow TocParser.g so the
+// two can be compared side by side.
+
+toc: (catalog | disc_type)* first_track_no? cd_text_global? track+
+
+catalog:        "CATALOG" STRING
+disc_type:      DISC_TYPE
+first_track_no: "FIRST_TRACK_NO" INT
+
+track: "TRACK" MODE SUB_CHANNEL_MODE? track_flag* cd_text_track? pregap? \
+       track_statement+ index*
+
+?track_flag:        isrc | copy | pre_emphasis | channels
+isrc:               "ISRC" STRING
+copy:               NO? "COPY"
+pre_emphasis:       NO? "PRE_EMPHASIS"
+channels:           CHANNELS
+
+pregap:             "PREGAP" msf
+index:              "INDEX" msf
+
+?track_statement:   file | datafile | fifo | silence | zero | start | end
+
+file:               FILE_KEYWORD STRING SWAP? offset? time time?
+datafile:           "DATAFILE" STRING offset? time?
+fifo:               "FIFO" STRING time
+silence:            "SILENCE" time
+zero:               "ZERO" MODE? SUB_CHANNEL_MODE? time
+start:              "START" msf?
+end:                "END" msf?
+
+offset:             "#" INT
+msf:                MSF
+time:               MSF | INT
+
+// A global CD_TEXT block may open with a language map; a track one may not.
+cd_text_global:     "CD_TEXT" "{" language_map? cd_text_block* "}"
+cd_text_track:      "CD_TEXT" "{" cd_text_block* "}"
+
+language_map:       "LANGUAGE_MAP" "{" language_map_entry+ "}"
+language_map_entry: INT ":" language_code
+language_code:      INT | LANGUAGE_EN
+
+// cdrdao 1.2.5 added an optional encoding at the top of a language block.
+cd_text_block:      "LANGUAGE" INT "{" CD_TEXT_ENCODING? cd_text_item* "}"
+cd_text_item:       CD_TEXT_ITEM cd_text_value
+cd_text_value:      STRING | binary_data
+binary_data:        "{" (INT ("," INT)*)? "}"
+
+NO:                 "NO"
+SWAP:               "SWAP"
+LANGUAGE_EN:        "EN"
+CHANNELS:           "TWO_CHANNEL_AUDIO" | "FOUR_CHANNEL_AUDIO"
+FILE_KEYWORD:       "AUDIOFILE" | "FILE"
+DISC_TYPE:          "CD_DA" | "CD_ROM_XA" | "CD_ROM" | "CD_I"
+
+CD_TEXT_ENCODING: "ENCODING_ISO_8859_1" | "ENCODING_ASCII" | "ENCODING_MS_JIS" \
+                | "ENCODING_KOREAN" | "ENCODING_MANDARIN"
+
+// MODE0 is only legal after ZERO; the transformer rejects it as a track mode.
+MODE: "MODE1_RAW" | "MODE1" | "MODE2_FORM_MIX" | "MODE2_FORM1" | "MODE2_FORM2" \
+    | "MODE2_RAW" | "MODE2" | "MODE0" | "AUDIO"
+
+SUB_CHANNEL_MODE:   "RW_RAW" | "RW"
+
+CD_TEXT_ITEM: "TITLE" | "PERFORMER" | "SONGWRITER" | "COMPOSER" | "ARRANGER" \
+            | "MESSAGE" | "DISC_ID" | "GENRE" | "TOC_INFO1" | "TOC_INFO2" \
+            | "RESERVED1" | "RESERVED2" | "RESERVED3" | "RESERVED4" \
+            | "CLOSED" \
+            | "UPC_EAN" | "ISRC" | "SIZE_INFO"
+
+// Inside a string a backslash may only introduce another backslash, a quote,
+// or three digits; cdrdao rejects any other use of one. Raw newlines and tabs
+// are accepted, as cdrdao accepts them.
+STRING: /"(?:\\[0-9][0-9][0-9]|\\["\\]|[^"\\])*"/
+
+MSF.2:   /[0-9]+:[0-9]+:[0-9]+/
+INT:     /[0-9]+/
+COMMENT: /\/\/[^\n]*/
+
+%import common.WS
+%ignore WS
+%ignore COMMENT