glyph-cli 0.2.0__py3-none-any.whl

glyph_cli/script.py

@@ -0,0 +1,272 @@
+"""The script itself: parts, words and the vocabulary that names them.
+
+A *part* is a 3x3 shape with a meaning. A *word* is two lattice positions,
+a **kind** on the left and a **which** on the right, written ``KIND.WHICH``.
+Either half may be empty (``_``). Numbers are ``COUNT.<n>`` (0 to 511): COUNT is the
+only kind whose which is read as nine bits, and it never takes a part as its which,
+so a number can never be drawn like a word. ``COUNT`` alone is zero.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+
+#: A half of a word: a part name, a number (only after ``ONE``) or ``None`` for empty.
+Half = str | int | None
+
+MAX_NUMBER = 511
+EMPTY = "_"
+NUMBER = "COUNT"  # the kind whose which is a number
+
+
+class GlyphError(Exception):
+    """A problem the user can fix: a bad word, a bad page, a bad vocabulary."""
+
+
+@dataclass(frozen=True)
+class Part:
+    name: str
+    shape: tuple[str, str, str]
+    thing: str
+    relation: str | None = None
+
+
+@dataclass(frozen=True)
+class Word:
+    """One word: ``kind`` and ``which``. ``Word(None, None)`` is the empty word."""
+
+    kind: str | None = None
+    which: Half = None
+
+    @property
+    def is_empty(self) -> bool:
+        return self.kind is None and self.which is None
+
+    @property
+    def is_number(self) -> bool:
+        return isinstance(self.which, int)
+
+    @property
+    def halves(self) -> tuple[Half, Half]:
+        return (self.kind, self.which)
+
+    def __str__(self) -> str:
+        if self.is_empty:
+            return EMPTY
+        which = "" if self.which is None else f".{self.which}"
+        return (self.kind or EMPTY) + which
+
+
+@dataclass
+class Entry:
+    """A vocabulary entry: a word with an agreed meaning."""
+
+    word: Word
+    gloss: str
+    domain: str = "Unsorted"
+    note: str = ""
+
+    def to_json(self) -> dict:
+        return {
+            "kind": self.word.kind,
+            "which": self.word.which,
+            "gloss": self.gloss,
+            "domain": self.domain,
+            "note": self.note,
+        }
+
+
+@dataclass
+class Vocabulary:
+    parts: dict[str, Part]
+    markers: dict[str, str]
+    entries: list[Entry] = field(default_factory=list)
+    version: int = 1
+    path: Path | None = None
+
+    # ---- loading and saving ----
+
+    @classmethod
+    def from_json(cls, data: dict, path: Path | None = None) -> Vocabulary:
+        try:
+            parts = {
+                name: Part(name, tuple(p["shape"]), p["thing"], p.get("relation")) for name, p in data["parts"].items()
+            }
+            entries = [
+                Entry(Word(e["kind"], e["which"]), e["gloss"], e.get("domain", "Unsorted"), e.get("note", ""))
+                for e in data["words"]
+            ]
+            return cls(parts, dict(data.get("markers", {})), entries, data.get("version", 1), path)
+        except (KeyError, TypeError) as exc:
+            raise GlyphError(f"not a glyph vocabulary file: missing {exc}") from exc
+
+    @classmethod
+    def load(cls, path: str | os.PathLike | None = None) -> Vocabulary:
+        """Load a vocabulary file, or the bundled one when ``path`` is ``None``."""
+        if path is None:
+            text = resources.files("glyph_cli").joinpath("data/vocab.json").read_text(encoding="utf-8")
+            return cls.from_json(json.loads(text))
+        p = Path(path)
+        try:
+            data = json.loads(p.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            raise GlyphError(f"vocabulary file not found: {p}") from None
+        except json.JSONDecodeError as exc:
+            raise GlyphError(f"{p} is not valid JSON: {exc}") from None
+        return cls.from_json(data, p)
+
+    def to_json(self) -> dict:
+        return {
+            "version": self.version,
+            "parts": {
+                p.name: {"shape": list(p.shape), "thing": p.thing, "relation": p.relation} for p in self.parts.values()
+            },
+            "markers": self.markers,
+            "words": [e.to_json() for e in self.entries],
+        }
+
+    def save(self, path: str | os.PathLike | None = None) -> Path:
+        target = Path(path) if path is not None else self.path
+        if target is None:
+            raise GlyphError(
+                "the bundled vocabulary is read-only; run `glyph init` to make an editable copy, "
+                "then point to it with --vocab or GLYPH_VOCAB"
+            )
+        tmp = target.with_name(target.name + ".tmp")
+        tmp.write_text(json.dumps(self.to_json(), indent=1, ensure_ascii=False) + "\n", encoding="utf-8")
+        os.replace(tmp, target)
+        self.path = target
+        return target
+
+    # ---- words ----
+
+    def parse(self, text: str) -> Word:
+        """``'BODY.OTHER'`` -> ``Word('BODY', 'OTHER')``; ``'COUNT.137'`` -> ``Word('COUNT', 137)``."""
+        s = text.strip()
+        if s in ("", EMPTY):
+            return Word()
+        k, _, w = s.partition(".")
+        kind = None if k in ("", EMPTY) else k.upper()
+        which: Half
+        if w in ("", EMPTY):
+            which = None
+        elif w.isdigit():
+            which = int(w)
+            if which > MAX_NUMBER:
+                raise GlyphError(f"number out of range 0-{MAX_NUMBER}: {which}")
+            if kind not in (NUMBER, None):
+                raise GlyphError(f"a number needs {NUMBER} as its kind, e.g. {NUMBER}.{which} (got {s})")
+            if kind == NUMBER and which == 0:
+                which = None  # COUNT alone is zero: COUNT.0 draws exactly like it
+        else:
+            which = w.upper()
+            if kind == NUMBER:
+                raise GlyphError(f"{NUMBER} only takes a number as its which, e.g. {NUMBER}.12 (got {s})")
+        for half in (kind, which):
+            if isinstance(half, str) and half not in self.parts:
+                raise GlyphError(f"unknown part: {half} (see `glyph parts`)")
+        return Word(kind, which)
+
+    def lookup(self, word: Word) -> Entry | None:
+        for e in self.entries:
+            if e.word == word:
+                return e
+        return None
+
+    def thing(self, half: Half) -> str:
+        """The meaning of one half on its own."""
+        if half is None:
+            return EMPTY
+        if isinstance(half, int):
+            return str(half)
+        return self.parts[half].thing
+
+    def gloss(self, word: Word, role: str = "node") -> str:
+        """The best human reading of a word as a ``node`` or as a ``relation``."""
+        if word.is_empty:
+            return "—"
+        if role == "relation":
+            base = ""
+            if word.kind:
+                part = self.parts[word.kind]
+                base = part.relation or part.thing
+            if word.which is None:
+                return base
+            marker = self.markers.get(str(word.which), str(word.which))
+            return f"{base} [{marker}]"
+        if word.kind == NUMBER and (word.is_number or word.which is None):
+            return str(word.which or 0)
+        entry = self.lookup(word)
+        if entry:
+            return entry.gloss
+        if word.which is None:
+            return self.parts[word.kind].thing  # type: ignore[index]
+        return f"{self.thing(word.kind)} | {self.thing(word.which)} (not in vocabulary)"
+
+    # ---- editing ----
+
+    def add(self, word: Word, gloss: str, domain: str = "Unsorted", note: str = "", force: bool = False) -> Entry:
+        if word.kind is None or word.is_number or word.kind == NUMBER:
+            raise GlyphError(f"a vocabulary word needs a kind; numbers ({NUMBER}.n) are built in")
+        existing = self.lookup(word)
+        if existing:
+            raise GlyphError(f'already in the vocabulary: {word} = "{existing.gloss}"')
+        same = [e for e in self.entries if e.gloss.lower() == gloss.lower()]
+        if same and not force:
+            raise GlyphError(f'the meaning "{gloss}" is already used by {same[0].word}; use --force to add anyway')
+        entry = Entry(word, gloss, domain, note)
+        self.entries.append(entry)
+        return entry
+
+    def remove(self, word: Word) -> Entry:
+        entry = self.lookup(word)
+        if not entry:
+            raise GlyphError(f"not in the vocabulary: {word}")
+        self.entries.remove(entry)
+        return entry
+
+    def search(self, text: str) -> tuple[list[Entry], list[Part]]:
+        t = text.lower()
+        words = [e for e in self.entries if t in e.gloss.lower() or t in e.note.lower()]
+        parts = [p for p in self.parts.values() if t in p.thing.lower() or (p.relation and t in p.relation.lower())]
+        return words, parts
+
+    def validate(self) -> list[str]:
+        """Return a list of problems; an empty list means the vocabulary is sound."""
+        errors: list[str] = []
+        shapes: dict[tuple[str, ...], str] = {}
+        for p in self.parts.values():
+            if len(p.shape) != 3 or any(len(r) != 3 or set(r) - set("#.") for r in p.shape):
+                errors.append(f'part {p.name}: shape must be 3 rows of 3 "#"/"."')
+            if p.shape in shapes:
+                errors.append(f"parts {shapes[p.shape]} and {p.name} have the same shape")
+            shapes[p.shape] = p.name
+            if not any("#" in r for r in p.shape):
+                errors.append(f"part {p.name}: shape is empty")
+        seen: dict[Word, str] = {}
+        glosses: dict[str, Word] = {}
+        for e in self.entries:
+            for half in e.word.halves:
+                if isinstance(half, str) and half not in self.parts:
+                    errors.append(f"{e.word}: unknown part {half}")
+            if e.word.kind == NUMBER:
+                errors.append(f"{e.word}: {NUMBER} words are numbers and are built in")
+            if e.word in seen:
+                errors.append(f'{e.word} defined twice ("{seen[e.word]}" and "{e.gloss}")')
+            seen[e.word] = e.gloss
+            g = e.gloss.lower()
+            if g in glosses:
+                errors.append(f'meaning "{e.gloss}" used by {glosses[g]} and {e.word}')
+            glosses[g] = e.word
+        return errors
+
+    def domains(self) -> list[str]:
+        out: list[str] = []
+        for e in self.entries:
+            if e.domain not in out:
+                out.append(e.domain)
+        return out

glyph_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: glyph-cli
+Version: 0.2.0
+Summary: The dictionary and toolkit for the grid script of Ross 128 b (InterImm, The Contact Era).
+Project-URL: Homepage, https://github.com/InterImm/glyph-cli
+Project-URL: Documentation, https://interimm.github.io/glyph-cli/
+Project-URL: Source, https://github.com/InterImm/glyph-cli
+Project-URL: Issues, https://github.com/InterImm/glyph-cli/issues
+Author: InterImm
+License-Expression: MIT
+License-File: LICENSE
+Keywords: conlang,interimm,knowledge graph,science fiction,writing system
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Other Audience
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# glyph
+
+The dictionary and toolkit for the **grid script**: how humans write down what Ross 128 b sends, in InterImm's *The Contact Era*.
+
+**Docs:** https://interimm.github.io/glyph-cli/
+
+```sh
+uvx --from glyph-cli glyph show BODY.OTHER STAR.TIME COUNT.137
+```
+
+```text
++++.+++   .+..+.+   .....+.
++++.+..   +++.+.+   ......+
++++.+++   .+..+.+   +++...+
+  BODY.OTHER: your world
+  STAR.TIME: pulsar
+  COUNT.137: 137
+```
+
+## Install
+
+```sh
+uv tool install glyph-cli    # or: pipx install glyph-cli, or: pip install glyph-cli
+```
+
+Python 3.10 or newer, no other dependencies.
+
+## Use
+
+```sh
+glyph parts                         # the 16 parts
+glyph find wind                     # search meanings
+glyph check BODY.STAR               # is it a word? exit 1 if not
+glyph show BODY.OTHER --symbol ×    # draw words
+glyph render examples/third-voice.txt         # draw a page
+glyph render examples/third-voice.txt --svg -o page.svg
+glyph graph examples/conversation.txt         # read it as a knowledge graph (--json, --dot)
+glyph render examples/question.txt | glyph decode -   # and back
+glyph init my-vocab.json && export GLYPH_VOCAB=$PWD/my-vocab.json
+glyph add BODY.STAR "a star-world" --domain Worlds
+```
+
+A page file has one band per line, `SYMBOL: node | relation | node`; a blank line starts the next statement. See [`examples/`](https://github.com/InterImm/glyph-cli/tree/main/examples) and the [docs](https://interimm.github.io/glyph-cli/pages/).
+
+## Develop
+
+```sh
+uv sync --all-groups          # or: pip install -e . pytest ruff zensical
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run python scripts/gen_docs.py    # regenerate docs/vocabulary.md, docs/cli.md and the example drawings
+uv run zensical serve                # docs at http://localhost:8000
+```
+
+The vocabulary ships in [`src/glyph_cli/data/vocab.json`](https://github.com/InterImm/glyph-cli/blob/main/src/glyph_cli/data/vocab.json). Change it with the tool (`glyph --vocab src/glyph_cli/data/vocab.json add ...`), then run `scripts/gen_docs.py`; the tests fail if the generated docs are stale.
+
+Pushes to `main` publish the docs to GitHub Pages.
+
+## Release
+
+1. Bump `__version__` in `src/glyph_cli/__init__.py` and merge it to `main`.
+2. Publish a GitHub release tagged `vX.Y.Z` (the same version).
+
+The release workflow checks the tag matches the version, builds the package, tests the built wheel and uploads it to [PyPI](https://pypi.org/project/glyph-cli/) with Trusted Publishing, so no token is stored.
+
+## License
+
+MIT

glyph_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+glyph_cli/__init__.py,sha256=yDgWZPf2YOoAtryLnfNOtWPynJ9JwGdWREHnGS7xAXU,241
+glyph_cli/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+glyph_cli/cli.py,sha256=JVMrbzyR8bDj1ALwbzeRyQJcwh8bjLVhxM9pc4dhhko,9863
+glyph_cli/drawing.py,sha256=1sIUJyoOaAKavU2kirHXierxubdJZAamK9wQ952mrUU,7936
+glyph_cli/export.py,sha256=_UFvvBUqX4kzHWVC5tpjd_R_xl2yuYPYiRGV5XC9oMI,1163
+glyph_cli/graph.py,sha256=NQVWCWh7f4tMM2HDEDHs3atiNqflWMaSis-YFuEo7jw,4809
+glyph_cli/page.py,sha256=4j7TRPeSYxvWLaIdb-VzO7PCtrjYGD-AGySWyJXACDU,3679
+glyph_cli/script.py,sha256=3HbGqX7kdbPmkFwPEl6sSoN6qbkeRsR89p-LOg2MdzE,10252
+glyph_cli/data/vocab.json,sha256=-s-zYZwVd6qHx78NUmKp9XeH2ksULE9dNu-hXEmwKDQ,8764
+glyph_cli-0.2.0.dist-info/METADATA,sha256=6NGqwzfgYnS999LflMye3SModtyDSJH2qp0m_akyreM,3664
+glyph_cli-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+glyph_cli-0.2.0.dist-info/entry_points.txt,sha256=CmNHQcMaQCjYbHPNpq0Qo5fY_sv_e-QBtirLrQzfdW8,45
+glyph_cli-0.2.0.dist-info/licenses/LICENSE,sha256=BNbLWEVBqHWUAMGfNbrk-ZHxjbF5NbsszdU3IYiFZko,1065
+glyph_cli-0.2.0.dist-info/RECORD,,

glyph_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

glyph_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+glyph = glyph_cli.cli:main

glyph_cli-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InterImm
+
+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.