statable 3.1.0__py3-none-any.whl

statable/cli.py

@@ -0,0 +1,251 @@
+# code/statable/cli.py
+"""statable-cli - Command-line interface for StaTable SDK.
+
+Subcommands:
+    generate    Generate C code from a design XML file
+    validate    Validate a design XML file
+    version     Print version
+
+Output:
+    stdout: JSON result (default) or plain text
+    stderr: log / error messages
+
+Exit codes:
+    0   success
+    1   validation error (validate --exit-on-error)
+    2   internal error (missing file, parse failure, etc.)
+
+Usage:
+    statable-cli generate --xml design.xml --out generated/ --format json
+    statable-cli validate --xml design.xml --format json --exit-on-error
+    statable-cli version
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+CLI_VERSION = "3.1.0"
+
+
+def _err(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def _load_project(xml_path: str):
+    """Load XML design file.
+
+    Returns (tabs, gd, rf_lib, cond_lib, lit_lib, settings).
+    """
+    from statable.xml_io import project_from_xml
+    return project_from_xml(xml_path)
+
+
+def _build_config(settings):
+    """Build CodeGenerationConfig from project settings dict."""
+    from codegen.config import CodeGenerationConfig
+    cfg = CodeGenerationConfig()
+    if not settings:
+        return cfg
+    for key, value in settings.items():
+        if key == "project_name":
+            continue
+        if hasattr(cfg, key):
+            try:
+                setattr(cfg, key, value)
+            except Exception:
+                pass
+    return cfg
+
+
+def cmd_generate(args) -> int:
+    xml_path = args.xml
+    out_dir = args.out
+
+    try:
+        tabs, gd, rf_lib, _cond, _lit, settings = _load_project(xml_path)
+    except FileNotFoundError:
+        _err(f"error: XML file not found: {xml_path}")
+        return 2
+    except Exception as e:
+        _err(f"error: failed to load project: {e!r}")
+        return 2
+
+    if not tabs:
+        _err("error: no tabs/state machines found in project")
+        return 2
+
+    try:
+        cfg = _build_config(settings)
+    except Exception as e:
+        _err(f"error: config setup failed: {e!r}")
+        return 2
+
+    try:
+        from codegen.c_code_generator import CCodeGenerator
+        gen = CCodeGenerator(config=cfg)
+        generated = gen.generate_all_layers(
+            tabs, gd, role_function_library=rf_lib,
+        )
+    except Exception as e:
+        _err(f"error: generation failed: {e!r}")
+        return 2
+
+    try:
+        Path(out_dir).mkdir(parents=True, exist_ok=True)
+        saved = gen.save_generated_code(generated, str(out_dir))
+    except Exception as e:
+        _err(f"error: save failed: {e!r}")
+        return 2
+
+    out_res = Path(out_dir).resolve()
+    rel_files = []
+    for p in saved:
+        try:
+            rel_files.append(
+                Path(p).resolve().relative_to(out_res).as_posix()
+            )
+        except ValueError:
+            rel_files.append(Path(p).name)
+    rel_files.sort()
+
+    if args.format == "json":
+        result = {
+            "status": "ok",
+            "command": "generate",
+            "input": str(xml_path),
+            "output_dir": str(out_dir),
+            "files_generated": rel_files,
+            "warnings": [],
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"OK: {len(saved)} files generated in {out_dir}")
+        for f in rel_files:
+            print(f"  {f}")
+    return 0
+
+
+def cmd_validate(args) -> int:
+    xml_path = args.xml
+
+    try:
+        tabs, gd, _rf, _cond, _lit, _settings = _load_project(xml_path)
+    except FileNotFoundError:
+        _err(f"error: XML file not found: {xml_path}")
+        return 2
+    except Exception as e:
+        _err(f"error: failed to load project: {e!r}")
+        return 2
+
+    if not tabs:
+        _err("error: no tabs/state machines found in project")
+        return 2
+
+    try:
+        from codegen.validate.validator import CodeGenerationValidator
+        validator = CodeGenerationValidator()
+    except Exception as e:
+        _err(f"error: validator init failed: {e!r}")
+        return 2
+
+    all_issues = []
+    total_errors = 0
+    total_warnings = 0
+
+    for name, sm in tabs:
+        try:
+            res = validator.validate(sm, gd)
+        except Exception as e:
+            _err(f"error: validation failed for tab {name!r}: {e!r}")
+            return 2
+        for issue in res.issues:
+            d = issue.to_dict()
+            d["tab"] = name
+            all_issues.append(d)
+        total_errors += res.error_count
+        total_warnings += res.warning_count
+
+    status = "ok" if total_errors == 0 else "error"
+
+    if args.format == "json":
+        out = {
+            "status": status,
+            "command": "validate",
+            "input": str(xml_path),
+            "errors": total_errors,
+            "warnings": total_warnings,
+            "issues": all_issues,
+        }
+        print(json.dumps(out, indent=2))
+    else:
+        print(
+            f"{status.upper()}: errors={total_errors} "
+            f"warnings={total_warnings}"
+        )
+        for d in all_issues:
+            sev = d.get("severity", "?")
+            code = d.get("code", "?")
+            msg = d.get("message", "")
+            print(f"  [{sev}] {code}: {msg}")
+
+    if args.exit_on_error and total_errors > 0:
+        return 1
+    return 0
+
+
+def cmd_version(args) -> int:
+    try:
+        from statable import __version__ as pkg_version
+    except Exception:
+        pkg_version = CLI_VERSION
+    print(f"statable-cli {pkg_version}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="statable-cli",
+        description="StaTable command-line interface",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"statable-cli {CLI_VERSION}",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_gen = sub.add_parser("generate", help="Generate C code from XML")
+    p_gen.add_argument("--xml", required=True,
+                       help="Input design XML file")
+    p_gen.add_argument("--out", required=True,
+                       help="Output directory")
+    p_gen.add_argument("--format", choices=["json", "text"],
+                       default="json")
+    p_gen.set_defaults(func=cmd_generate)
+
+    p_val = sub.add_parser("validate", help="Validate XML design file")
+    p_val.add_argument("--xml", required=True,
+                       help="Input design XML file")
+    p_val.add_argument("--format", choices=["json", "text"],
+                       default="json")
+    p_val.add_argument("--exit-on-error", action="store_true",
+                       help="Return exit code 1 on validation error")
+    p_val.set_defaults(func=cmd_validate)
+
+    p_ver = sub.add_parser("version", help="Print version")
+    p_ver.set_defaults(func=cmd_version)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

statable/global_defs.py

@@ -0,0 +1,256 @@
+"""Data model for global variables, event flags, interrupt handlers, device resources, timer settings, and user-defined types"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class StructMemberDef:
+    """Struct member definition"""
+    name: str
+    data_type: str
+    bit_width: int = 0
+    description: str = ""
+    title: str = ""
+    array_size: int = 0
+
+    def __post_init__(self):
+        if not self.title:
+            if self.bit_width > 0:
+                self.title = f"{self.name}:{self.bit_width}"
+            elif self.array_size > 0:
+                self.title = f"{self.name}[{self.array_size}]"
+            else:
+                self.title = f"Member: {self.name}"
+
+
+@dataclass
+class CustomTypeDef:
+    """User-defined types (structs, etc.)"""
+    name: str
+    description: str = ""
+    members: List[StructMemberDef] = field(default_factory=list)
+    title: str = ""
+
+    def __post_init__(self):
+        if not self.title:
+            self.title = f"Type: {self.name}"
+
+
+@dataclass
+class SystemVariable:
+    """Global variables shared across the system"""
+    name: str
+    type: str
+    unit: str = ""
+    default_value: str = ""
+    group: str = ""
+    description: str = ""
+    title: str = ""
+    array_size: int = 0
+
+    def __post_init__(self):
+        if not self.title:
+            if self.array_size > 0:
+                self.title = f"{self.name}[{self.array_size}]"
+            else:
+                self.title = f"Variable: {self.name}"
+
+
+@dataclass
+class EventFlag:
+    """Event flags managed as bit fields"""
+    name: str
+    min_value: int
+    max_value: int
+    group: str = ""
+    description: str = ""
+    title: str = ""
+
+    def __post_init__(self):
+        if not self.title:
+            self.title = f"Flag: {self.name}"
+
+    @property
+    def bit_width(self) -> int:
+        if self.max_value < self.min_value:
+            return 0
+        return (self.max_value - self.min_value).bit_length()
+
+
+@dataclass
+class InterruptAction:
+    """Conditional actions inside an interrupt handler"""
+    condition: str = ""
+    action: str = ""
+
+
+@dataclass
+class InterruptHandlerDef:
+    """Interrupt handler definition
+
+    used_role_functions: list of used role functions' qualified_name (auto-extracted)
+      - e.g. ["Driver.Init", "Application.HandleTick"]
+      - Updated when the ISR action is saved
+      - Also used in generated code comments
+
+    used_variables: list of used global variable names (auto-extracted)
+      - e.g. ["counter", "g_system_tick"]
+    """
+    name: str
+    description: str = ""
+    event_names: List[str] = field(default_factory=list)
+    is_timer: bool = False
+    actions: List[InterruptAction] = field(default_factory=list)
+    title: str = ""
+    # Added: usage record
+    used_role_functions: List[str] = field(default_factory=list)
+    used_variables: List[str] = field(default_factory=list)
+
+    def __post_init__(self):
+        if not self.title:
+            self.title = f"Interrupt: {self.name}"
+
+
+@dataclass
+class DevicePlaceholderDef:
+    """Device resource placeholder definition"""
+    name: str
+    description: str = ""
+    title: str = ""
+
+    def __post_init__(self):
+        if not self.title:
+            self.title = f"Device: {self.name}"
+
+
+@dataclass
+class TimerDerivedDef:
+    """Derived timer variable definition"""
+    period_name: str
+    multiplier: int
+    variable_name: str
+    data_type: str = "uint8_t"
+    title: str = ""
+
+    def __post_init__(self):
+        if not self.title:
+            self.title = f"Timer: {self.variable_name}"
+
+
+@dataclass
+class TimerBaseDef:
+    """Timer tick variable definition"""
+    variable_name: str = "g_system_tick"
+    unit: str = "1ms"
+    data_type: str = "volatile uint32_t"
+    derived: List[TimerDerivedDef] = field(default_factory=list)
+    title: str = ""
+    interrupt_name: str = ""
+
+    def __post_init__(self):
+        if not self.title:
+            self.title = f"Timer base: {self.variable_name}"
+
+
+@dataclass
+class EventQueueDef:
+    """Event queue definition"""
+    name: str
+    size: int
+    element_type: str
+    event_ids: List[str] = field(default_factory=list)
+    priority_enabled: bool = False
+    interrupt_safe: bool = True
+    rtos_enabled: bool = False
+    description: str = ""
+    title: str = ""
+
+    def __post_init__(self):
+        if not self.title:
+            self.title = f"Queue: {self.name}"
+
+
+class GlobalDefinitions:
+    """Management class for global variables, event flags, interrupt handlers, device resources, timer settings, event queues, and user-defined types"""
+
+    def __init__(self):
+        self.variables: List[SystemVariable] = []
+        self.flags: List[EventFlag] = []
+        self.interrupts: List[InterruptHandlerDef] = []
+        self.placeholders: List[DevicePlaceholderDef] = []
+        self.timer_base: TimerBaseDef = TimerBaseDef()
+        self.extra_timers: List[TimerBaseDef] = []
+        self.event_queues: List[EventQueueDef] = []
+        self.custom_types: List[CustomTypeDef] = []
+
+    def add_timer_variables(self):
+        """Timer base variables and derived timer variables are registered as global variables.
+
+        - Existing variables (loaded from XML or edited in GUI) preserve description / title
+        - Only type / unit are synchronized with the timer definition
+        - Only non-existing variables are newly added
+
+        This ensures description / title are preserved across round-trips.
+        """
+        existing_by_name = {v.name: v for v in self.variables}
+
+        def _sync_or_add(name, type_, unit, default, group,
+                         default_desc, default_title):
+            if name in existing_by_name:
+                v = existing_by_name[name]
+                # Treat timer definition as authoritative (type, unit)
+                v.type = type_
+                v.unit = unit
+                # Preserve existing description / title
+                if not v.description:
+                    v.description = default_desc
+                if not v.title:
+                    v.title = default_title
+                # If group is unset, fill in
+                if not v.group:
+                    v.group = group
+            else:
+                self.variables.append(SystemVariable(
+                    name=name,
+                    type=type_,
+                    unit=unit,
+                    default_value=default,
+                    group=group,
+                    description=default_desc,
+                    title=default_title,
+                ))
+
+        all_timers = [self.timer_base] + self.extra_timers
+        for timer in all_timers:
+            # Base timer variable
+            _sync_or_add(
+                name=timer.variable_name,
+                type_=timer.data_type,
+                unit=timer.unit,
+                default="0",
+                group="Timer",
+                default_desc="Timer base variable",
+                default_title=timer.title or f"Timer base: {timer.variable_name}",
+            )
+            # Derived timer variable
+            for d in timer.derived:
+                _sync_or_add(
+                    name=d.variable_name,
+                    type_=d.data_type,
+                    unit=d.period_name,
+                    default="0",
+                    group="Timer",
+                    default_desc=f"Derived timer variable ({d.period_name})",
+                    default_title=d.title or f"Timer: {d.variable_name}",
+                )
+
+    # Get group name
+    def variable_groups(self) -> List[str]:
+        return sorted({v.group for v in self.variables if v.group})
+
+    def flag_groups(self) -> List[str]:
+        return sorted({f.group for f in self.flags if f.group})
+
+    def custom_type_names(self) -> List[str]:
+        return sorted({t.name for t in self.custom_types})

statable/mermaid_gen.py

@@ -0,0 +1,144 @@
+from .state_machine import StateMachine
+
+
+# ============================================================
+# Mermaid label sanitization (v2.0 / v2.2)
+#   All replacements use ASCII to satisfy the English-only policy.
+# ============================================================
+_MERMAID_LABEL_REPLACEMENTS = (
+    (":",  "-"),   # colon -> dash
+    ("[",  "("),   # opening bracket -> paren
+    ("]",  ")"),   # closing bracket -> paren
+    ('"',  "'"),
+    ("`",  "'"),
+    ("\n", " "),
+    ("\r", " "),
+)
+
+
+def _sanitize_label(text: str) -> str:
+    """Sanitize the Mermaid label string."""
+    if not text:
+        return ""
+    for src, dst in _MERMAID_LABEL_REPLACEMENTS:
+        text = text.replace(src, dst)
+    text = " ".join(text.split())
+    return text
+
+
+def _truncate_condition(condition: str, max_chars: int = 50) -> str:
+    """Show long state transition conditions abbreviated."""
+    if not condition:
+        return ""
+    lines = condition.split('\n')
+    first_line = lines[0].strip() if lines else ""
+    if not first_line:
+        return ""
+    if len(first_line) > max_chars:
+        return first_line[:max_chars].rstrip() + "..."
+    if len(lines) > 1:
+        return first_line + " ..."
+    return first_line
+
+
+def _mode_suffix(trans) -> str:
+    """
+    v2.2: Return a short mode suffix for the transition label.
+
+    "C" -> Commit    (early_return=True)
+    "T" -> Tentative (early_return=False)
+    Empty string is returned when early_return is not set (backward compat).
+    """
+    er = getattr(trans, 'early_return', None)
+    if er is True:
+        return " [Commit]"
+    return ""
+
+
+def _build_label(trans, *, short_mode: bool = True) -> str:
+    """Build the Mermaid label for a single transition."""
+    label_parts = []
+
+    # ---- Title ----
+    title_raw = getattr(trans, 'title', '') or ""
+    title_safe = _sanitize_label(title_raw)
+    if title_safe and title_safe != "(untitled transition)":
+        label_parts.append(title_safe)
+    else:
+        if getattr(trans, 'target', ''):
+            label_parts.append(_sanitize_label(trans.target))
+        else:
+            label_parts.append("(internal)")
+
+    # ---- Event ----
+    ev = getattr(trans, 'event', '') or ""
+    if ev:
+        ev_safe = _sanitize_label(ev)
+        if ev_safe:
+            label_parts.append(f"({ev_safe})")
+
+    # ---- Condition ----
+    cond = getattr(trans, 'condition', '') or ""
+    if cond:
+        cond_text = _sanitize_label(_truncate_condition(cond))
+        if cond_text:
+            label_parts.append(f"[{cond_text}]")
+
+    # ---- Mode (v2.2) ----
+    mode = _mode_suffix(trans)
+    if mode:
+        label_parts.append(mode)
+
+    return " ".join(label_parts).strip()
+
+
+def generate_mermaid(sm: StateMachine) -> str:
+    """
+    Generate a Mermaid stateDiagram-v2 string from a StateMachine.
+
+    [v2.2 changes]
+      - Each transition in a cell becomes its own edge.
+      - else_target is emitted as a separate edge (dashed style not
+        available in stateDiagram-v2, so we use label "else").
+      - early_return=True adds " [Commit]" to the label.
+      - entry / exit are NOT rendered (metadata only).
+    """
+    lines = ["stateDiagram-v2", "    direction LR"]
+
+    if sm.initial_state:
+        lines.append(f"    [*] --> {sm.initial_state}")
+
+    for t in sm.transitions:
+        # ---- Primary edge (target) ----
+        if t.target:
+            label = _build_label(t)
+            lines.append(f"    {t.source} --> {t.target} : {label}")
+        else:
+            # No target: internal action only -> attach a note
+            label = _build_label(t)
+            lines.append(f"    note right of {t.source} : internal: {label}")
+
+        # ---- Secondary edge (else_target) ----
+        else_target = getattr(t, 'else_target', '') or ''
+        has_else = getattr(t, 'has_else', True)
+        if has_else and else_target:
+            else_label_parts = []
+            # Show event name (if any) so the edge is identifiable
+            ev = getattr(t, 'event', '') or ""
+            if ev:
+                ev_safe = _sanitize_label(ev)
+                if ev_safe:
+                    else_label_parts.append(f"({ev_safe})")
+            else:
+                else_label_parts.append("(completion)")
+            else_label_parts.append("else")
+            # Add mode suffix
+            mode = _mode_suffix(t)
+            if mode:
+                else_label_parts.append(mode)
+            else_label = " ".join(else_label_parts)
+            lines.append(
+                f"    {t.source} --> {else_target} : {else_label}"
+            )
+
+    return "\n".join(lines)