weavly 0.1.0__tar.gz

weavly-0.1.0/LICENSE

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

weavly-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: weavly
+Version: 0.1.0
+Summary: Compiler for the Weavly dialog scripting language
+Author: Weavly contributors
+License-Expression: MIT
+Project-URL: Repository, https://github.com/weavly-lang/weavly-compiler
+Project-URL: Documentation, https://weavly-lang.github.io/weavly-docs/
+Project-URL: Issues, https://github.com/weavly-lang/weavly-compiler/issues
+Keywords: weavly,dialog,compiler,godot,interactive-fiction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark>=1.3.1
+Requires-Dist: typer>=0.21.0
+Dynamic: license-file
+
+# Weavly Compiler
+
+Compiler for the Weavly dialog scripting language. Parses `.wvl` files and compiles them to JSON for the Weavly Godot runtime.
+
+Language documentation: https://weavly-lang.github.io/weavly-docs/
+
+## Install
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then:
+
+```bash
+uv tool install weavly
+```
+
+uv installs a suitable Python if needed and puts `weavly` on your PATH (run `uv tool update-shell` if it isn't). Upgrade with `uv tool upgrade weavly`.
+
+With Python 3.11+ already installed, `pipx install weavly` works too.
+
+## Usage
+
+```bash
+weavly init my-project   # creates my-project/src/nodes.wvl
+cd my-project
+weavly build             # compiles src/**/*.wvl into build/
+weavly build --pretty    # same, with indented JSON
+weavly --version         # installed compiler version
+```
+
+`weavly init` without a name sets up `src/` in the current directory.
+
+The build writes:
+
+- `build/<path>.wvl.json` for each source file, containing its nodes
+- `build/env.json` with every `@env` declaration in the project
+
+Syntax errors, duplicate variable declarations, number declarations whose min, max or default don't fit together, duplicate node ids and `@goto` targets with no matching node fail the build with exit code 1. A failed build leaves the previous `build/` untouched.
+
+## Development
+
+```bash
+git clone https://github.com/weavly-lang/weavly-compiler.git
+cd weavly-compiler
+uv sync --group dev
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and release steps.
+
+## License
+
+[MIT](LICENSE)

weavly-0.1.0/README.md

@@ -0,0 +1,50 @@
+# Weavly Compiler
+
+Compiler for the Weavly dialog scripting language. Parses `.wvl` files and compiles them to JSON for the Weavly Godot runtime.
+
+Language documentation: https://weavly-lang.github.io/weavly-docs/
+
+## Install
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then:
+
+```bash
+uv tool install weavly
+```
+
+uv installs a suitable Python if needed and puts `weavly` on your PATH (run `uv tool update-shell` if it isn't). Upgrade with `uv tool upgrade weavly`.
+
+With Python 3.11+ already installed, `pipx install weavly` works too.
+
+## Usage
+
+```bash
+weavly init my-project   # creates my-project/src/nodes.wvl
+cd my-project
+weavly build             # compiles src/**/*.wvl into build/
+weavly build --pretty    # same, with indented JSON
+weavly --version         # installed compiler version
+```
+
+`weavly init` without a name sets up `src/` in the current directory.
+
+The build writes:
+
+- `build/<path>.wvl.json` for each source file, containing its nodes
+- `build/env.json` with every `@env` declaration in the project
+
+Syntax errors, duplicate variable declarations, number declarations whose min, max or default don't fit together, duplicate node ids and `@goto` targets with no matching node fail the build with exit code 1. A failed build leaves the previous `build/` untouched.
+
+## Development
+
+```bash
+git clone https://github.com/weavly-lang/weavly-compiler.git
+cd weavly-compiler
+uv sync --group dev
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and release steps.
+
+## License
+
+[MIT](LICENSE)

weavly-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "weavly"
+version = "0.1.0"
+description = "Compiler for the Weavly dialog scripting language"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Weavly contributors" }]
+requires-python = ">=3.11"
+dependencies = [
+    "lark>=1.3.1",
+    "typer>=0.21.0",
+]
+keywords = ["weavly", "dialog", "compiler", "godot", "interactive-fiction"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+    "Topic :: Software Development :: Compilers",
+]
+
+[project.urls]
+Repository = "https://github.com/weavly-lang/weavly-compiler"
+Documentation = "https://weavly-lang.github.io/weavly-docs/"
+Issues = "https://github.com/weavly-lang/weavly-compiler/issues"
+
+[project.scripts]
+weavly = "weavly.cli:app"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+weavly = ["resources/*.lark"]
+
+[dependency-groups]
+dev = [
+    "isort>=7.0.0",
+    "pytest>=8.0.0",
+    "ruff>=0.14.11",
+]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+known_first_party = ["weavly"]
+sections = ["FUTURE", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"]

weavly-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

weavly-0.1.0/src/weavly/__init__.py

@@ -0,0 +1 @@
+

weavly-0.1.0/src/weavly/cli.py

@@ -0,0 +1,82 @@
+from importlib.metadata import version as package_version
+from pathlib import Path
+
+import typer
+
+from .parsing import (
+    WVL_SOURCE_EXTENSION,
+    build_all_files,
+)
+from .reporting import report_error
+
+SOURCE_DIR = Path("src")
+BUILD_DIR = Path("build")
+
+NODE_INIT_STRING = (
+    "@env\n"
+    "name: string = \"World\"\n"
+    "@endenv\n"
+    "\n"
+    "@node first_node\n"
+    "Hello $name!\n"
+    "@endnode\n"
+)
+
+app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        typer.echo(f"weavly {package_version('weavly')}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_print_version,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+):
+    """Compiler for the Weavly dialog scripting language."""
+
+
+@app.command()
+def build(
+    pretty: bool = typer.Option(
+        False, "--pretty", help="Write indented, human-readable JSON."
+    ),
+):
+    """Compile src/**/*.wvl into build/."""
+    count = build_all_files(SOURCE_DIR, BUILD_DIR, pretty)
+    files = "file" if count == 1 else "files"
+    typer.echo(f"Built {count} {files} into {BUILD_DIR.as_posix()}/")
+
+
+@app.command()
+def init(
+    name: str = typer.Argument(
+        None, help="Directory to create. Defaults to the current directory."
+    ),
+):
+    """Create a new Weavly project with a starter src/nodes.wvl."""
+    if name:
+        base = Path(name)
+        if base.exists():
+            report_error(f"project '{name}' already exists")
+            raise typer.Exit(code=1)
+        base.mkdir()
+    else:
+        base = Path()
+
+    src: Path = base / "src"
+    if src.exists():
+        report_error(f"directory '{src.as_posix()}' already exists")
+        raise typer.Exit(code=1)
+    src.mkdir()
+    nodes_file = src / f"nodes{WVL_SOURCE_EXTENSION}"
+    nodes_file.write_text(NODE_INIT_STRING, encoding="utf-8")
+    typer.echo(f"Created {nodes_file.as_posix()}")

weavly-0.1.0/src/weavly/parsing/__init__.py

@@ -0,0 +1,7 @@
+from .parser import WVL_BUILD_EXTENSION, WVL_SOURCE_EXTENSION, build_all_files
+
+__all__ = [
+    "build_all_files",
+    "WVL_SOURCE_EXTENSION",
+    "WVL_BUILD_EXTENSION",
+]

weavly-0.1.0/src/weavly/parsing/parser.py

@@ -0,0 +1,254 @@
+import json
+import shutil
+from importlib import resources
+from pathlib import Path
+
+import typer
+from lark import Lark, Token, Transformer, Tree
+from lark.exceptions import UnexpectedInput, VisitError
+
+from ..reporting import report_error
+from .syntax_errors import describe_syntax_error, terminal_names
+from .wvl_transformer import InvalidStringError, WvlTransformer
+
+PARSER_TYPE = "lalr"
+ENCODING = "utf-8"
+SOURCE_ENCODING = "utf-8-sig"
+
+WVL_SOURCE_EXTENSION = ".wvl"
+WVL_BUILD_EXTENSION = ".wvl.json"
+WVL_GRAMMAR_FILE = "wvl-grammar.lark"
+ENV_BUILD_FILE = "env.json"
+
+_DECLARATION_RULES = frozenset(
+    {"number_declaration", "string_declaration", "flag_declaration"}
+)
+_NODE_RULES = frozenset({"node_start"})
+_GOTO_RULES = frozenset({"goto", "inline_goto"})
+
+Location = tuple[Path, int, int]
+
+
+def build_all_files(src_dir: Path, build_dir: Path, pretty: bool) -> int:
+    if not src_dir.is_dir():
+        report_error(
+            f"no '{src_dir.as_posix()}' directory found. Run 'weavly init' to create "
+            "a project or run the build from the project root."
+        )
+        raise typer.Exit(code=1)
+
+    grammar = _load_grammar(WVL_GRAMMAR_FILE)
+    parser = _build_parser(grammar, PARSER_TYPE)
+    names = terminal_names(parser)
+    transformer = WvlTransformer()
+
+    declarations: list[dict] = []
+    outputs: list[tuple[Path, dict]] = []
+    # name -> location of the first declaration seen with that name.
+    declared: dict[str, Location] = {}
+    node_ids: dict[str, Location] = {}
+    gotos: list[tuple[str, Location]] = []
+    validation_errors: list[tuple[Location, str]] = []
+    failed = False
+
+    for file in sorted(src_dir.rglob(f"*{WVL_SOURCE_EXTENSION}")):
+        if not file.is_file():
+            continue
+
+        relative_path = file.relative_to(src_dir)
+        out_file = relative_path.with_suffix(WVL_BUILD_EXTENSION)
+
+        try:
+            text = file.read_text(encoding=SOURCE_ENCODING)
+        except UnicodeDecodeError as e:
+            _report_encoding_error(e, file)
+            failed = True
+            continue
+
+        try:
+            tree = parser.parse(text)
+        except UnexpectedInput as e:
+            _report_parse_error(e, file, text, names)
+            failed = True
+            continue
+
+        try:
+            data = transformer.transform(tree)
+        except VisitError as e:
+            if not isinstance(e.orig_exc, InvalidStringError):
+                raise
+            _report_string_error(e.orig_exc, file)
+            failed = True
+            continue
+
+        # Source locations come from the raw tree; the transformed data has no
+        # line numbers.
+        _record_unique(
+            _id_locations(tree, _DECLARATION_RULES, file),
+            declared,
+            "variable",
+            validation_errors,
+        )
+        _record_unique(
+            _id_locations(tree, _NODE_RULES, file), node_ids, "node id", validation_errors
+        )
+        gotos.extend(_id_locations(tree, _GOTO_RULES, file))
+        validation_errors.extend(_number_range_errors(tree, file))
+        declarations.extend(data.get("declarations", []))
+
+        outputs.append((out_file, {"nodes": data["nodes"]}))
+
+    if failed:
+        raise typer.Exit(code=1)
+
+    validation_errors.extend(
+        (location, f"goto target '{target}' matches no node")
+        for target, location in gotos
+        if target not in node_ids
+    )
+    if validation_errors:
+        for (file, line, column), message in sorted(validation_errors):
+            report_error(message, file, line, column)
+        raise typer.Exit(code=1)
+
+    file_count = len(outputs)
+    outputs.append((Path(ENV_BUILD_FILE), {"declarations": declarations}))
+    _replace_build_dir(build_dir, outputs, pretty)
+    return file_count
+
+
+def _replace_build_dir(
+    build_dir: Path, outputs: list[tuple[Path, dict]], pretty: bool
+) -> None:
+    tmp_dir = build_dir.with_name(f".{build_dir.name}.tmp")
+    old_dir = build_dir.with_name(f".{build_dir.name}.old")
+    try:
+        for leftover in (tmp_dir, old_dir):
+            if leftover.exists():
+                shutil.rmtree(leftover)
+        for out_file, data in outputs:
+            _write_json(data, tmp_dir / out_file, pretty)
+        if build_dir.exists():
+            build_dir.rename(old_dir)
+        tmp_dir.rename(build_dir)
+    except OSError as e:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+        report_error(
+            f"could not update '{build_dir.as_posix()}': {e.strerror or e}. "
+            "Close any program using its files and build again."
+        )
+        raise typer.Exit(code=1)
+    shutil.rmtree(old_dir, ignore_errors=True)
+
+
+def _id_locations(
+    tree: Tree, rules: frozenset[str], file: Path
+) -> list[tuple[str, Location]]:
+    """Return (id, location) for the leading ID of every matching rule, in source order."""
+    locations = []
+    for subtree in tree.iter_subtrees_topdown():
+        if subtree.data in rules:
+            id_token = subtree.children[0]
+            locations.append((str(id_token), (file, id_token.line, id_token.column)))
+    return locations
+
+
+def _record_unique(
+    locations: list[tuple[str, Location]],
+    seen: dict[str, Location],
+    kind: str,
+    errors: list[tuple[Location, str]],
+) -> None:
+    for name, location in locations:
+        if name in seen:
+            prev_file, prev_line, _ = seen[name]
+            errors.append(
+                (
+                    location,
+                    f"duplicate {kind} '{name}', first declared at "
+                    f"{prev_file.as_posix()}:{prev_line}",
+                )
+            )
+        else:
+            seen[name] = location
+
+
+def _number_range_errors(tree: Tree, file: Path) -> list[tuple[Location, str]]:
+    errors = []
+    for declaration in tree.find_data("number_declaration"):
+        name_token, *numbers = declaration.children
+        minimum, maximum, value = (_number(child) for child in numbers)
+        location = (file, name_token.line, name_token.column)
+        name = str(name_token)
+
+        if minimum is not None and maximum is not None and minimum > maximum:
+            errors.append(
+                (location, f"number '{name}' has min {minimum:g} greater than max {maximum:g}")
+            )
+            continue
+
+        default = f"default {value:g}" if value is not None else "implicit default 0"
+        value = value or 0.0
+        if minimum is not None and value < minimum:
+            errors.append(
+                (location, f"number '{name}' has {default} below its min {minimum:g}")
+            )
+        elif maximum is not None and value > maximum:
+            errors.append(
+                (location, f"number '{name}' has {default} above its max {maximum:g}")
+            )
+    return errors
+
+
+def _number(child: Tree | Token | None) -> float | None:
+    if child is None:
+        return None
+    if isinstance(child, Tree):
+        return -float(child.children[0])
+    return float(child)
+
+
+def _write_json(data: dict, out_file: Path, pretty: bool) -> None:
+    out_file.parent.mkdir(parents=True, exist_ok=True)
+    if pretty:
+        out_file.write_text(json.dumps(data, indent=2), encoding=ENCODING)
+    else:
+        out_file.write_text(json.dumps(data, separators=(",", ":")), encoding=ENCODING)
+
+
+def _load_grammar(grammar_file: str) -> str:
+    grammar = (
+        resources.files("weavly.resources")
+        .joinpath(grammar_file)
+        .read_text(encoding=ENCODING)
+    )
+    return grammar
+
+
+def _build_parser(grammar: str, parser_type: str) -> Lark:
+    return Lark(grammar, parser=parser_type)
+
+
+def _parse(parser: Lark, text: str, transformer: Transformer) -> dict:
+    tree = parser.parse(text)
+    data = transformer.transform(tree)
+    return data
+
+
+def _report_encoding_error(error: UnicodeDecodeError, file: Path) -> None:
+    line = error.object[: error.start].count(b"\n") + 1
+    report_error("invalid encoding, files must be saved as UTF-8", file, line)
+
+
+def _report_string_error(error: InvalidStringError, file: Path) -> None:
+    token = error.token
+    report_error(
+        f"invalid string {token.value}: {error.reason}", file, token.line, token.column
+    )
+
+
+def _report_parse_error(
+    error: UnexpectedInput, file: Path, text: str, names: dict[str, str]
+) -> None:
+    message, details = describe_syntax_error(error, text, names)
+    report_error(message, file, error.line, error.column, details)