hassl 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

hassl/__init__.py

@@ -1 +1 @@
-__version__ = "0.3.1"
+__version__ = "0.4.0"

hassl/ast/nodes.py

@@ -58,6 +58,20 @@ class Schedule:
     windows: List[ScheduleWindow] = field(default_factory=list)
     private: bool = False
 
+@dataclass
+class TemplateDecl:
+    kind: str            # "rule" | "sync" | "schedule"
+    name: str
+    params: list = field(default_factory=list) # [{"name": "light", "default": ...}, ...]
+    body: Any = None  # Rule | Sync | Schedule body shape
+    private: bool = False
+
+@dataclass
+class UseTemplate:
+    name: str            # template name being referenced
+    args: list = field(default_factory=list)  # ["pos1", {"name":"kw","value":...}, ...] 
+    as_name: Optional[str] = None
+    
 @dataclass
 class Rule:
     name: str
@@ -75,7 +89,8 @@ class Program:
     def to_dict(self):
         def enc(x):
             if isinstance(x, (Alias, Sync, Rule, IfClause, Schedule,
-                              HolidaySet, ScheduleWindow, PeriodSelector)):
+                              HolidaySet, ScheduleWindow, PeriodSelector,
+                              TemplateDecl, UseTemplate)):
                 d = asdict(x); d["type"] = x.__class__.__name__; return d
             return x
         return {

hassl/cli.py

@@ -4,7 +4,7 @@ from pathlib import Path
 from typing import Dict, Tuple, List
 from .parser.loader import load_grammar_text
 from .parser.transform import HasslTransformer
-from .ast.nodes import Program, Alias, Schedule
+from .ast.nodes import Program, Alias, Schedule, TemplateDecl
 from lark import Lark
 from .semantics import analyzer as sem_analyzer
 from .semantics.analyzer import analyze
@@ -85,6 +85,12 @@ def _collect_public_exports(prog: Program, pkg: str) -> Dict[Tuple[str,str,str],
             name = s.get("name")
             if isinstance(name, str) and name.strip():
                 out[(pkg, "schedule", name)] = Schedule(name=name, clauses=s.get("clauses", []) or [], private=False)
+
+        # Templates (public only)
+    for s in prog.statements:
+        if isinstance(s, TemplateDecl) and not getattr(s, "private", False):
+            out[(pkg, "template", s.name)] = s
+            
     return out
 
 def _scan_hassl_files(path: Path) -> List[Path]:
@@ -97,40 +103,62 @@ def _module_to_path(module_root: Path, module: str) -> Path:
 
 def _ensure_imports_loaded(programs, module_root: Path):
     """If imported packages aren't parsed yet, try to load their .hassl files from module_root."""
-    # programs: List[tuple[Path, Program, str]]
+    # Track both package names (from parsed files) and module ids (from import statements)
     known_pkgs = {pkg for _, _, pkg in programs}
+    seen_modules: set[str] = set()  # abs_mod we've already attempted/loaded
+    seen_paths: set[Path] = set(p for p, _, _ in programs)
+
     added = True
     while added:
         added = False
-        for _, prog, importer_pkg in list(programs):
+        # iterate over a snapshot; we'll append to programs
+        for importer_path, prog, importer_pkg in list(programs):
             for imp in getattr(prog, "imports", []) or []:
                 if not isinstance(imp, dict) or imp.get("type") != "import":
                     continue
+
                 raw_mod = imp.get("module", "")
-                if not raw_mod:
+                if not raw_mod or not module_root:
                     continue
-                # resolve relative notation against the importing package
+
                 abs_mod = _normalize_module(importer_pkg, raw_mod)
-                if abs_mod in known_pkgs:
+
+                # guard: avoid re-trying the same module or self-import
+                if abs_mod in seen_modules or abs_mod == importer_pkg:
                     continue
-                if not module_root:
+
+                # If we already have a program whose package == abs_mod, skip
+                if abs_mod in known_pkgs:
+                    seen_modules.add(abs_mod)
                     continue
+
                 candidate = _module_to_path(module_root, abs_mod)
-                if candidate.exists():
-                    print(f"[hasslc] Autoload candidate FOUND for '{abs_mod}': {candidate}")
-                    with open(candidate, "r", encoding="utf-8") as f:
-                        text = f.read()
-                    p = parse_hassl(text)
-                    # force package to declared or derived (declared will win)
-                    # If the file declared a package, keep it. Otherwise, assign the resolved module id.
-                    pkg_name = p.package or abs_mod
-                    p.package = pkg_name
-                    programs.append((candidate, p, pkg_name))
-                    known_pkgs.add(pkg_name)
-                    added = True
-                else:
+                if not candidate.exists():
                     print(f"[hasslc] Autoload candidate MISS for '{abs_mod}': {candidate}")
+                    seen_modules.add(abs_mod)  # mark as tried to avoid spamming
+                    continue
+
+                if candidate in seen_paths:
+                    # We’ve already parsed this exact file; mark its module and move on
+                    print(f"[hasslc] Autoload candidate SKIP (already loaded) for '{abs_mod}': {candidate}")
+                    seen_modules.add(abs_mod)
+                    continue
 
+                print(f"[hasslc] Autoload candidate FOUND for '{abs_mod}': {candidate}")
+                with open(candidate, "r", encoding="utf-8") as f:
+                    text = f.read()
+
+                p = parse_hassl(text)
+                # prefer declared package; otherwise bind to module id
+                pkg_name = p.package or abs_mod
+                p.package = pkg_name
+
+                programs.append((candidate, p, pkg_name))
+                known_pkgs.add(pkg_name)
+                seen_modules.add(abs_mod)
+                seen_paths.add(candidate)
+                added = True
+                
 def main():
     print("[hasslc] Using CLI file:", __file__)
     ap = argparse.ArgumentParser(prog="hasslc", description="HASSL Compiler")
@@ -197,174 +225,12 @@ def main():
 
     # Also drop a cross-project export table for debugging
     with open(out_root / "DEBUG_exports.json", "w", encoding="utf-8") as fp:
-        printable = {f"{k[0]}::{k[1]}::{k[2]}": ("Alias" if isinstance(v, Alias) else "Schedule") for k, v in GLOBAL_EXPORTS.items()}
-        json.dump(printable, fp, indent=2)
-    print(f"[hasslc] Global exports index written to {out_root / 'DEBUG_exports.json'}")
-
-if __name__ == "__main__":
-    main()
-import argparse
-import os, json, glob
-from pathlib import Path
-from typing import Dict, Tuple, List
-from .parser.loader import load_grammar_text
-from .parser.transform import HasslTransformer
-from .ast.nodes import Program, Alias, Schedule
-from lark import Lark
-from .semantics import analyzer as sem_analyzer
-from .semantics.analyzer import analyze
-from .codegen.package import emit_package
-from .codegen import generate as codegen_generate
-
-def parse_hassl(text: str) -> Program:
-    grammar = load_grammar_text()
-    parser = Lark(grammar, start="start", parser="lalr", maybe_placeholders=False)
-    tree = parser.parse(text)
-    program = HasslTransformer().transform(tree)
-    return program
-
-def _derive_package_name(prog: Program, src_path: Path, module_root: Path | None) -> str:
-    """
-    If the source did not declare `package`, derive one from the path:
-    - If module_root is given and src_path is under it: use relative path (dots)
-    - Else: use file stem
-    """
-    if getattr(prog, "package", None):
-        return prog.package  # declared
-    if module_root:
-        try:
-            rel = src_path.resolve().relative_to(module_root.resolve())
-            parts = list(rel.with_suffix("").parts)
-            if parts:
-                return ".".join(parts)
-        except Exception:
-            pass
-    return src_path.stem
-
-def _collect_public_exports(prog: Program, pkg: str) -> Dict[Tuple[str,str,str], object]:
-    """
-    Build (pkg, kind, name) -> node for public alias/schedule in a single Program.
-    Accepts both Schedule nodes and transformer dicts {"type":"schedule_decl",...}.
-    """
-    out: Dict[Tuple[str,str,str], object] = {}
-    # Aliases
-    for s in prog.statements:
-        if isinstance(s, Alias):
-            if not getattr(s, "private", False):
-                out[(pkg, "alias", s.name)] = s
-    # Schedules (either dicts from transformer or Schedule nodes)
-    for s in prog.statements:
-        if isinstance(s, Schedule):
-            if not getattr(s, "private", False):
-                out[(pkg, "schedule", s.name)] = s
-        elif isinstance(s, dict) and s.get("type") == "schedule_decl" and not s.get("private", False):
-            name = s.get("name")
-            if isinstance(name, str) and name.strip():
-                out[(pkg, "schedule", name)] = Schedule(name=name, clauses=s.get("clauses", []) or [], private=False)
-    return out
-
-def _scan_hassl_files(path: Path) -> List[Path]:
-    if path.is_file():
-        return [path]
-    return [Path(p) for p in glob.glob(str(path / "**" / "*.hassl"), recursive=True)]
-
-def _module_to_path(module_root: Path, module: str) -> Path:
-    return (module_root / Path(module.replace(".", "/"))).with_suffix(".hassl")
-
-def _ensure_imports_loaded(programs, module_root: Path):
-    """If imported packages aren't parsed yet, try to load their .hassl files from module_root."""
-    # programs: List[tuple[Path, Program, str]]
-    known_pkgs = {pkg for _, _, pkg in programs}
-    added = True
-    while added:
-        added = False
-        for _, prog, _pkg in list(programs):
-            for imp in getattr(prog, "imports", []) or []:
-                if not isinstance(imp, dict) or imp.get("type") != "import":
-                    continue
-                mod = imp.get("module", "")
-                if not mod or mod in known_pkgs:
-                    continue
-                if not module_root:
-                    continue
-                candidate = _module_to_path(module_root, mod)
-                if candidate.exists():
-                    print(f"[hasslc] Autoload candidate FOUND for '{mod}': {candidate}")
-                    with open(candidate, "r", encoding="utf-8") as f:
-                        text = f.read()
-                    p = parse_hassl(text)
-                    # force package to declared or derived (declared will win)
-                    pkg_name = p.package or mod
-                    p.package = pkg_name
-                    programs.append((candidate, p, pkg_name))
-                    known_pkgs.add(pkg_name)
-                    added = True
-                else:
-                    print(f"[hasslc] Autoload candidate MISS for '{mod}': {candidate}")
-
-def main():
-    ap = argparse.ArgumentParser(prog="hasslc", description="HASSL Compiler")
-    ap.add_argument("input", help="Input .hassl file OR directory")
-    ap.add_argument("-o", "--out", default="./packages/out", help="Output directory root for HA package(s)")
-    ap.add_argument("--module-root", default=None, help="Optional root to derive package names from paths")
-    args = ap.parse_args()
-
-    in_path = Path(args.input)
-    out_root = Path(args.out)
-    module_root = Path(args.module_root).resolve() if args.module_root else None
-
-    src_files = _scan_hassl_files(in_path)
-    if not src_files:
-        raise SystemExit(f"[hasslc] No .hassl files found in {in_path}")
-
-    # Pass 0: parse all and assign/derive package names
-    programs: List[tuple[Path, Program, str]] = []
-    for p in src_files:
-        with open(p, "r", encoding="utf-8") as f:
-            text = f.read()
-        prog = parse_hassl(text)
-        pkg_name = _derive_package_name(prog, p, module_root)
-        try:
-            prog.package = pkg_name
-        except Exception:
-            pass
-        programs.append((p, prog, pkg_name))
-
-    # auto-load any missing imports from --module_root
-    _ensure_imports_loaded(programs, module_root)
-    
-    # Pass 1: collect public exports across all programs
-    GLOBAL_EXPORTS: Dict[Tuple[str,str,str], object] = {}
-    for path, prog, pkg in programs:
-        GLOBAL_EXPORTS.update(_collect_public_exports(prog, pkg))
-
-    # publish global exports to analyzer
-    sem_analyzer.GLOBAL_EXPORTS = GLOBAL_EXPORTS
-
-    # Pass 2: analyze each program with global view
-    os.makedirs(out_root, exist_ok=True)
-    all_ir = []
-    for path, prog, pkg in programs:
-        print(f"[hasslc] Parsing {path}  (package: {pkg})")
-        print("[hasslc] AST:", json.dumps(prog.to_dict(), indent=2))
-        ir = analyze(prog)
-        print("[hasslc] IR:", json.dumps(ir.to_dict(), indent=2))
-        all_ir.append((pkg, ir))
-
-    # Emit: per package subdir
-    for pkg, ir in all_ir:
-        pkg_dir = out_root / pkg.replace(".", "_")
-        os.makedirs(pkg_dir, exist_ok=True)
-        ir_dict = ir.to_dict() if hasattr(ir, "to_dict") else ir
-        codegen_generate(ir_dict, str(pkg_dir))
-        emit_package(ir, str(pkg_dir))
-        with open(pkg_dir / "DEBUG_ir.json", "w", encoding="utf-8") as dbg:
-            dbg.write(json.dumps(ir.to_dict(), indent=2))
-        print(f"[hasslc] Package written to {pkg_dir}")
-
-    # Also drop a cross-project export table for debugging
-    with open(out_root / "DEBUG_exports.json", "w", encoding="utf-8") as fp:
-        printable = {f"{k[0]}::{k[1]}::{k[2]}": ("Alias" if isinstance(v, Alias) else "Schedule") for k, v in GLOBAL_EXPORTS.items()}
+        def _kind(v):
+            if isinstance(v, Alias): return "Alias"
+            if isinstance(v, Schedule): return "Schedule"
+            if isinstance(v, TemplateDecl): return "Template"
+            return type(v).__name__
+        printable = {f"{k[0]}::{k[1]}::{k[2]}": _kind(v) for k, v in GLOBAL_EXPORTS.items()}
         json.dump(printable, fp, indent=2)
     print(f"[hasslc] Global exports index written to {out_root / 'DEBUG_exports.json'}")
 

hassl/codegen/package.py

@@ -215,7 +215,20 @@ def _holiday_condition(mode: Optional[str], hol_id: Optional[str]):
     # True when today is a holiday for 'only', false when 'except'
     eid = f"binary_sensor.hassl_holiday_{hol_id}"
     return {"condition": "state", "entity_id": eid, "state": "on" if mode == "only" else "off"}
-    
+
+def _norm_hmode(raw: Optional[str]) -> Optional[str]:
+    """Coerce analyzer-provided holiday_mode variants to {'only','except',None}."""
+    if not raw:
+        return None
+    v = str(raw).strip().lower().replace("_", " ").replace("-", " ")
+    # Accept a bunch of user/analyzer phrasings
+    if any(k in v for k in ("except", "exclude", "unless", "not")):
+        return "except"
+    if any(k in v for k in ("only", "holiday only", "holidays only")):
+        return "only"
+    # Unknown → leave as-is to avoid surprising behavior
+    return raw
+
 def _trigger_for(ts: Dict[str, Any]) -> Dict[str, Any]:
     """
     Build a HA trigger for a time-spec dict:
@@ -787,8 +800,10 @@ def emit_package(ir: IRProgram, outdir: str):
 
             ds = w.get("day_selector")
             href = w.get("holiday_ref")
-            hmode = w.get("holiday_mode")
+            hmode = _norm_hmode(w.get("holiday_mode"))
             period = w.get("period")
+            if href and hmode is None and ds in ("weekdays", "weekends"):
+                hmode = "except"
 
             # Coerce time specs to dicts compatible with _trigger_for/_window_condition_from_specs
             raw_start = w.get("start")
@@ -797,9 +812,13 @@ def emit_package(ir: IRProgram, outdir: str):
                 if isinstance(ts, dict):
                     return ts
                 if isinstance(ts, str):
+                    v = ts.strip()
                     # accept "HH:MM" or "HH:MM:SS"
-                    v = ts if len(ts) in (5,8) else "00:00"
-                    return {"kind":"clock","value": v[:5] if len(v)==5 else v[:8]}
+                    if len(v) == 5:   # HH:MM
+                        return {"kind":"clock","value": v}
+                    if len(v) == 8:   # HH:MM:SS
+                        return {"kind":"clock","value": v}
+                    return {"kind":"clock","value":"00:00"}
                 return {"kind":"clock","value":"00:00"}
             start_ts = _coerce(raw_start)
             end_ts   = _coerce(raw_end)

hassl/codegen/rules_min.py

@@ -331,10 +331,15 @@ def _collect_schedules(ir: dict):
     inline_by_rule = {}
     use_by_rule = {}
 
-    # top-level declared schedules
+    # top-level declared schedules (legacy clauses)
     schedules_obj = ir.get("schedules") or {}
     if isinstance(schedules_obj, dict):
         declared = {str(k): (v or []) for k, v in schedules_obj.items()}
+    # include window schedules as declared (no legacy clauses, but valid names)
+    windows_obj = ir.get("schedules_windows") or {}
+    if isinstance(windows_obj, dict):
+        for k in windows_obj.keys():
+            declared.setdefault(str(k), [])
 
     # per-rule data
     for rule in ir.get("rules", []):
@@ -359,7 +364,7 @@ def generate_rules(ir, outdir):
     # collect helper keys we must ensure exist
     ctx_inputs = {}
 
-    # package slug for schedule sensor ids
+    # package slug for output file naming
     pkg = _pkg_slug(outdir)
 
     # --- schedules collection ---
@@ -385,16 +390,14 @@ def generate_rules(ir, outdir):
         for nm in (use_by_rule.get(rname, []) or []):
             base = str(nm).split(".")[-1]
             if base not in declared_base_names and (base not in exported_sched_pkgs):
-                expected_sensor = _schedule_sensor(base, pkg)
                 raise ValueError(
                     "HASSL: schedule reference not found. "
                     f"Rule '{rname}' uses schedule '{nm}', but no schedule named '{base}' "
-                    f"was declared in this package '{pkg}'.\n\n"
+                    "was declared in this package.\n\n"
                     "Declare it with:\n"
                     f"  schedule {base}:\n"
                     "    enable from <start> to <end>;\n\n"
                     "Or ensure the schedule is declared in the same package.\n"
-                    f"(If you expected a sensor, codegen looks for: {expected_sensor})"
                 )
 
     # NOTE: No helper creation here — package.py owns schedule sensors.
@@ -415,15 +418,6 @@ def generate_rules(ir, outdir):
         if rule_gates:
             for g in rule_gates:
                 ents = [e for e in (g.get("entities") or []) if isinstance(e, str)]
-                # Also include the legacy, current-outdir slug binary_sensor expected by older tests/code
-                # Determine the base schedule name, then synthesize the local sensor id.
-                resolved = str(g.get("resolved", "")) if isinstance(g.get("resolved", ""), str) else ""
-                base = resolved.rsplit(".", 1)[-1] if resolved else None
-                if base:
-                    legacy_local = _schedule_sensor(base, pkg)  # e.g., binary_sensor.hassl_schedule_out_std_<base>_active
-                    if legacy_local not in ents:
-                        ents.append(legacy_local)
-                        
                 if not ents:
                     continue
                 if len(ents) == 1:
@@ -593,11 +587,11 @@ def generate_rules(ir, outdir):
                         "data": {"entity_id": full, "value": str(val)}
                     })
                 else:
-                    # Try light.turn_on data first; fallback to generic service data
-                    if eid.startswith("light."):
-                        act_list.append({"service": "light.turn_on", "target": {"entity_id": eid}, "data": {attr: val}})
-                    else:
-                        act_list.append({"service": "homeassistant.turn_on", "target": {"entity_id": eid}, "data": {attr: val}})
+                    # Unknown action type: log and skip (keeps generator robust)
+                    act_list.append({
+                        "service": "logbook.log",
+                        "data": {"name": "HASSL", "message": f"Unhandled action type: {act.get('type')}"}
+                    })
 
             conds = [gate_cond] + sched_conds + [cond_ha]
             if qual_cond:

hassl/parser/hassl.lark

@@ -2,6 +2,7 @@
 // + additive schedule support
 // + packages/imports + private visibility
 
+
 start: stmt*
 
 stmt: package_decl
@@ -11,6 +12,8 @@ stmt: package_decl
     | rule
     | schedule_decl
     | holidays_decl
+    | template_decl
+    | use_template_stmt
 
 // --- Aliases ---
 alias: PRIVATE? "alias" CNAME "=" entity //can mark private
@@ -18,11 +21,6 @@ alias: PRIVATE? "alias" CNAME "=" entity //can mark private
 // --- Sync ---
 sync: "sync" synctype "[" entity_list "]" "as" CNAME syncopts?
 
-ONOFF: "onoff"
-DIMMER: "dimmer"
-ATTRIBUTE: "attribute"
-SHARED: "shared"
-ALL: "all"
 synctype: ONOFF | DIMMER | ATTRIBUTE | SHARED | ALL
 
 syncopts: "{" ("invert" ":" entity_list) "}"
@@ -74,7 +72,7 @@ assign: CNAME "=" STATE ("for" dur)?
 attr_assign: CNAME "." CNAME ("." CNAME)* "." CNAME "=" NUMBER
            | CNAME "." CNAME "=" NUMBER
 
-waitact: "wait" "(" condition "for" dur ")" action
+waitact: "wait" "(" condition "for" (dur | CNAME | STRING) ")" action
 // condition used by wait(): allow expr + optional qualifier inside the parens
 condition: expr qualifier?
 
@@ -88,37 +86,24 @@ UNIT: "ms" | "s" | "m" | "h" | "d"
 // Timepoint placeholder (kept simple)
 timepoint: CNAME
 
-SCHEDULE: "schedule"
-USE: "use"
-FROM: "from"
-TO: "to"
-UNTIL: "until"
-ENABLE: "enable"
-DISABLE: "disable"
-SUNRISE: "sunrise"
-SUNSET: "sunset"
-PRIVATE: "private"
-
-TIME_HHMM: /[0-2]?\d:[0-5]\d/
-OFFSET: /[+-]\d+(ms|s|m|h|d)/
-
 // Reusable named schedule declarations
 schedule_decl: PRIVATE? SCHEDULE CNAME ":" schedule_clause+
 
 // Clauses usable both in declarations and inline
 // Keep legacy form AND add new 'on …' forms
 schedule_clause: schedule_legacy_clause
-               | schedule_new_clause
+               | schedule_window_clause
+	       | sched_holiday_only
 
 // Legacy (unchanged)
 schedule_legacy_clause: schedule_op FROM time_spec schedule_end? ";"
 
 // NEW schedule window syntax:
-//   [during <period>] on (weekdays|weekends|daily) HH:MM-HH:MM [except holidays <id>] ;
+//   [during <period>] on (weekdaysNo, |weekends|daily) HH:MM-HH:MM [except holidays <id>] ;
 //   on holidays <id> HH:MM-HH:MM ;
-schedule_new_clause: period? "on" day_selector time_range holiday_mod? ";"
-                   | "on" "holidays" CNAME time_range ";"
+schedule_window_clause: period? "on" day_selector time_range holiday_mod? ";"
 
+sched_holiday_only: "on" "holidays" CNAME time_range ";"
 // Periods
 period: "during" "months" month_range
       | "during" "dates"  mmdd_range
@@ -131,7 +116,7 @@ MMDD: /\d{2}-\d{2}/
 ymd_range: YMD ".." YMD
 YMD: /\d{4}-\d{2}-\d{2}/
 
-day_selector: "weekdays" | "weekends" | "daily"
+day_selector: WEEKDAYS | WEEKENDS | DAILY
 time_range: TIME_HHMM "-" TIME_HHMM
 holiday_mod: "except" "holidays" CNAME
 
@@ -140,7 +125,7 @@ schedule_end: TO time_spec    -> schedule_to
             | UNTIL time_spec -> schedule_until
 
 // Rule-level usage
-rule_schedule_use: SCHEDULE USE name_list ";"
+rule_schedule_use: SCHEDULE USE name_list ";"?
 // allow qualified (pkg.symbol) via existing 'entity' rule
 name_list: name ("," name)*
 name: CNAME | entity
@@ -162,12 +147,41 @@ member: entity | CNAME
 
 entity: CNAME ("." CNAME)+
 
+
 // ---- Lexer ----
-%import common.CNAME
-%import common.WS
+// Order matters: keyword terminals first so they take precedence over CNAME
+SCHEDULE: "schedule"
+USE: "use"
+FROM: "from"
+TO: "to"
+UNTIL: "until"
+ENABLE: "enable"
+DISABLE: "disable"
+SUNRISE: "sunrise"
+SUNSET: "sunset"
+PRIVATE: "private"
+TEMPLATE: "template"
+
+ONOFF: "onoff"
+DIMMER: "dimmer"
+ATTRIBUTE: "attribute"
+SHARED: "shared"
+ALL: "all"
+WEEKDAYS: "weekdays"
+WEEKENDS: "weekends"
+DAILY:    "daily"
+
 %import common.ESCAPED_STRING -> STRING
 %import common.INT
 %import common.SIGNED_NUMBER
+%import common.WS
+
+// Override CNAME after keywords, so keywords win
+CNAME: /[a-zA-Z_][a-zA-Z0-9_]*/
+
+TIME_HHMM: /[0-2]?\d:[0-5]\d/
+OFFSET: /[+-]\d+(ms|s|m|h|d)/
+
 LINE_COMMENT: /\/\/[^\n]*/
 %ignore LINE_COMMENT
 %ignore WS
@@ -188,7 +202,7 @@ import_tail: ".*"
 import_list: import_item ("," import_item)*
 import_item: CNAME ("as" CNAME)?
 
-// ---- Holidays declaration (NEW) ----
+// ---- Holidays declaration ----
 // Example:
 // holidays us_ca:
 //   country="US", province="CA", add=["2025-11-28"], remove=["2025-12-26"]
@@ -203,4 +217,28 @@ daylist: DAY ("," DAY)*
 excludelist: ("sat"|"sun"|"holiday") ("," ("sat"|"sun"|"holiday"))*
 DAY.2: "mon"|"tue"|"wed"|"thu"|"fri"|"sat"|"sun"
 DATESTR: /"\d{4}-\d{2}-\d{2}"/
-datestr_list: DATESTR ("," DATESTR)*
+datestr_list: DATESTR ("," DATESTR)*
+
+// === Template
+template_decl: PRIVATE? TEMPLATE template_kind CNAME "(" template_params? ")" ":" template_body
+template_kind: "rule" | "sync" | "schedule"
+template_params: template_param ("," template_param)*
+template_param: CNAME ("=" template_default)?
+template_default: NUMBER | STRING | CNAME
+
+template_body: rule_body     -> template_rule_body
+             | sync_body     -> template_sync_body
+             | schedule_body -> template_schedule_body
+
+// --- Bodies used by template_body (define these ONCE) ---
+rule_body: rule_clause+                         // clauses without 'rule NAME:'
+sync_body: synctype "[" entity_list "]" syncopts?
+schedule_body: schedule_clause+                 // clauses without 'schedule NAME:'
+
+// Reuse existing pieces parsed elsewhere (no duplicates below this line)
+
+// --- Template invocation ---
+use_template_stmt: "use" "template" CNAME "(" call_args? ")" ("as" CNAME)?
+call_args: call_arg ("," call_arg)*
+call_arg: (CNAME "=" value) | value
+value: NUMBER | STRING | entity | CNAME