typescratch 1.0.0__py3-none-any.whl

typescratch/__init__.py

@@ -0,0 +1,146 @@
+"""TypeScratch - a small programming language that compiles to Scratch 3 (.sb3) files.
+
+Library usage:
+
+    import typescratch
+
+    # Compile a .tysh file to a .sb3 next to it
+    typescratch.file("C:/Users/pc/Desktop/thing.tysh")
+
+    # Or specify the output path explicitly
+    typescratch.file("thing.tysh", out="thing.sb3")
+
+    # Compile from a source string
+    src = '''
+    s "Sprite1"
+    when gf clicked {
+      say(Hello, World!)(2)
+    }
+    '''
+    sb3_bytes = typescratch.source(src)         # returns bytes
+    typescratch.source(src, out="out.sb3")      # writes to file
+
+    # Lower-level: compile and return (project_json, assets_dict)
+    project, assets = typescratch.compile_source(src)
+
+CLI usage:
+
+    typescratch build thing.tysh                 # writes thing.sb3
+    typescratch build thing.tysh --out out.sb3
+    typescratch build thing.tysh --debug         # verbose AST/block dump
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional, Tuple, Dict, Any
+
+from .errors import CompileError, Debug
+from .lexer import tokenize
+from .parser import Parser
+from .codegen import Codegen
+from .sb3 import write_sb3, write_sb3_bytes
+
+
+__version__ = "1.0.0"
+
+
+def compile_source(src: str, filename: str = "<tysh>", debug: bool = False,
+                   asset_root: Optional[str] = None
+                   ) -> Tuple[dict, Dict[str, bytes]]:
+    """Compile a TypeScratch source string to (project_json, assets_dict).
+
+    `asset_root` is the base directory for resolving relative `img=` paths.
+    If None, defaults to the directory of `filename` (or cwd).
+    """
+    dbg = Debug(enabled=debug)
+    dbg.section("Tokens")
+    toks = tokenize(src, filename)
+    for t in toks:
+        dbg.line(f"{t.line:>4}:{t.col:<3} {t.type:<14} {t.value!r}")
+
+    dbg.section("AST")
+    program = Parser(toks, filename).parse_program()
+    dbg.line(repr(program))
+    for tgt in program.targets:
+        dbg.line(f"  target {tgt.kind} {tgt.name!r} scripts={len(tgt.scripts)} "
+                 f"custom={len(tgt.custom_blocks)} costumes={len(tgt.costumes)}")
+        for s in tgt.scripts:
+            dbg.line(f"    hat={s.hat.kind} body={len(s.body)} stmts")
+
+    if asset_root is None:
+        if filename and filename != "<tysh>":
+            asset_root = os.path.dirname(os.path.abspath(filename))
+        else:
+            asset_root = os.getcwd()
+
+    cg = Codegen(program, debug=dbg, asset_root=asset_root)
+    project, assets = cg.generate()
+    return project, assets
+
+
+def source(src: str, out: Optional[str] = None, debug: bool = False,
+           filename: str = "<tysh>") -> bytes:
+    """Compile a TypeScratch source string and return the .sb3 bytes.
+
+    If `out` is given, also write to that file path.
+    """
+    project, assets = compile_source(src, filename=filename, debug=debug)
+    sb3_bytes = write_sb3_bytes(project, assets)
+    if out:
+        with open(out, "wb") as f:
+            f.write(sb3_bytes)
+    return sb3_bytes
+
+
+def file(path: str, out: Optional[str] = None, debug: bool = False) -> str:
+    """Compile a .tysh file to a .sb3 file.
+
+    Returns the output file path.
+    """
+    if not os.path.isfile(path):
+        raise FileNotFoundError(f"TypeScratch source file not found: {path}")
+    with open(path, "r", encoding="utf-8") as f:
+        src = f.read()
+    if out is None:
+        # default: same name, .sb3 extension, next to input
+        base, _ = os.path.splitext(path)
+        out = base + ".sb3"
+    source(src, out=out, debug=debug, filename=path)
+    return out
+
+
+# Friendly alias - `typescratch.compile("out.sb3")` after `typescratch.file("in.tysh")`
+# Actually the user wanted `typescratch.file(...)` then `typescratch.compile(...)`.
+# Let me support both styles:
+
+def compile(out_path: str, src_path: Optional[str] = None, debug: bool = False) -> str:
+    """Compile a .tysh source to a specific .sb3 output path.
+
+    If `src_path` is None, looks for a .tysh file with the same basename
+    as `out_path` (e.g. for `out.sb3`, looks for `out.tysh` in the same dir).
+    """
+    if src_path is None:
+        base, _ = os.path.splitext(out_path)
+        for ext in (".tysh", ".ts", ".tsh"):
+            candidate = base + ext
+            if os.path.isfile(candidate):
+                src_path = candidate
+                break
+        if src_path is None:
+            raise FileNotFoundError(
+                f"no source file found for output {out_path!r} "
+                f"(looked for {base}.tysh)"
+            )
+    return file(src_path, out=out_path, debug=debug)
+
+
+__all__ = [
+    "file",
+    "source",
+    "compile",
+    "compile_source",
+    "CompileError",
+    "__version__",
+]

typescratch/__main__.py

@@ -0,0 +1,10 @@
+"""Allow running TypeScratch as `python -m typescratch build ...`.
+
+This file is executed when you run `python -m typescratch` — it delegates
+to the CLI's main function.
+"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

typescratch/assets.py

@@ -0,0 +1,69 @@
+"""Default Scratch assets used when a sprite/backdrop has no image.
+
+We embed the OFFICIAL Scratch Cat costume SVG (costume1 from the
+default Scratch 3.0 project) - extracted from an actual .sb3 file -
+so that any project we generate looks correct in the Scratch editor.
+
+A blank white backdrop SVG is also provided.
+"""
+
+import os
+
+# Path to the official Scratch Cat SVG (sitting alongside this module)
+_CAT_SVG_PATH = os.path.join(os.path.dirname(__file__), "scratchcat_official.svg")
+
+
+def _load_official_cat() -> bytes:
+    """Load the official Scratch Cat SVG from disk."""
+    try:
+        with open(_CAT_SVG_PATH, "rb") as f:
+            return f.read()
+    except FileNotFoundError:
+        # Fallback to a placeholder if the SVG file is missing (e.g. if
+        # the package was installed without the data file)
+        return PLACEHOLDER_CAT_SVG.encode("utf-8")
+
+
+# Official Scratch Cat - the real deal, loaded from scratchcat_official.svg
+# Rotation center: (48, 50) - matches Scratch's default.
+SCRATCH_CAT_SVG = _load_official_cat().decode("utf-8", errors="replace")
+
+
+# A simple blank white backdrop, the size of a default Scratch stage.
+BLANK_BACKDROP_SVG = """<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="360" viewBox="0 0 480 360">
+  <rect width="480" height="360" fill="#ffffff"/>
+</svg>
+"""
+
+# A neutral grey costume used as a last-resort fallback if the official
+# SVG file is missing from the install.
+PLACEHOLDER_CAT_SVG = """<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96">
+  <rect width="96" height="96" fill="#cccccc"/>
+  <text x="48" y="50" text-anchor="middle" font-family="sans-serif" font-size="14">cat</text>
+</svg>
+"""
+
+# A short silent WAV used when a sound is referenced but no file exists.
+SILENT_WAV = (
+    b"RIFF\x24\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00"
+    b"\x44\xac\x00\x00\x88\x58\x01\x00\x02\x00\x10\x00data\x00\x00\x00\x00"
+)
+
+
+def default_sprite_costume():
+    """Return (name, svg_bytes, md5ext, rotation_center_x, rotation_center_y)
+    for the official Scratch Cat."""
+    data = SCRATCH_CAT_SVG.encode("utf-8")
+    return ("costume1", data, "scratchcat.svg", 48, 50)
+
+
+def default_backdrop():
+    """Return (name, svg_bytes, md5ext, rotation_center_x, rotation_center_y)
+    for a blank white backdrop."""
+    return ("backdrop1", BLANK_BACKDROP_SVG.encode("utf-8"), "backdrop1.svg", 240, 180)
+
+
+def placeholder_costume(name="costume1"):
+    return (name, PLACEHOLDER_CAT_SVG.encode("utf-8"), "placeholder.svg", 30, 30)

typescratch/ast_nodes.py

@@ -0,0 +1,363 @@
+"""AST node definitions for TypeScratch.
+
+The grammar (informally):
+
+    program       := (extension | target)*
+
+    extension     := 'extension' EXT_NAME
+    target        := sprite | backdrop
+    sprite        := 's' STRING [sprite_attrs]
+    backdrop      := 'b' STRING [backdrop_attrs]
+    sprite_attrs  := ('xy=' NUM ',' NUM | 'dir=' NUM | 'size=' NUM
+                      | 'visible=' BOOL | 'rot=' ROT | 'img=' PATH | 'costume=' NAME)*
+    backdrop_attrs:= ('img=' PATH | 'costume=' NAME)*
+
+    script        := hat '{' statement* '}'
+    hat           := 'when' hat_kind hat_args?
+
+    statement     := block_call
+                   | var_assign
+                   | var_modify
+                   | list_op
+                   | 'if' expr block ('else' block)?
+                   | 'repeat' expr block
+                   | 'repeatUntil' expr block
+                   | 'forever' block
+                   | 'while' expr block
+                   | 'wait' expr
+                   | 'stop' STOP_ARG
+                   | 'def' NAME '(' params ')' block        # custom block definition
+                   | custom_call
+
+    block_call    := NAME ('.' NAME)? '(' args? ')' post?  # e.g. say(...)(2), pen.Down, goto(1,2)
+                   | NAME '.' NAME                          # argument-less form: pen.Down, nextCostume
+                   | NAME                                    # argument-less: show, hide
+
+    var_assign    := NAME '=' expr
+    var_modify    := NAME ('+=' | '-=' | '*=' | '/=') expr
+
+    list_op       := NAME '.' ('add' | 'delete' | 'insert' | 'replace') '(' args ')'
+
+    expr          := or_expr
+    or_expr       := and_expr (('or') and_expr)*
+    and_expr      := not_expr ('and' not_expr)*
+    not_expr      := 'not' not_expr | compare
+    compare       := add (('>' | '<' | '=') add)?
+    add           := mul (('+' | '-') mul)*
+    mul           := unary (('*' | '/' | 'mod') unary)*
+    unary         := '-' unary | atom
+    atom          := NUM | STRING | NAME | '(' expr ')' | func_call | builtin
+    func_call     := NAME '(' args? ')'
+
+Strings in the .tysh source can be written *without* quotes (because
+"Scratch has no strings, only text").  Where a string vs an identifier
+is ambiguous (e.g. arguments to `say`), the lexer yields a single TEXT
+token whose interpretation is context-sensitive in the parser.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Any, Dict
+
+
+# ---------------------------------------------------------------------------
+# Top-level
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Program:
+    extensions: List[str] = field(default_factory=list)
+    targets: List["Target"] = field(default_factory=list)
+
+    def __repr__(self):
+        return f"Program(ext={self.extensions}, targets={len(self.targets)})"
+
+
+@dataclass
+class Target:
+    kind: str                     # 'sprite' or 'stage'
+    name: str
+    x: float = 0.0
+    y: float = 0.0
+    direction: float = 90.0
+    size: float = 100.0
+    visible: bool = True
+    rotation_style: str = "all around"  # all around | left-right | don't rotate
+    img: Optional[str] = None
+    costumes: List[Dict[str, Any]] = field(default_factory=list)  # {name, path, is_default}
+    sounds: List[Dict[str, Any]] = field(default_factory=list)
+    scripts: List["Script"] = field(default_factory=list)
+    custom_blocks: List["CustomBlockDef"] = field(default_factory=list)
+
+
+@dataclass
+class Script:
+    hat: "Hat"
+    body: List["Statement"] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Hats
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Hat:
+    kind: str            # gf | spr | key | backdrop | receive | greater_than | clicked_clone | broadcast
+    args: List[Any] = field(default_factory=list)
+    line: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Statements
+# ---------------------------------------------------------------------------
+
+class Statement:
+    line: int = 0
+
+
+@dataclass
+class BlockCall(Statement):
+    """A built-in block call: e.g. say(...) , goto(x,y), pen.Down.
+
+    `namespace` is None for global blocks (say, goto, move, ...).
+    `method`  is the block name.
+    `args`    is the list of expressions / atoms inside the parens.
+    `post`    is the optional trailing paren group, e.g. the seconds in
+              `say(Hello, World!)(2)`.
+    """
+    namespace: Optional[str]
+    method: str
+    args: List[Any]
+    post: Optional[List[Any]] = None
+    line: int = 0
+
+
+@dataclass
+class VarAssign(Statement):
+    name: str
+    value: Any
+    line: int = 0
+
+
+@dataclass
+class VarModify(Statement):
+    name: str
+    op: str          # '+=' | '-=' | '*=' | '/='
+    value: Any
+    line: int = 0
+
+
+@dataclass
+class ListOp(Statement):
+    list_name: str
+    op: str          # 'add' | 'delete' | 'insert' | 'replace' | 'show' | 'hide'
+    args: List[Any]
+    line: int = 0
+
+
+@dataclass
+class IfStatement(Statement):
+    cond: Any
+    then_body: List[Statement]
+    else_body: Optional[List[Statement]] = None
+    line: int = 0
+
+
+@dataclass
+class RepeatStatement(Statement):
+    times: Any
+    body: List[Statement]
+    line: int = 0
+
+
+@dataclass
+class RepeatUntilStatement(Statement):
+    cond: Any
+    body: List[Statement]
+    line: int = 0
+
+
+@dataclass
+class WaitUntilStatement(Statement):
+    """`waitUntil (cond)` - control_wait_until."""
+    cond: Any
+    line: int = 0
+
+
+@dataclass
+class ForeverStatement(Statement):
+    body: List[Statement]
+    line: int = 0
+
+
+@dataclass
+class WhileStatement(Statement):
+    """Syntactic sugar: `while (c) { ... }` -> `repeatUntil(not c) { ... }`."""
+    cond: Any
+    body: List[Statement]
+    line: int = 0
+
+
+@dataclass
+class ForEachStatement(Statement):
+    """`forEach (var) in (number) { ... }` - hidden control_for_each block.
+
+    Iterates `var` from 1 to `count`, running the body once per value.
+    `var_name` is the variable to use as the loop counter.
+    """
+    var_name: str
+    count: Any
+    body: List[Statement]
+    line: int = 0
+
+
+@dataclass
+class AllAtOnceStatement(Statement):
+    """`allAtOnce { ... }` - hidden control_all_at_once block.
+
+    Runs the body without yielding to the screen refresh between blocks
+    (similar to a warp-mode custom block).
+    """
+    body: List[Statement]
+    line: int = 0
+
+
+@dataclass
+class WaitStatement(Statement):
+    secs: Any
+    line: int = 0
+
+
+@dataclass
+class StopStatement(Statement):
+    kind: str       # 'all' | 'this script' | 'other scripts in sprite' | 'other scripts in stage'
+    line: int = 0
+
+
+@dataclass
+class BroadcastStatement(Statement):
+    msg: Any
+    wait: bool = False
+    line: int = 0
+
+
+@dataclass
+class CustomBlockDef(Statement):
+    """`def MyBlock(name, age) { ... }` - defines a custom block."""
+    name: str
+    params: List[Dict[str, str]]   # [{name, type}] type in {string|bool|number}
+    body: List[Statement]
+    warp: bool = False             # run without screen refresh
+    line: int = 0
+
+
+@dataclass
+class CustomBlockCall(Statement):
+    """A call to a user-defined custom block."""
+    name: str
+    args: List[Any]
+    line: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Expressions
+# ---------------------------------------------------------------------------
+
+@dataclass
+class NumberLit:
+    value: float
+    line: int = 0
+
+
+@dataclass
+class StringLit:
+    value: str
+    line: int = 0
+
+
+@dataclass
+class ColorLit:
+    value: str    # like "#ff0000"
+    line: int = 0
+
+
+@dataclass
+class VarRef:
+    name: str
+    line: int = 0
+
+
+@dataclass
+class ListRef:
+    name: str
+    index: Any
+    line: int = 0
+
+
+@dataclass
+class BinOp:
+    op: str          # '+','-','*','/','mod','>','<','=','and','or'
+    left: Any
+    right: Any
+    line: int = 0
+
+
+@dataclass
+class UnaryOp:
+    op: str          # 'not' or '-'
+    operand: Any
+    line: int = 0
+
+
+@dataclass
+class FuncCall:
+    """Operator-like reporter: pickRandom(1,10), join(a,b), abs(x), ..."""
+    name: str
+    args: List[Any]
+    line: int = 0
+
+
+@dataclass
+class BuiltinRef:
+    """Direct references to Scratch reporters that have no arguments:
+    answer, mouseX, mouseY, timer, loudness, daysSince2000, username,
+    x, y, direction, size, costumeName, backdropName, volume, etc.
+    """
+    name: str
+    line: int = 0
+
+
+@dataclass
+class BareRef:
+    """A bare identifier used in expression context.
+
+    Resolved at codegen time:
+      * if the name matches a declared variable in the current target -> VarRef
+      * if the name matches a builtin reporter (e.g. "answer", "mouseX") -> BuiltinRef
+      * if the name matches a current custom-block parameter -> ArgumentRef
+      * otherwise -> StringLit (literal text)
+    """
+    name: str
+    line: int = 0
+
+
+@dataclass
+class ArgumentRef:
+    """Reference to a custom block parameter (an argument_reporter block)."""
+    name: str
+    arg_id: str = ""  # filled in by codegen
+    line: int = 0
+
+
+@dataclass
+class ListReporterRef:
+    """A list reporter reference like `inventory.item(1)`, `inventory.length`,
+    `inventory.contains(thing)`, `inventory.itemNum(thing)`, `inventory.contents`.
+
+    Resolved at codegen time into the appropriate data_* block.
+    """
+    list_name: str
+    method: str     # 'item' | 'length' | 'contains' | 'itemNum' | 'contents'
+    args: List[Any]
+    line: int = 0