pbark 1.0.0__tar.gz

pbark-1.0.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: pbark
+Version: 1.0.0
+Summary: Python port of the jbark dog-themed story programming language
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# pbark
+
+Python port of [jbark](../src/main/java/dev/klomptech/jbark/), the dog-themed story programming language.
+
+**Semi-automated port:** pbark was translated from the Java source. It aims for parity with jbark and shares the same test suite. If behaviour diverges, jbark is canonical.
+
+## Release status
+
+**Already in this repo:** interpreter, 95 tests, CLI, registry files in `pbark/resources/`, `pip install .` works from a clone.
+
+**Still to do (you):** PyPI account → `twine upload` so others can `pip install pbark`. Full steps: [docs/RELEASE-PYTHON.md](../docs/RELEASE-PYTHON.md).
+
+When you edit breeds/objects in `src/main/resources/`, refresh the Python copy:
+
+```bash
+./scripts/sync-pbark-resources.sh   # from repo root
+```
+
+## Install
+
+Requires **Python 3.10+**.
+
+```bash
+cd pbark
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+## Run
+
+From the repo root (after install):
+
+```bash
+./pbark/bin/pbark examples/woof/goodboy.woof
+./pbark/bin/pbark --version
+./pbark/bin/pbark --list-breeds
+```
+
+Or with the module directly:
+
+```bash
+python3 -m pbark examples/woof/bimba.woof
+```
+
+Flags match jbark: `--help`, `--version`, `--strict`, `--quiet`, `--list-breeds`, `--list-objects`.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+The test suite is ported from jbark's JUnit tests. Golden output, parser shape, and feature coverage.
+
+## Docs
+
+- [docs/MANUAL.md](../docs/MANUAL.md) - grammar and runtime rules
+- [docs/AUTHOR.md](../docs/AUTHOR.md) - writing stories
+- [docs/RELEASE-PYTHON.md](../docs/RELEASE-PYTHON.md) - what's done vs what you still do for PyPI
+- [examples/](../examples/) - runnable `.woof` programs

pbark-1.0.0/README.md

@@ -0,0 +1,62 @@
+# pbark
+
+Python port of [jbark](../src/main/java/dev/klomptech/jbark/), the dog-themed story programming language.
+
+**Semi-automated port:** pbark was translated from the Java source. It aims for parity with jbark and shares the same test suite. If behaviour diverges, jbark is canonical.
+
+## Release status
+
+**Already in this repo:** interpreter, 95 tests, CLI, registry files in `pbark/resources/`, `pip install .` works from a clone.
+
+**Still to do (you):** PyPI account → `twine upload` so others can `pip install pbark`. Full steps: [docs/RELEASE-PYTHON.md](../docs/RELEASE-PYTHON.md).
+
+When you edit breeds/objects in `src/main/resources/`, refresh the Python copy:
+
+```bash
+./scripts/sync-pbark-resources.sh   # from repo root
+```
+
+## Install
+
+Requires **Python 3.10+**.
+
+```bash
+cd pbark
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+## Run
+
+From the repo root (after install):
+
+```bash
+./pbark/bin/pbark examples/woof/goodboy.woof
+./pbark/bin/pbark --version
+./pbark/bin/pbark --list-breeds
+```
+
+Or with the module directly:
+
+```bash
+python3 -m pbark examples/woof/bimba.woof
+```
+
+Flags match jbark: `--help`, `--version`, `--strict`, `--quiet`, `--list-breeds`, `--list-objects`.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+The test suite is ported from jbark's JUnit tests. Golden output, parser shape, and feature coverage.
+
+## Docs
+
+- [docs/MANUAL.md](../docs/MANUAL.md) - grammar and runtime rules
+- [docs/AUTHOR.md](../docs/AUTHOR.md) - writing stories
+- [docs/RELEASE-PYTHON.md](../docs/RELEASE-PYTHON.md) - what's done vs what you still do for PyPI
+- [examples/](../examples/) - runnable `.woof` programs

pbark-1.0.0/pbark/__init__.py

@@ -0,0 +1,3 @@
+"""pbark: Python port of the jbark dog-themed story programming language."""
+
+__version__ = "1.0.0"

pbark-1.0.0/pbark/__main__.py

@@ -0,0 +1,4 @@
+from pbark.bark import main
+
+if __name__ == "__main__":
+    main()

pbark-1.0.0/pbark/bark.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from pbark.cli import dog_art as DogArt
+from pbark.cli import version as Version
+from pbark.config.config_loader import ConfigLoader
+from pbark.errors import BarkError, ExitCode
+from pbark.interpreter.interpreter import Interpreter
+from pbark.lexer import Lexer
+from pbark.options import BarkOptions
+from pbark.parser.parser import Parser
+
+
+def print_help() -> None:
+    print(
+        """pbark: a dog-themed story programming language (Python port of jbark)
+
+Usage:
+  pbark [script.woof]          Run a .woof file
+  pbark                        Read lines from stdin (Ctrl+D to finish)
+  pbark --version              Show version and a dog fact
+  pbark --list-breeds          List registered breeds
+  pbark --list-objects         List registered objects
+  pbark --strict script.woof   Warn on story-only lines that do nothing
+  pbark --quiet script.woof    Suppress startup banner and goodbye
+
+Docs: docs/AUTHOR.md · docs/MANUAL.md
+"""
+    )
+
+
+def _list_names(label: str, names: list[str]) -> None:
+    print(f"{label}:")
+    for name in names:
+        print(f"  {name}")
+
+
+def _is_help_flag(arg: str) -> bool:
+    return arg in ("--help", "-h")
+
+
+def _is_version_flag(arg: str) -> bool:
+    return arg in ("--version", "-version")
+
+
+def run(source: str, options: BarkOptions | None = None) -> int:
+    options = options or BarkOptions.defaults()
+    try:
+        if not options.quiet:
+            DogArt.print_banner()
+        lexer = Lexer(source)
+        parser = Parser(lexer.tokenise(), options)
+        program = parser.parse()
+        Interpreter().run(program)
+        if not options.quiet:
+            DogArt.print_goodbye()
+        return ExitCode.OK
+    except BarkError as e:
+        print(e, file=sys.stderr)
+        return ExitCode.DATA_ERROR
+
+
+def main() -> None:
+    options = BarkOptions.defaults()
+    script_path: str | None = None
+    for arg in sys.argv[1:]:
+        if _is_help_flag(arg):
+            print_help()
+            sys.exit(ExitCode.OK)
+        if _is_version_flag(arg):
+            Version.print_version()
+            sys.exit(ExitCode.OK)
+        if arg == "--strict":
+            options = BarkOptions(True, options.quiet)
+            continue
+        if arg == "--quiet":
+            options = BarkOptions(options.strict, True)
+            continue
+        if arg == "--list-breeds":
+            _list_names("Breeds", ConfigLoader.list_breeds())
+            sys.exit(ExitCode.OK)
+        if arg == "--list-objects":
+            _list_names("Objects", ConfigLoader.list_objects())
+            sys.exit(ExitCode.OK)
+        if arg.startswith("-"):
+            print(f"Unknown flag: {arg}. Try pbark --help", file=sys.stderr)
+            sys.exit(ExitCode.USAGE)
+        if script_path is not None:
+            print("Usage: pbark [flags] [script.woof]. Try pbark --help", file=sys.stderr)
+            sys.exit(ExitCode.USAGE)
+        script_path = arg
+
+    try:
+        if script_path is not None:
+            source = Path(script_path).read_text(encoding="utf-8")
+        else:
+            print("> ", end="")
+            source = sys.stdin.read()
+    except OSError as e:
+        print(f"Couldn't dig up that file: {e}", file=sys.stderr)
+        sys.exit(ExitCode.INVALID_ARGUMENTS)
+
+    sys.exit(run(source, options))
+
+
+if __name__ == "__main__":
+    main()

pbark-1.0.0/pbark/cli/dog_art.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import random
+
+from pbark.config._resources import resources_dir
+
+EMOJI = "\U0001f415"
+PAW = "\U0001f43e"
+FACT_PREFIX = "Funny fact: "
+
+_EMOJIS = [EMOJI, "\U0001f436", "woof."]
+
+_BANNERS = [
+    """
+      ___    __
+    /(. .)\\    )
+     (*)_____/|
+     /        |
+    /    |--\\ |
+   (_)(_)   (_)
+""",
+    """
+    / \\__
+   (    @\\___
+   /         O
+  /   (_____/
+ /_____/   U
+    woof!
+""",
+    """
+                __
+   (\\,--------'()'--o
+    (_    ___    /~"
+     (_)_)  (_)_)
+""",
+]
+
+
+def _load_goodbyes() -> list[str]:
+    lines = [
+        "The dogs are now chilling on your bed.",
+        "After dragging the bed through the house, no more energy to play.",
+        "That was a good walk, time to relax.",
+        "The dogs had enough of playing, they went upstairs.",
+    ]
+    path = resources_dir() / "dogfacts.txt"
+    if path.is_file():
+        for line in path.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            if stripped:
+                lines.append(FACT_PREFIX + stripped)
+    return lines
+
+
+_GOODBYES = _load_goodbyes()
+
+
+def print_banner() -> None:
+    print(random.choice(_BANNERS))
+
+
+def random_bare_bark() -> str:
+    return random.choice(_EMOJIS)
+
+
+def print_goodbye() -> None:
+    print(random.choice(_GOODBYES))
+
+
+def paws_art() -> str:
+    return f"{PAW}   {PAW}   {PAW}"
+
+
+def print_paws() -> None:
+    print(paws_art())

pbark-1.0.0/pbark/cli/version.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import random
+
+from pbark.cli.dog_art import FACT_PREFIX
+from pbark.config._resources import resources_dir
+
+NAME = "pbark"
+NUMBER = "1.0.0"
+
+
+def _load_facts() -> list[str]:
+    path = resources_dir() / "dogfacts.txt"
+    if not path.is_file():
+        return []
+    return [line.strip() for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+_DOG_FACTS = _load_facts()
+
+
+def print_version() -> None:
+    print(f"{NAME} {NUMBER}")
+    fact = random_dog_fact()
+    if fact is not None:
+        print(FACT_PREFIX + fact)
+
+
+def random_dog_fact() -> str | None:
+    if not _DOG_FACTS:
+        return None
+    return random.choice(_DOG_FACTS)

pbark-1.0.0/pbark/config/_resources.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resources_dir() -> Path:
+    # Bundled copies ship inside the wheel (pip install pbark).
+    bundled = Path(__file__).resolve().parent.parent / "resources"
+    if (bundled / "breeds.txt").is_file():
+        return bundled
+    # Git clone dev layout: shared monorepo registry files.
+    return Path(__file__).resolve().parent.parent.parent.parent / "src" / "main" / "resources"

pbark-1.0.0/pbark/config/config_loader.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from pbark.config._resources import resources_dir
+from pbark.config.variable_type import VariableType
+from pbark.errors import BarkError
+from pbark.lexer import Token, TokenType
+
+
+class ConfigLoader:
+    MEMORY = "memory"
+    JOURNAL = "journal"
+
+    _INDEX: dict[str, VariableType] = {}
+    _PHRASE_ALIASES: dict[str, str] = {}
+    _loaded = False
+
+    @classmethod
+    def _ensure_loaded(cls) -> None:
+        if cls._loaded:
+            return
+        cls._load("/breeds.txt", VariableType.BREED)
+        cls._load("/objects.txt", VariableType.OBJECT)
+        cls._load("/stashes.txt", VariableType.STASH)
+        cls._load("/piles.txt", VariableType.PILE)
+        cls._INDEX[cls.MEMORY] = VariableType.STORY_NUMBER
+        cls._INDEX[cls.JOURNAL] = VariableType.STORY_TEXT
+        cls._build_phrase_aliases()
+        cls._loaded = True
+
+    @classmethod
+    def _load(cls, filename: str, vtype: VariableType) -> None:
+        path = resources_dir() / filename.lstrip("/")
+        if not path.is_file():
+            raise IllegalStateError(f"Resource not found: {filename}")
+        for line in path.read_text(encoding="utf-8").splitlines():
+            word = line.strip()
+            if word:
+                cls._INDEX[cls.normalise(word)] = vtype
+
+    @classmethod
+    def _build_phrase_aliases(cls) -> None:
+        for name in list(cls._INDEX.keys()):
+            cls._PHRASE_ALIASES[name] = name
+            if "_" in name:
+                cls._PHRASE_ALIASES[name.replace("_", " ")] = name
+
+    @staticmethod
+    def normalise(name: str) -> str:
+        return name.strip().lower()
+
+    @classmethod
+    def type_of(cls, name: str) -> VariableType | None:
+        cls._ensure_loaded()
+        return cls._INDEX.get(cls.normalise(name))
+
+    @classmethod
+    def is_valid_name(cls, name: str) -> bool:
+        return cls.type_of(name) is not None
+
+    @classmethod
+    def is_breed(cls, name: str) -> bool:
+        return cls.type_of(name) == VariableType.BREED
+
+    @classmethod
+    def is_stash(cls, name: str) -> bool:
+        return cls.type_of(name) == VariableType.STASH
+
+    @classmethod
+    def is_pile(cls, name: str) -> bool:
+        return cls.type_of(name) == VariableType.PILE
+
+    @classmethod
+    def is_story_number_constant(cls, name: str) -> bool:
+        return cls.type_of(name) == VariableType.STORY_NUMBER
+
+    @classmethod
+    def is_story_text_constant(cls, name: str) -> bool:
+        return cls.type_of(name) == VariableType.STORY_TEXT
+
+    @classmethod
+    def is_story_constant(cls, name: str) -> bool:
+        return cls.is_story_number_constant(name)
+
+    @classmethod
+    def memory_name(cls) -> str:
+        return cls.MEMORY
+
+    @classmethod
+    def journal_name(cls) -> str:
+        return cls.JOURNAL
+
+    @classmethod
+    def token_index_after_resolved_name(
+        cls, tokens: list[Token], fr: int, to: int, resolved_name: str
+    ) -> int:
+        cls._ensure_loaded()
+        words: list[str] = []
+        positions: list[int] = []
+        for i in range(fr, to):
+            token = tokens[i]
+            if token.is_(TokenType.IDENTIFIER):
+                words.append(cls.normalise(token.value))
+                positions.append(i)
+        for length in range(min(4, len(words)), 0, -1):
+            for start in range(len(words) - length + 1):
+                phrase = " ".join(words[start : start + length])
+                if resolved_name == cls.resolve_name_phrase(phrase):
+                    return positions[start + length - 1] + 1
+        key = cls.normalise(resolved_name)
+        for i in range(fr, to):
+            token = tokens[i]
+            if token.is_(TokenType.IDENTIFIER) and key == cls.normalise(token.value):
+                return i + 1
+        return -1
+
+    @classmethod
+    def list_names(cls, vtype: VariableType) -> list[str]:
+        cls._ensure_loaded()
+        return sorted(k for k, v in cls._INDEX.items() if v == vtype)
+
+    @classmethod
+    def list_breeds(cls) -> list[str]:
+        return cls.list_names(VariableType.BREED)
+
+    @classmethod
+    def list_objects(cls) -> list[str]:
+        return cls.list_names(VariableType.OBJECT)
+
+    @classmethod
+    def list_stashes(cls) -> list[str]:
+        return cls.list_names(VariableType.STASH)
+
+    @classmethod
+    def list_piles(cls) -> list[str]:
+        return cls.list_names(VariableType.PILE)
+
+    @classmethod
+    def resolve_name_phrase(cls, phrase: str) -> str | None:
+        cls._ensure_loaded()
+        return cls._PHRASE_ALIASES.get(cls.normalise(phrase))
+
+    @classmethod
+    def resolve_name_from_tokens(cls, tokens: list[Token], fr: int, to: int) -> str | None:
+        cls._ensure_loaded()
+        words = cls._identifier_words(tokens, fr, to)
+        cls._skip_leading_story_noise(words)
+        return cls._match_longest_name_phrase(words)
+
+    @classmethod
+    def resolve_collection_from_tokens(
+        cls, tokens: list[Token], fr: int, to: int
+    ) -> str | None:
+        cls._ensure_loaded()
+        words = cls._identifier_words(tokens, fr, to)
+        cls._skip_leading_story_noise(words)
+        best = None
+        best_length = 0
+        for length in range(min(4, len(words)), 0, -1):
+            for start in range(len(words) - length + 1):
+                phrase = " ".join(words[start : start + length])
+                resolved = cls.resolve_name_phrase(phrase)
+                if (
+                    resolved is not None
+                    and (cls.is_stash(resolved) or cls.is_pile(resolved))
+                    and length >= best_length
+                ):
+                    best = resolved
+                    best_length = length
+        return best
+
+    @classmethod
+    def _skip_leading_story_noise(cls, words: list[str]) -> None:
+        while words:
+            if cls.is_valid_name(words[0]) or cls.resolve_name_phrase(words[0]) is not None:
+                break
+            name_ahead = False
+            for length in range(1, min(4, len(words)) + 1):
+                if cls.resolve_name_phrase(" ".join(words[:length])) is not None:
+                    name_ahead = True
+                    break
+            if name_ahead:
+                break
+            words.pop(0)
+
+    @staticmethod
+    def _identifier_words(tokens: list[Token], fr: int, to: int) -> list[str]:
+        words: list[str] = []
+        for i in range(fr, to):
+            token = tokens[i]
+            if token.is_(TokenType.IDENTIFIER):
+                words.append(ConfigLoader.normalise(token.value))
+        return words
+
+    @classmethod
+    def _match_longest_name_phrase(cls, words: list[str]) -> str | None:
+        for length in range(min(4, len(words)), 0, -1):
+            for start in range(len(words) - length + 1):
+                phrase = " ".join(words[start : start + length])
+                resolved = cls.resolve_name_phrase(phrase)
+                if resolved is not None:
+                    return resolved
+        return None
+
+    @classmethod
+    def require_stash(cls, name: str, line: int) -> None:
+        if not cls.is_stash(name):
+            from pbark.config.name_hints import NameHints
+
+            raise BarkError(
+                line,
+                f"'{name}' is not a not something the dogs can get stuff from or bury in."
+                + NameHints.hint_phrase(name, cls.list_stashes()),
+            )
+
+    @classmethod
+    def require_pile(cls, name: str, line: int) -> None:
+        if not cls.is_pile(name):
+            from pbark.config.name_hints import NameHints
+
+            raise BarkError(
+                line,
+                f"'{name}' is not a registered pile. wrong spot."
+                + NameHints.hint_phrase(name, cls.list_piles()),
+            )
+
+    @classmethod
+    def require_breed(cls, name: str, line: int) -> None:
+        if not cls.is_breed(name):
+            from pbark.config.name_hints import NameHints
+
+            raise BarkError(
+                line,
+                f'"{name}" isn\'t a breed we know about. Garbage bin mix??'
+                + NameHints.hint_phrase(name, cls.list_breeds()),
+            )
+
+
+class IllegalStateError(RuntimeError):
+    pass