hassl 0.2.0__tar.gz

hassl-0.2.0/LICENSE

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

hassl-0.2.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: hassl
+Version: 0.2.0
+Summary: HASSL: Home Assistant Simple Scripting Language
+Home-page: https://github.com/adanowitz/hassl
+Author: adanowitz
+Author-email: adanowitz@gmail.com
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark-parser
+Requires-Dist: jinja2
+Requires-Dist: pyyaml
+Dynamic: license-file
+
+# HASSL
+
+> **Home Assistant Simple Scripting Language**
+
+HASSL is a human-friendly domain-specific language (DSL) for building **loop-safe**, **deterministic**, and **composable** automations for [Home Assistant](https://www.home-assistant.io/).
+
+It compiles lightweight `.hassl` scripts into fully functional YAML packages that plug directly into Home Assistant, replacing complex automations with a clean, readable syntax.
+
+---
+
+## 🚀 Features
+
+- **Readable DSL** → write logic like natural language (`if motion && lux < 50 then light = on`)
+- **Sync devices** → keep switches, dimmers, and fans perfectly in sync
+- **Schedules** → declare time-based gates (`enable from 08:00 until 19:00`)
+- **Loop-safe** → context ID tracking prevents feedback loops
+- **Per-rule enable gates** → `disable rule` or `enable rule` dynamically
+- **Inline waits** → `wait (!motion for 10m)` works like native HA triggers
+- **Color temperature in Kelvin** → `light.kelvin = 2700`
+- **Auto-reload resilience** → schedules re-evaluate automatically on HA restart
+
+---
+
+## 🧰 Example
+
+```hassl
+alias light  = light.wesley_lamp
+alias motion = binary_sensor.wesley_motion_motion
+alias lux    = sensor.wesley_motion_illuminance
+
+schedule wake_hours:
+  enable from 08:00 until 19:00;
+
+rule wesley_motion_light:
+  schedule use wake_hours;
+  if (motion && lux < 50)
+  then light = on;
+  wait (!motion for 10m) light = off
+
+rule landing_manual_off:
+  if (light == off) not_by any_hassl
+  then disable rule wesley_motion_light for 3m
+```
+
+Produces a complete Home Assistant package with:
+
+- Helpers (`input_boolean`, `input_text`, `input_number`)
+- Context-aware writer scripts
+- Sync automations for linked devices
+- Rule-based automations with schedules and `not_by` guards
+
+---
+
+## 🏗 Installation
+
+```bash
+git clone https://github.com/adanowitz/hassl.git
+cd hassl
+pip install -e .
+```
+
+Verify:
+
+```bash
+hasslc --help
+```
+
+---
+
+## ⚙️ Usage
+
+1. Create a `.hassl` script (e.g., `living_room.hassl`).
+2. Compile it into a Home Assistant package:
+   ```bash
+   hasslc living_room.hassl -o ./packages/living_room/
+   ```
+3. Copy the package into `/config/packages/` and reload automations.
+
+Each `.hassl` file compiles into an isolated package — no naming collisions, no shared helpers.
+
+---
+
+## 📦 Output Files
+
+| File                       | Description                                   |
+| -------------------------- | --------------------------------------------- |
+| `helpers_<pkg>.yaml`       | Defines all helpers (booleans, text, numbers) |
+| `scripts_<pkg>.yaml`       | Writer scripts with context stamping          |
+| `sync_<pkg>_*.yaml`        | Sync automations for each property            |
+| `rules_bundled_<pkg>.yaml` | Rule logic automations + schedules            |
+
+---
+
+## 🧠 Concepts
+
+| Concept      | Description                                                     |
+| ------------ | --------------------------------------------------------------- |
+| **Alias**    | Maps short names to HA entities (`alias light = light.kitchen`) |
+| **Sync**     | Keeps multiple devices aligned across on/off, brightness, etc.  |
+| **Rule**     | Defines reactive logic with guards, waits, and control flow.    |
+| **Schedule** | Defines active time windows, reusable across rules.             |
+| **Tag**      | Lightweight metadata stored in `input_text` helpers.            |
+
+---
+
+## 🔒 Loop Safety & Context Tracking
+
+HASSL automatically writes the **parent context ID** into helper entities before performing actions.\
+This ensures `not_by any_hassl` and `not_by rule("name")` guards work flawlessly, preventing infinite feedback.
+
+---
+
+## 🕒 Schedules That Survive Restarts
+
+All schedules are restart-safe:
+
+- `input_boolean.hassl_schedule_<name>` automatically re-evaluates on startup.
+- Triggers are set for both start and end times.
+- Missed events (like mid-day restarts) are recovered automatically.
+
+---
+
+## 📚 Documentation
+
+For full grammar and detailed semantics, see the [HASSL Language Specification](./HASSL_Specification.md).
+
+For a hands-on guide, check out the [Quickstart](./quickstart.md).
+
+---
+
+## 🧩 Contributing
+
+Contributions, tests, and ideas welcome!\
+To run tests locally:
+
+```bash
+pytest tests/
+```
+
+Please open pull requests for grammar improvements, new device domains, or scheduling logic.
+
+---
+
+## 📄 License
+
+MIT License © 2025\
+Created and maintained by [@adanowitz](https://github.com/adanowitz)
+
+---
+
+**HASSL** — simple, reliable, human-readable automations for Home Assistant.
+

hassl-0.2.0/README.md

@@ -0,0 +1,152 @@
+# HASSL
+
+> **Home Assistant Simple Scripting Language**
+
+HASSL is a human-friendly domain-specific language (DSL) for building **loop-safe**, **deterministic**, and **composable** automations for [Home Assistant](https://www.home-assistant.io/).
+
+It compiles lightweight `.hassl` scripts into fully functional YAML packages that plug directly into Home Assistant, replacing complex automations with a clean, readable syntax.
+
+---
+
+## 🚀 Features
+
+- **Readable DSL** → write logic like natural language (`if motion && lux < 50 then light = on`)
+- **Sync devices** → keep switches, dimmers, and fans perfectly in sync
+- **Schedules** → declare time-based gates (`enable from 08:00 until 19:00`)
+- **Loop-safe** → context ID tracking prevents feedback loops
+- **Per-rule enable gates** → `disable rule` or `enable rule` dynamically
+- **Inline waits** → `wait (!motion for 10m)` works like native HA triggers
+- **Color temperature in Kelvin** → `light.kelvin = 2700`
+- **Auto-reload resilience** → schedules re-evaluate automatically on HA restart
+
+---
+
+## 🧰 Example
+
+```hassl
+alias light  = light.wesley_lamp
+alias motion = binary_sensor.wesley_motion_motion
+alias lux    = sensor.wesley_motion_illuminance
+
+schedule wake_hours:
+  enable from 08:00 until 19:00;
+
+rule wesley_motion_light:
+  schedule use wake_hours;
+  if (motion && lux < 50)
+  then light = on;
+  wait (!motion for 10m) light = off
+
+rule landing_manual_off:
+  if (light == off) not_by any_hassl
+  then disable rule wesley_motion_light for 3m
+```
+
+Produces a complete Home Assistant package with:
+
+- Helpers (`input_boolean`, `input_text`, `input_number`)
+- Context-aware writer scripts
+- Sync automations for linked devices
+- Rule-based automations with schedules and `not_by` guards
+
+---
+
+## 🏗 Installation
+
+```bash
+git clone https://github.com/adanowitz/hassl.git
+cd hassl
+pip install -e .
+```
+
+Verify:
+
+```bash
+hasslc --help
+```
+
+---
+
+## ⚙️ Usage
+
+1. Create a `.hassl` script (e.g., `living_room.hassl`).
+2. Compile it into a Home Assistant package:
+   ```bash
+   hasslc living_room.hassl -o ./packages/living_room/
+   ```
+3. Copy the package into `/config/packages/` and reload automations.
+
+Each `.hassl` file compiles into an isolated package — no naming collisions, no shared helpers.
+
+---
+
+## 📦 Output Files
+
+| File                       | Description                                   |
+| -------------------------- | --------------------------------------------- |
+| `helpers_<pkg>.yaml`       | Defines all helpers (booleans, text, numbers) |
+| `scripts_<pkg>.yaml`       | Writer scripts with context stamping          |
+| `sync_<pkg>_*.yaml`        | Sync automations for each property            |
+| `rules_bundled_<pkg>.yaml` | Rule logic automations + schedules            |
+
+---
+
+## 🧠 Concepts
+
+| Concept      | Description                                                     |
+| ------------ | --------------------------------------------------------------- |
+| **Alias**    | Maps short names to HA entities (`alias light = light.kitchen`) |
+| **Sync**     | Keeps multiple devices aligned across on/off, brightness, etc.  |
+| **Rule**     | Defines reactive logic with guards, waits, and control flow.    |
+| **Schedule** | Defines active time windows, reusable across rules.             |
+| **Tag**      | Lightweight metadata stored in `input_text` helpers.            |
+
+---
+
+## 🔒 Loop Safety & Context Tracking
+
+HASSL automatically writes the **parent context ID** into helper entities before performing actions.\
+This ensures `not_by any_hassl` and `not_by rule("name")` guards work flawlessly, preventing infinite feedback.
+
+---
+
+## 🕒 Schedules That Survive Restarts
+
+All schedules are restart-safe:
+
+- `input_boolean.hassl_schedule_<name>` automatically re-evaluates on startup.
+- Triggers are set for both start and end times.
+- Missed events (like mid-day restarts) are recovered automatically.
+
+---
+
+## 📚 Documentation
+
+For full grammar and detailed semantics, see the [HASSL Language Specification](./HASSL_Specification.md).
+
+For a hands-on guide, check out the [Quickstart](./quickstart.md).
+
+---
+
+## 🧩 Contributing
+
+Contributions, tests, and ideas welcome!\
+To run tests locally:
+
+```bash
+pytest tests/
+```
+
+Please open pull requests for grammar improvements, new device domains, or scheduling logic.
+
+---
+
+## 📄 License
+
+MIT License © 2025\
+Created and maintained by [@adanowitz](https://github.com/adanowitz)
+
+---
+
+**HASSL** — simple, reliable, human-readable automations for Home Assistant.
+

hassl-0.2.0/hassl/ast/nodes.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass, asdict, field
+from typing import List, Any, Dict
+
+@dataclass
+class Alias:
+    name: str
+    entity: str
+
+@dataclass
+class Sync:
+    kind: str
+    members: List[str]
+    name: str
+    invert: List[str] = field(default_factory=list)
+
+@dataclass
+class IfClause:
+    condition: Dict[str, Any]
+    actions: List[Dict[str, Any]]
+
+@dataclass
+class Rule:
+    name: str
+    clauses: List[IfClause]
+
+@dataclass
+class Program:
+    statements: List[object]
+    def to_dict(self):
+        def enc(x):
+            if isinstance(x, (Alias, Sync, Rule, IfClause)):
+                d = asdict(x); d["type"] = x.__class__.__name__; return d
+            return x
+        return {"type": "Program","statements": [enc(s) for s in self.statements]}

hassl-0.2.0/hassl/cli.py

@@ -0,0 +1,42 @@
+import argparse
+import os, json
+from .parser.transform import HasslTransformer
+from .ast.nodes import Program
+from lark import Lark
+from .semantics.analyzer import analyze
+from .codegen.package import emit_package
+from .codegen import generate as codegen_generate
+
+GRAMMAR_PATH = os.path.join(os.path.dirname(__file__), "parser", "hassl.lark")
+
+def parse_hassl(text: str) -> Program:
+    with open(GRAMMAR_PATH) as f:
+        grammar = f.read()
+    parser = Lark(grammar, start="start", parser="lalr", maybe_placeholders=False)
+    tree = parser.parse(text)
+    program = HasslTransformer().transform(tree)
+    return program
+
+def main():
+    ap = argparse.ArgumentParser(prog="hasslc", description="HASSL Compiler")
+    ap.add_argument("input", help="Input .hassl file")
+    ap.add_argument("-o", "--out", default="./packages/out", help="Output directory for HA package")
+    args = ap.parse_args()
+
+    with open(args.input) as f:
+        src = f.read()
+
+    program = parse_hassl(src)
+    print("[hasslc] AST:", program.to_dict())
+    ir = analyze(program)
+    print("[hasslc] IR:", ir.to_dict())
+
+    ir_dict = ir.to_dict() if hasattr(ir, "to_dict") else ir
+    codegen_generate(ir_dict, args.out)
+    print(f"[hasslc] Package written to {args.out}")
+
+    os.makedirs(args.out, exist_ok=True)
+    emit_package(ir, args.out)
+    with open(os.path.join(args.out, "DEBUG_ir.json"), "w") as dbg:
+        dbg.write(json.dumps(ir.to_dict(), indent=2))
+    print(f"[hasslc] Package written to {args.out}")

hassl-0.2.0/hassl/codegen/__init__.py

@@ -0,0 +1,22 @@
+from pathlib import Path
+from .package import emit_package
+from .rules_min import generate_rules
+
+def generate(ir_obj, outdir):
+    """
+    Orchestrate codegen in a merge-safe order:
+      1) emit_package: writes/merges helpers, scripts, and sync automations
+      2) generate_rules: writes rules automations & merges gate booleans into helpers.yaml
++    """
+    Path(outdir).mkdir(parents=True, exist_ok=True)
+
+    # 1) Sync & helpers first (merge-safe via yaml_emit._dump_yaml)
+    try:
+        emit_package(ir_obj if hasattr(ir_obj, "syncs") else ir_obj, outdir)
+    except Exception:
+        # keep going to still emit rules even if sync pass fails
+        pass
+
+    # 2) Rules last (adds gate booleans; also merge-safe)
+    generate_rules(ir_obj if isinstance(ir_obj, dict) else getattr(ir_obj, "to_dict", lambda: ir_obj)(), outdir)
+    return True