hoodscript 1.1.0__py3-none-any.whl

hoodscript/data/curriculum.md

@@ -0,0 +1,343 @@
+# HoodScript 10-Lesson Curriculum
+
+Each lesson is one runnable file. Type it in, run it with `hoodscript
+lessonN.hs`, then run `hoodscript -c lessonN.hs` to see the Python it becomes.
+That second step is the whole trick: you are learning Python with a handful
+of different words, and the words are the only thing that changes.
+
+Expected output is shown under each program. Every program here is executed
+by the test suite, so if yours differs, the crash report will point at the
+line.
+
+Keyword reference: [`keywords.md`](keywords.md). The words this curriculum
+teaches: `holla` `ask` `bet` `dip` `fam` `be` `skip` `chill` `tryna` `catch`
+`regardless` `throw` `finna` `done` `cap` and the `*Trip` exception names.
+Everything else is Python.
+
+---
+
+## Lesson 1 — Values and `holla`
+
+**Keywords:** `holla` `cap` `no cap`
+
+```hood
+name = "Khris"
+age = 30
+height = 1.8
+ready = no cap
+lying = cap
+nothing = None
+holla name, age, height, ready, lying, nothing
+holla type(age), int("42") + 1, str(3.5)
+```
+
+```
+Khris 30 1.8 True False None
+<class 'int'> 43 3.5
+```
+
+Variables don't need declaring. `holla` is `print` — with or without
+parentheses. `cap` is `False` (a lie); `no cap` is `True`. `type`, `int`,
+`str` and every other builtin keep their Python names.
+
+---
+
+## Lesson 2 — Decisions
+
+**Keywords:** `else if` `ain't` `ain't nobody` `it's`
+
+```hood
+score = 87
+if score >= 90:
+    holla "A"
+else if score >= 80:
+    holla "B"
+else:
+    holla "C or below"
+if ain't score < 50 and it's score:
+    holla "passing"
+name = ""
+if ain't nobody name:
+    holla "no name given"
+```
+
+```
+B
+passing
+no name given
+```
+
+`if`/`else` are Python's; `else if` is `elif`. `ain't` is `not`; `ain't
+nobody` is the emphatic guard form (also `not`). `it's x` means `x` exists —
+`(x is not None)` — so `it's 0` is true.
+
+---
+
+## Lesson 3 — Loops: `be` and `skip`
+
+**Keywords:** `be` `steady` `skip` and inclusive ranges `a..b`
+
+```hood
+be i in 1..3:
+    holla "lap", i
+n = 0
+steady:
+    n = n + 1
+    if n == 2:
+        skip
+    if n > 4:
+        break
+    holla "n is", n
+```
+
+```
+lap 1
+lap 2
+lap 3
+n is 1
+n is 3
+n is 4
+```
+
+`be x in xs` is `for x in xs` — habitual *be*, the thing that happens over
+and over. `1..3` is 1, 2, 3 — inclusive, unlike Python's `range`. `steady:`
+is `while True:` — keep going until `break`. `skip` is `continue`.
+
+---
+
+## Lesson 4 — Functions: `bet` and `dip`
+
+**Keywords:** `bet` `dip` `chill`
+
+```hood
+bet greet(who, greeting="wassup"):
+    dip greeting + ", " + who
+double = lambda x: x * 2
+holla(greet("fam"), greet("Khris", "yo"), double(21))
+bet countdown(n):
+    while n > 0:
+        yield n
+        n = n - 1
+holla(list(countdown(3)))
+bet nothing_yet():
+    chill
+holla(nothing_yet())
+```
+
+```
+wassup, fam yo, Khris 42
+[3, 2, 1]
+None
+```
+
+`bet` defines a function — a commitment. `dip` returns — you leave with the
+value. `chill` is `pass`. `lambda` and `yield` are Python's.
+
+---
+
+## Lesson 5 — Collections
+
+**Keywords:** `BIN`
+
+```hood
+nums = [3, 1, 2]
+holla(len(nums), sum(nums), sorted(nums))
+book = dict(a=1, b=2)
+be k, v in book.items():
+    holla(k, v)
+be i, x in enumerate(["x", "y"]):
+    holla(i, x)
+holla(list(zip([1, 2], ["a", "b"])), set([1, 1, 2]), tuple([1, 2]))
+holla([x for x in nums if x > 1], list(map(lambda x: x * 10, nums)))
+holla(all([no cap, True]), any([cap, True]))
+BIN LIMIT = 2
+holla nums[:LIMIT]
+```
+
+```
+3 6 [1, 2, 3]
+a 1
+b 2
+0 x
+1 y
+[(1, 'a'), (2, 'b')] {1, 2} (1, 2)
+[3, 2] [30, 10, 20]
+True True
+[3, 1]
+```
+
+Lists, dicts, sets, tuples, comprehensions, `len`, `sum`, `zip`, `map` —
+all Python, all unchanged. There was no cited word for any of them, so
+HoodScript doesn't pretend. `BIN X = v` is a constant (`X: Final = v`) —
+stressed *BIN*: true for a long time, and still is.
+
+---
+
+## Lesson 6 — Classes: `fam`
+
+**Keywords:** `fam`
+
+```hood
+fam Animal:
+    bet __init__(self, name):
+        self.name = name
+    bet speak(self):
+        dip self.name + " makes a sound"
+fam Dog(Animal):
+    bet speak(self):
+        dip super().speak() + " (woof)"
+d = Dog("Rex")
+holla(d.speak(), isinstance(d, Animal))
+```
+
+```
+Rex makes a sound (woof) True
+```
+
+`fam` is `class` — the close group an object belongs to. `self` and
+`super()` are Python's.
+
+---
+
+## Lesson 7 — Errors: `tryna`, `catch`, `regardless`, `throw`
+
+**Keywords:** `tryna` `catch` `regardless` `throw` · **Exceptions:** `ZeroSplitTrip` `BadValueTrip`
+
+```hood
+bet divide(a, b):
+    tryna:
+        dip a / b
+    catch ZeroSplitTrip:
+        holla("can't split by zero")
+        dip None
+    regardless:
+        holla("done dividing")
+holla(divide(6, 3))
+holla(divide(1, 0))
+bet check(x):
+    if x < 0:
+        throw BadValueTrip("x gotta be positive, got " + str(x))
+    dip x
+tryna:
+    check(-1)
+catch BadValueTrip as e:
+    holla("caught:", e)
+assert check(1) == 1
+```
+
+```
+done dividing
+2.0
+can't split by zero
+done dividing
+None
+caught: x gotta be positive, got -1
+```
+
+`tryna` is `try`. `catch`/`regardless`/`throw` are `except`/`finally`/`raise`
+— plain English kept deliberately. The `*Trip` names are Python's exception
+classes: `ZeroSplitTrip` *is* `ZeroDivisionError` (run `-c` and see). Any
+exception without a `*Trip` name is caught under its Python name.
+
+---
+
+## Lesson 8 — Modules and files
+
+**Keywords:** none
+
+```hood
+import json
+from pathlib import Path
+import math as m
+holla(json.dumps({"ok": True}), m.sqrt(16), Path("."))
+with open("out.txt", "w") as f:
+    f.write("written from HoodScript\n")
+holla(open("out.txt").read().strip())
+```
+
+```
+{"ok": true} 4.0 .
+written from HoodScript
+```
+
+The whole Python ecosystem is available, spelled the Python way. To import
+your own `.hs` files, see the onboarding guide §6–7.
+
+---
+
+## Lesson 9 — Async: `finna` and `done`
+
+**Keywords:** `finna` `done`
+
+```hood
+import asyncio
+finna bet fetch(n):
+    done asyncio.sleep(0)
+    dip n * 2
+finna bet main():
+    results = done asyncio.gather(fetch(1), fetch(2))
+    holla(results)
+asyncio.run(main())
+```
+
+```
+[2, 4]
+```
+
+`finna bet` is `async def` — *fixin' to*: prepared, not yet running, which
+is exactly what a coroutine object is. `done` is `await` — perfective: the
+thing, completed. Note that `fut.done()` — the *method* — is untouched;
+keywords are never rewritten after a dot.
+
+---
+
+## Lesson 10 — Pattern matching, scope, and the escape hatch
+
+**Keywords:** none
+
+```hood
+bet describe(cmd):
+    match cmd:
+        case ["go", direction]:
+            dip "going " + direction
+        case ["stop"]:
+            dip "stopping"
+        case _:
+            dip "unknown"
+holla(describe(["go", "north"]), describe(["stop"]), describe([]))
+total = 0
+bet bump():
+    global total
+    total = total + 1
+bump(); bump()
+holla(total)
+bet outer():
+    x = 1
+    bet inner():
+        nonlocal x
+        x = x + 1
+    inner()
+    dip x
+holla(outer())
+```
+
+```
+going north stopping unknown
+2
+2
+```
+
+`match`/`case`, `global`, `nonlocal` are Python's. And here is the escape
+hatch: **every Python keyword still works in HoodScript.** `def` and `return`
+are accepted alongside `bet` and `dip`. You can paste any Python file into a
+`.hs` file and it runs. The HoodScript words are preferred, not required.
+
+---
+
+## Graduation
+
+You now know every keyword in the language — fifteen words, eleven two-word
+forms, plus the exception names. Run `hoodscript -c` on any of these files one last time and
+read the Python: that is what you've been writing all along. From here, the
+[Python documentation](https://docs.python.org/3/) is the HoodScript
+documentation — substitute the words from [`keywords.md`](keywords.md).

hoodscript/debugger.py

@@ -0,0 +1,71 @@
+"""The HoodScript debugger shim.
+
+Integrates with debugpy (DAP) and Python debugging infrastructure.
+Because HoodScript transpilation preserves exact line numbers, debugpy
+and Python debuggers operate directly on .hs and .hood files once the
+import hook is installed and the entry point is transpiled.
+"""
+
+import sys
+from pathlib import Path
+
+from hoodscript import importer, traceback_handler
+from hoodscript.transpiler import transpile
+
+
+def run_debug(
+    filepath: str,
+    port: int = 5678,
+    host: str = "127.0.0.1",
+    wait_for_client: bool = False,
+    listen: bool = False,
+) -> int:
+    """Run a HoodScript program under debugpy or with debugging support."""
+    path = Path(filepath).resolve()
+    if not path.exists():
+        sys.stderr.write(f"File not found: {filepath}\n")
+        return 1
+
+    # Install import hook & traceback handler
+    importer.install()
+    traceback_handler.install()
+
+    # Put script directory on sys.path
+    file_dir = str(path.parent)
+    if file_dir not in sys.path:
+        sys.path.insert(0, file_dir)
+
+    # If debugpy listener is requested
+    if listen or wait_for_client:
+        try:
+            import debugpy
+
+            debugpy.listen((host, port))
+            sys.stderr.write(f"debugpy listening on {host}:{port}\n")
+            if wait_for_client:
+                sys.stderr.write("Waiting for debugger client to attach...\n")
+                debugpy.wait_for_client()
+        except ImportError:
+            sys.stderr.write("debugpy is not installed. Install with: pip install debugpy\n")
+            return 1
+
+    src = path.read_text(encoding="utf-8")
+    py_code = transpile(src, str(path))
+    code_obj = compile(py_code, str(path), "exec")
+
+    scope = {
+        "__file__": str(path),
+        "__name__": "__main__",
+        "__doc__": None,
+    }
+
+    try:
+        exec(code_obj, scope)
+        return 0
+    except SystemExit as e:                       # the program called exit(): honour it, don't report it
+        return int(e.code) if isinstance(e.code, int) else (0 if e.code is None else 1)
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:
+        traceback_handler.hood_excepthook(type(e), e, e.__traceback__)
+        return 1

hoodscript/errors/__init__.py

@@ -0,0 +1,12 @@
+"""The JPE (Just Plain English) error engine.
+
+    diagnose(exc_type, exc, tb) -> Diagnostic     # errors.translator
+    render(diagnostic, stream)                    # errors.renderer
+    CATALOG                                       # errors.catalog
+"""
+
+from hoodscript.errors.catalog import CATALOG, Entry, by_code, find
+from hoodscript.errors.renderer import render, render_plain
+from hoodscript.errors.translator import Diagnostic, diagnose
+
+__all__ = ["CATALOG", "Entry", "Diagnostic", "by_code", "diagnose", "find", "render", "render_plain"]