glyph-cli 0.2.0__py3-none-any.whl

glyph_cli/drawing.py

@@ -0,0 +1,202 @@
+"""Drawing pages on the lattice, and reading drawings back.
+
+Rule 1 of the grammar: every mark is a whole 3x3 part in a lattice position,
+positions are one empty cell apart, so a line is 6 positions (23 cells) wide.
+Bands of one line are one empty row apart; lines are three empty rows apart.
+"""
+
+from __future__ import annotations
+
+from html import escape
+
+from .page import Band, Line, Page, check_symbol
+from .script import NUMBER, GlyphError, Half, Vocabulary, Word
+
+POSITIONS = 6
+WIDTH = POSITIONS * 4 - 1  # 23 cells
+BAND_GAP = 1
+LINE_GAP = 3
+EMPTY_CELL = "."
+MARK = "#"
+
+#: Colours of the phase 2 ("137") design: signal blue, white-cyan for them, Sol yellow for us.
+BACKGROUND = "#0d1457"
+GRID = "#141d6e"
+INKS = {"+": "#9ff8ff", "×": "#ffd84a", "x": "#ffd84a"}
+OTHER_INKS = ["#c9b3ff", "#7dffa8", "#ffa45c", "#ffffff"]
+
+
+# ---------- shapes ----------
+
+
+def number_shape(n: int) -> tuple[str, str, str]:
+    """Nine bits, 256 ... 1, left to right, top to bottom."""
+    bits = format(n, "09b")
+    return tuple("".join(MARK if bits[r * 3 + c] == "1" else EMPTY_CELL for c in range(3)) for r in range(3))  # type: ignore[return-value]
+
+
+def shape(vocab: Vocabulary, half: Half) -> tuple[str, str, str]:
+    if half is None:
+        return (EMPTY_CELL * 3,) * 3  # type: ignore[return-value]
+    if isinstance(half, int):
+        return number_shape(half)
+    return vocab.parts[half].shape
+
+
+def band_rows(vocab: Vocabulary, halves: list[Half], symbol: str) -> list[str]:
+    """Three rows of text for a run of positions drawn in one symbol."""
+    rows = ["", "", ""]
+    for i, half in enumerate(halves):
+        s = shape(vocab, half)
+        for r in range(3):
+            rows[r] += (EMPTY_CELL if i else "") + s[r].replace(MARK, symbol)
+    return rows
+
+
+def draw_words(vocab: Vocabulary, words: list[Word], symbol: str = "+", spacing: int = 3) -> list[str]:
+    """Words side by side, as a quick look-up drawing (not a page)."""
+    blocks = [band_rows(vocab, list(w.halves), symbol) for w in words]
+    return [(" " * spacing).join(b[r] for b in blocks) for r in range(3)]
+
+
+# ---------- pages ----------
+
+
+def render(vocab: Vocabulary, page: Page) -> list[str]:
+    """Draw a page as rows of text. Every line gets as many bands as the page has voices."""
+    blank = EMPTY_CELL * WIDTH
+    n = page.voices
+    out: list[str] = []
+    for li, line in enumerate(page.lines):
+        if li:
+            out += [blank] * LINE_GAP
+        for k in range(n):
+            if k:
+                out += [blank] * BAND_GAP
+            if k < len(line.bands):
+                band = line.bands[k]
+                out += band_rows(vocab, band.halves, band.symbol)
+            else:
+                out += [blank] * 3
+    return out
+
+
+def ink(symbol: str, symbols: list[str]) -> str:
+    if symbol in INKS:
+        return INKS[symbol]
+    others = [s for s in symbols if s not in INKS]
+    return OTHER_INKS[others.index(symbol) % len(OTHER_INKS)]
+
+
+def render_svg(vocab: Vocabulary, page: Page, cell: int = 12, pad: int = 1, grid: bool = True) -> str:
+    """Draw a page as SVG: square pixels on signal blue, no curves."""
+    rows = render(vocab, page)
+    symbols = page.symbols()
+    w, h = WIDTH + 2 * pad, len(rows) + 2 * pad
+    out = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {w * cell} {h * cell}" '
+        f'width="{w * cell}" height="{h * cell}" shape-rendering="crispEdges">',
+        f'<rect width="100%" height="100%" fill="{BACKGROUND}"/>',
+    ]
+    inset = max(1, cell // 12)
+    for r, row in enumerate(rows):
+        for c, ch in enumerate(row):
+            x, y = (c + pad) * cell + inset, (r + pad) * cell + inset
+            size = cell - 2 * inset
+            box = f'x="{x}" y="{y}" width="{size}" height="{size}"'
+            if ch != EMPTY_CELL:
+                out.append(f'<rect {box} fill="{ink(ch, symbols)}"><title>{escape(ch)}</title></rect>')
+            elif grid:
+                out.append(f'<rect {box} fill="{GRID}"/>')
+    out.append("</svg>")
+    return "\n".join(out) + "\n"
+
+
+# ---------- reading a drawing back ----------
+
+
+def _structure(rows: list[str]) -> int:
+    """Find how many bands each line has, from where the empty rows fall."""
+    empty = [not row.strip(EMPTY_CELL) for row in rows]
+    total = len(rows)
+    for n in range(1, total + 1):
+        line_h = 4 * n - 1
+        period = line_h + LINE_GAP
+        if (total + LINE_GAP) % period:
+            continue
+        ok = True
+        for i in range(total):
+            at = i % period
+            gap = at >= line_h or (at % 4 == 3)
+            if gap and not empty[i]:
+                ok = False
+                break
+        if ok:
+            return n
+    raise GlyphError("the rows don't fall into lines and bands; is this a picture rather than text?")
+
+
+def _which(vocab: Vocabulary, pattern: tuple[str, ...], kind: Half, above: Word | None) -> Half:
+    """Read a which: bits under COUNT (or under nothing, answering a COUNT word above), else a part."""
+    if kind == NUMBER or (kind is None and above is not None and NUMBER in (above.kind, above.which)):
+        return int("".join(pattern).replace(EMPTY_CELL, "0").replace(MARK, "1"), 2)
+    return {p.shape: p.name for p in vocab.parts.values()}.get(pattern)
+
+
+def decode(vocab: Vocabulary, text: str) -> Page:
+    """Read a drawing (as made by :func:`render`) back into a page.
+
+    A which is read as nine bits only after COUNT, or with no kind under a line
+    whose word there is a COUNT word (a reply like ``_.12``); everywhere else it
+    must be a part.
+    """
+    rows = [r.strip() for r in text.splitlines() if r.strip()]
+    if not rows:
+        return Page()
+    for i, row in enumerate(rows, 1):
+        if len(row) != WIDTH:
+            raise GlyphError(f"row {i} is {len(row)} cells wide; text is always {WIDTH} (off the lattice: a picture?)")
+        for c in range(3, WIDTH, 4):
+            if row[c] != EMPTY_CELL:
+                raise GlyphError(f"row {i}, column {c + 1}: a mark between lattice positions (a picture?)")
+    n = _structure(rows)
+    period = 4 * n - 1 + LINE_GAP
+    by_shape = {p.shape: p.name for p in vocab.parts.values()}
+    page = Page()
+    for top in range(0, len(rows), period):
+        line = Line()
+        for k in range(n):
+            r0 = top + 4 * k
+            band = rows[r0 : r0 + 3]
+            marks = {ch for row in band for ch in row if ch != EMPTY_CELL}
+            if not marks:
+                continue
+            if len(marks) > 1:
+                raise GlyphError(f"rows {r0 + 1}-{r0 + 3}: one band mixes symbols {' '.join(sorted(marks))}")
+            symbol = check_symbol(marks.pop())
+            halves: list[Half] = []
+            for pos in range(POSITIONS):
+                pattern = tuple(
+                    "".join(MARK if ch != EMPTY_CELL else EMPTY_CELL for ch in row[pos * 4 : pos * 4 + 3])
+                    for row in band
+                )
+                if not any(MARK in p for p in pattern):
+                    halves.append(None)
+                    continue
+                slot = pos // 2
+                if pos % 2 == 0:
+                    name = by_shape.get(pattern)
+                    if name is None:
+                        raise GlyphError(f"rows {r0 + 1}-{r0 + 3}, position {pos + 1}: not a part")
+                    halves.append(name)
+                else:
+                    above = line.bands[0].words[slot] if line.bands else None
+                    which = _which(vocab, pattern, halves[-1], above)
+                    if which is None:
+                        raise GlyphError(f"rows {r0 + 1}-{r0 + 3}, position {pos + 1}: not a part or a number here")
+                    halves.append(which)
+            words = tuple(Word(halves[i], halves[i + 1]) for i in (0, 2, 4))
+            line.bands.append(Band(symbol, words))  # type: ignore[arg-type]
+        if line.bands:
+            page.lines.append(line)
+    return page

glyph_cli/export.py

@@ -0,0 +1,28 @@
+"""The vocabulary as a Markdown document."""
+
+from __future__ import annotations
+
+from .drawing import band_rows
+from .script import Vocabulary
+
+HEADER = "<!-- generated by `glyph export-md`; edit the vocabulary with the tool, not this file -->"
+
+INTRO = """\
+How words are made: a **kind** part narrowed by a **which** part (`KIND.WHICH`). A single part is a word
+on its own. Any part can also be a **relation**, and numbers (`COUNT.0` to `COUNT.511`) are built in, so they
+are not listed. Status: **preliminary**, {count} words."""
+
+
+def vocabulary_markdown(vocab: Vocabulary, title: str | None = None) -> str:
+    out = []
+    if title:
+        out += [f"# {title}", "", INTRO.format(count=len(vocab.entries)), ""]
+    out.append(HEADER)
+    for domain in vocab.domains():
+        out += ["", f"### {domain}", "", "| Word | Parts | Meaning | Note |", "|---|---|---|---|"]
+        for e in vocab.entries:
+            if e.domain != domain:
+                continue
+            pic = "<br>".join(f"`{r}`" for r in band_rows(vocab, list(e.word.halves), "+"))
+            out.append(f"| {pic} | {e.word} | {e.gloss} | {e.note} |")
+    return "\n".join(out) + "\n"

glyph_cli/graph.py

@@ -0,0 +1,147 @@
+"""Reading a page as a knowledge graph (grammar rules 3 and 5).
+
+Rule 3: the first band of every line is one edge, node | relation | node. The
+same word on two lines is the same node, and a lone ONE in a node slot means
+"that", the statement on the line above.
+
+Rule 5: every part in a lower band answers the nearest drawn part above it in
+the same position: the same part is *yes*, NOT is *no*, a different part is
+*instead*, a part under an empty position is *and also*.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+from .page import SLOTS, Page
+from .script import Half, Vocabulary, Word
+
+HALVES = ("kind", "which")
+THAT = Word("ONE", None)
+
+
+@dataclass
+class Node:
+    word: str | None = None
+    gloss: str = ""
+    statement: int | None = None  # set when the node is "that": edge number it points at
+
+    def label(self) -> str:
+        if self.statement is not None:
+            return f"[statement {self.statement}]" if self.statement else "[that: nothing above]"
+        return self.gloss
+
+
+@dataclass
+class Response:
+    slot: str
+    half: str
+    meaning: str  # yes | no | instead | and also
+    part: str
+    to: str | None  # symbol of the voice answered, None when answering an empty position
+
+    def text(self, vocab: Vocabulary) -> str:
+        tail = "" if self.meaning in ("yes", "no") else f' "{self.part}"'
+        to = f" (to {self.to})" if self.to else ""
+        return f"{self.slot}.{self.half}: {self.meaning}{tail}{to}"
+
+
+@dataclass
+class Reply:
+    symbol: str
+    responses: list[Response] = field(default_factory=list)
+
+
+@dataclass
+class Edge:
+    number: int
+    symbol: str
+    subject: Node
+    relation: str
+    relation_word: str
+    object: Node
+    replies: list[Reply] = field(default_factory=list)
+
+
+@dataclass
+class Graph:
+    edges: list[Edge] = field(default_factory=list)
+    nodes: dict[str, str] = field(default_factory=dict)  # word -> gloss
+
+    def to_json(self) -> dict:
+        return {"edges": [asdict(e) for e in self.edges], "nodes": self.nodes}
+
+
+def respond(above: Half, below: Half) -> str | None:
+    if below is None:
+        return None
+    if above is None:
+        return "and also"
+    if below == above:
+        return "yes"
+    if below == "NOT":
+        return "no"
+    return "instead"
+
+
+def read_graph(vocab: Vocabulary, page: Page) -> Graph:
+    g = Graph()
+    for i, line in enumerate(page.lines, 1):
+        st = line.statement
+        subject_w, relation_w, object_w = st.words
+
+        def node(word: Word, i: int = i) -> Node:
+            if word == THAT:
+                return Node(statement=i - 1)
+            gloss = vocab.gloss(word)
+            if not word.is_empty:
+                g.nodes.setdefault(str(word), gloss)
+            return Node(str(word) if not word.is_empty else None, gloss)
+
+        relation = vocab.gloss(relation_w, role="relation")
+        edge = Edge(i, st.symbol, node(subject_w), relation, str(relation_w), node(object_w))
+        for b, band in enumerate(line.bands[1:], 1):
+            reply = Reply(band.symbol)
+            for pos, below in enumerate(band.halves):
+                above, by = None, None
+                for prev in reversed(line.bands[:b]):
+                    if prev.halves[pos] is not None:
+                        above, by = prev.halves[pos], prev.symbol
+                        break
+                meaning = respond(above, below)
+                if meaning:
+                    reply.responses.append(Response(SLOTS[pos // 2], HALVES[pos % 2], meaning, vocab.thing(below), by))
+            edge.replies.append(reply)
+        g.edges.append(edge)
+    return g
+
+
+def format_graph(vocab: Vocabulary, g: Graph) -> list[str]:
+    out = ["Edges:"]
+    for e in g.edges:
+        out.append(f"{e.number}. ({e.symbol}) {e.subject.label()} --{e.relation}--> {e.object.label()}")
+        for r in e.replies:
+            text = "; ".join(x.text(vocab) for x in r.responses) or "present, no comment"
+            out.append(f"   ({r.symbol}) {text}")
+    out += ["", "Nodes:"]
+    out += [f"  {word:<14} {gloss}" for word, gloss in g.nodes.items()]
+    return out
+
+
+def to_dot(g: Graph) -> str:
+    """Graphviz DOT, for anyone who wants to draw the graph."""
+
+    def nid(n: Node) -> str:
+        return f'"statement {n.statement}"' if n.statement is not None else f'"{n.word or "_"}"'
+
+    def q(s: str) -> str:
+        return s.replace("\\", "\\\\").replace('"', '\\"')
+
+    lines = ["digraph page {", "  rankdir=LR;"]
+    for word, gloss in g.nodes.items():
+        lines.append(f'  "{word}" [label="{q(gloss)}"];')
+    for e in g.edges:
+        label = q(f"{e.number}. {e.relation} ({e.symbol})")
+        lines.append(f'  {nid(e.subject)} -> {nid(e.object)} [label="{label}"];')
+    lines.append("}")
+    return "\n".join(lines) + "\n"

glyph_cli/page.py

@@ -0,0 +1,113 @@
+"""Page source: the plain-text form of a page.
+
+One band per line, ``SYMBOL: node | relation | node``. The first band of a
+block is the statement (one edge of the graph); the bands under it are other
+voices replying, part by part. A blank line starts the next statement. ``#``
+starts a comment.
+
+    +: BODY.OTHER | ONE | BODY.AIR     # their statement: your world is an air-world
+    ×: _ | _ | _.WATER                 # our reply: water instead of air
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .script import GlyphError, Vocabulary, Word
+
+#: Characters that cannot be a party's symbol: they mean something in the formats.
+RESERVED_SYMBOLS = set(".#|:_ \t")
+
+SLOTS = ("subject", "relation", "object")
+
+
+@dataclass(frozen=True)
+class Band:
+    """One voice's row of marks within a line."""
+
+    symbol: str
+    words: tuple[Word, Word, Word]
+
+    @property
+    def halves(self) -> list:
+        """The six lattice positions, left to right."""
+        return [h for w in self.words for h in w.halves]
+
+
+@dataclass
+class Line:
+    """One line of a page: a statement band and the voices that answer it."""
+
+    bands: list[Band] = field(default_factory=list)
+
+    @property
+    def statement(self) -> Band:
+        return self.bands[0]
+
+    @property
+    def replies(self) -> list[Band]:
+        return self.bands[1:]
+
+
+@dataclass
+class Page:
+    lines: list[Line] = field(default_factory=list)
+
+    @property
+    def voices(self) -> int:
+        """The most bands any line has: every line is drawn this tall."""
+        return max((len(line.bands) for line in self.lines), default=0)
+
+    def symbols(self) -> list[str]:
+        out: list[str] = []
+        for line in self.lines:
+            for band in line.bands:
+                if band.symbol not in out:
+                    out.append(band.symbol)
+        return out
+
+
+def check_symbol(symbol: str) -> str:
+    if len(symbol) != 1 or symbol in RESERVED_SYMBOLS:
+        reserved = " ".join(sorted(RESERVED_SYMBOLS - {" ", "\t"}))
+        raise GlyphError(f"a symbol is one character, not a space or any of {reserved}: {symbol!r}")
+    return symbol
+
+
+def parse_page(text: str, vocab: Vocabulary) -> Page:
+    """Read page source into a :class:`Page`."""
+    page, current = Page(), Line()
+    for number, raw in enumerate(text.splitlines(), 1):
+        line = raw.split("#", 1)[0].rstrip()
+        if not line.strip():
+            if current.bands:
+                page.lines.append(current)
+                current = Line()
+            continue
+        symbol, sep, rest = line.partition(":")
+        where = f"line {number}"
+        if not sep:
+            raise GlyphError(f'{where}: expected "SYMBOL: node | relation | node", got {raw.strip()!r}')
+        try:
+            check_symbol(symbol.strip())
+        except GlyphError as exc:
+            raise GlyphError(f"{where}: {exc}") from None
+        cells = rest.split("|")
+        if len(cells) != 3:
+            raise GlyphError(f"{where}: need exactly three slots separated by |, got {len(cells)}")
+        try:
+            words = tuple(vocab.parse(c) for c in cells)
+        except GlyphError as exc:
+            raise GlyphError(f"{where}: {exc}") from None
+        current.bands.append(Band(symbol.strip(), words))  # type: ignore[arg-type]
+    if current.bands:
+        page.lines.append(current)
+    return page
+
+
+def format_page(page: Page) -> str:
+    """Write a :class:`Page` back as page source."""
+    blocks = []
+    for line in page.lines:
+        blocks.append("\n".join(f"{b.symbol}: " + " | ".join(str(w) for w in b.words) for b in line.bands))
+    return "\n\n".join(blocks) + ("\n" if blocks else "")