qubasic 0.1.0__py3-none-any.whl

qbasic_core/subs.py

@@ -0,0 +1,261 @@
+"""QBASIC SUB/FUNCTION — proper subroutines with local scope."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from qbasic_core.engine import (
+    ExecResult, ExecOutcome,
+    RE_SUB, RE_END_SUB, RE_FUNCTION, RE_END_FUNCTION,
+    RE_CALL, RE_LOCAL, RE_STATIC_DECL, RE_SHARED,
+)
+from qbasic_core.exec_context import ExecContext
+
+
+class SubroutineMixin:
+    """SUB/FUNCTION subroutines with LOCAL, STATIC, SHARED scoping.
+
+    Requires: TerminalProtocol — uses self.program, self.variables,
+    self._eval_with_vars(), self.eval_expr().
+    """
+
+    def _init_subs(self) -> None:
+        self._sub_defs: dict[str, dict[str, Any]] = {}
+        self._func_defs: dict[str, dict[str, Any]] = {}
+        self._scope_stack: list[dict[str, Any]] = []
+        self._static_vars: dict[str, dict[str, Any]] = {'_GLOBAL': {}}
+        self._call_stack: list[dict[str, Any]] = []
+
+    def _scan_subs(self, sorted_lines: list[int]) -> None:
+        """Scan program for SUB and FUNCTION blocks before execution."""
+        self._sub_defs.clear()
+        self._func_defs.clear()
+        for i, ln in enumerate(sorted_lines):
+            stmt = self.program[ln].strip()
+            m = RE_SUB.match(stmt)
+            if m:
+                name = m.group(1).upper()
+                params = [p.strip() for p in m.group(2).split(',')] if m.group(2) else []
+                end_ip = self._find_end_block(sorted_lines, i, 'SUB')
+                self._sub_defs[name] = {'params': params, 'start_ip': i + 1, 'end_ip': end_ip}
+                continue
+            m = RE_FUNCTION.match(stmt)
+            if m:
+                name = m.group(1).upper()
+                params = [p.strip() for p in m.group(2).split(',')] if m.group(2) else []
+                end_ip = self._find_end_block(sorted_lines, i, 'FUNCTION')
+                self._func_defs[name] = {'params': params, 'start_ip': i + 1, 'end_ip': end_ip}
+
+    def _find_end_block(self, sorted_lines: list[int], start_ip: int, kind: str) -> int:
+        scan = start_ip + 1
+        end_re = RE_END_SUB if kind == 'SUB' else RE_END_FUNCTION
+        while scan < len(sorted_lines):
+            s = self.program[sorted_lines[scan]].strip()
+            if end_re.match(s):
+                return scan
+            scan += 1
+        ln = sorted_lines[start_ip]
+        raise RuntimeError(f"{kind} at line {ln} has no END {kind}")
+
+    # ── Control flow handlers ──────────────────────────────────────────
+
+    def _cf_sub(self, stmt: str, sorted_lines: list[int], ip: int, *, parsed=None) -> tuple[bool, ExecOutcome] | None:
+        """SUB — skip the block during normal execution."""
+        if parsed is not None:
+            name = parsed.name
+        else:
+            m = RE_SUB.match(stmt)
+            if not m:
+                return None
+            name = m.group(1).upper()
+        if name in self._sub_defs:
+            return True, self._sub_defs[name]['end_ip'] + 1
+        return True, ExecResult.ADVANCE
+
+    def _cf_end_sub(self, stmt: str, *, parsed=None) -> tuple[bool, ExecOutcome] | None:
+        if parsed is None and not RE_END_SUB.match(stmt):
+            return None
+        if self._call_stack:
+            frame = self._call_stack.pop()
+            self._pop_scope(frame)
+            return True, frame['return_ip']
+        return True, ExecResult.ADVANCE
+
+    def _cf_function(self, stmt: str, sorted_lines: list[int], ip: int, *, parsed=None) -> tuple[bool, ExecOutcome] | None:
+        """FUNCTION — skip the block during normal execution."""
+        if parsed is not None:
+            name = parsed.name
+        else:
+            m = RE_FUNCTION.match(stmt)
+            if not m:
+                return None
+            name = m.group(1).upper()
+        if name in self._func_defs:
+            return True, self._func_defs[name]['end_ip'] + 1
+        return True, ExecResult.ADVANCE
+
+    def _cf_end_function(self, stmt: str, *, parsed=None) -> tuple[bool, ExecOutcome] | None:
+        if parsed is None and not RE_END_FUNCTION.match(stmt):
+            return None
+        if self._call_stack:
+            frame = self._call_stack.pop()
+            func_name = frame.get('func_name', '')
+            ret_val = self.variables.get(func_name, 0) if func_name else 0
+            self._pop_scope(frame)
+            if func_name:
+                self.variables['_FUNC_RETURN'] = ret_val
+            return True, frame['return_ip']
+        return True, ExecResult.ADVANCE
+
+    def _cf_call(self, stmt: str, run_vars: dict[str, Any],
+                 sorted_lines: list[int], ip: int, *, parsed=None) -> tuple[bool, ExecOutcome] | None:
+        if parsed is not None:
+            name = parsed.name
+            arg_str = parsed.args
+        else:
+            m = RE_CALL.match(stmt)
+            if not m:
+                return None
+            name = m.group(1).upper()
+            arg_str = m.group(2) or ''
+        args = [self._eval_with_vars(a.strip(), run_vars)
+                for a in arg_str.split(',') if a.strip()] if arg_str.strip() else []
+        if name not in self._sub_defs:
+            raise RuntimeError(f"UNDEFINED SUB: {name}")
+        sub = self._sub_defs[name]
+        self._push_scope()
+        # Bind parameters
+        for i, pname in enumerate(sub['params']):
+            val = args[i] if i < len(args) else 0
+            self.variables[pname] = val
+        # Restore STATIC vars
+        if name in self._static_vars:
+            for k, v in self._static_vars[name].items():
+                self.variables[k] = v
+        self._call_stack.append({'return_ip': ip + 1, 'sub_name': name})
+        return True, sub['start_ip']
+
+    def _invoke_function(self, name: str, args: list[float],
+                         sorted_lines: list[int]) -> Any:
+        """Execute a FUNCTION block and return its value.
+        Called from the expression evaluator.
+        Uses _exec_control_flow for full statement support inside function bodies."""
+        uname = name.upper()
+        if uname not in self._func_defs:
+            raise ValueError(f"UNDEFINED FUNCTION: {name}")
+        func = self._func_defs[uname]
+        self._push_scope()
+        for i, pname in enumerate(func['params']):
+            self.variables[pname] = args[i] if i < len(args) else 0
+        self.variables[uname] = 0  # return variable
+        if uname in self._static_vars:
+            for k, v in self._static_vars[uname].items():
+                self.variables[k] = v
+        ctx = ExecContext(
+            sorted_lines=sorted_lines,
+            ip=func['start_ip'],
+            run_vars=dict(self.variables),
+            loop_stack=[],
+            max_iterations=self._max_iterations,
+        )
+        while ctx.ip <= func['end_ip']:
+            ctx.iteration_count += 1
+            if ctx.iteration_count > ctx.max_iterations:
+                raise RuntimeError("FUNCTION LOOP LIMIT")
+            stmt = self.program[sorted_lines[ctx.ip]].strip()
+            if RE_END_FUNCTION.match(stmt):
+                break
+            # Pre-parse once, pass to both the main call and the recurse callback
+            from qbasic_core.parser import parse_stmt
+            stmt_parsed = parse_stmt(stmt)
+            # Use full control-flow dispatch for all statement types
+            def _fn_recurse(s, ls, sl, i, rv):
+                handled, result = self._exec_control_flow(s, ls, sl, i, rv, _fn_recurse)
+                if handled:
+                    return result
+                return None
+            handled, result = self._exec_control_flow(
+                stmt, ctx.loop_stack, sorted_lines, ctx.ip, ctx.run_vars, _fn_recurse,
+                parsed=stmt_parsed)
+            if handled:
+                if isinstance(result, int):
+                    ctx.ip = result
+                    continue
+                elif result is ExecResult.END:
+                    break
+            ctx.ip += 1
+        ret_val = self.variables.get(uname, ctx.run_vars.get(uname, 0))
+        self._pop_scope()
+        return ret_val
+
+    # ── LOCAL / STATIC / SHARED ────────────────────────────────────────
+
+    def _cf_local(self, stmt: str, run_vars: dict[str, Any], *, parsed=None) -> tuple[bool, ExecOutcome] | None:
+        if parsed is not None:
+            var_list = parsed.var_list
+        else:
+            m = RE_LOCAL.match(stmt)
+            if not m:
+                return None
+            var_list = m.group(1)
+        for vname in var_list.split(','):
+            vname = vname.strip()
+            if vname:
+                run_vars[vname] = 0
+                self.variables[vname] = 0
+        return True, ExecResult.ADVANCE
+
+    def _cf_static(self, stmt: str, run_vars: dict[str, Any], *, parsed=None) -> tuple[bool, ExecOutcome] | None:
+        if parsed is not None:
+            var_list = parsed.var_list
+        else:
+            m = RE_STATIC_DECL.match(stmt)
+            if not m:
+                return None
+            var_list = m.group(1)
+        sub_name = self._call_stack[-1]['sub_name'] if self._call_stack else '_GLOBAL'
+        if sub_name not in self._static_vars:
+            self._static_vars[sub_name] = {}
+        for vname in var_list.split(','):
+            vname = vname.strip()
+            if vname:
+                val = self._static_vars[sub_name].get(vname, 0)
+                run_vars[vname] = val
+                self.variables[vname] = val
+        return True, ExecResult.ADVANCE
+
+    def _cf_shared(self, stmt: str, run_vars: dict[str, Any], *, parsed=None) -> tuple[bool, ExecOutcome] | None:
+        if parsed is not None:
+            var_list = parsed.var_list
+        else:
+            m = RE_SHARED.match(stmt)
+            if not m:
+                return None
+            var_list = m.group(1)
+        for vname in var_list.split(','):
+            vname = vname.strip()
+            if vname and self._scope_stack and vname in self._scope_stack[-1]:
+                run_vars[vname] = self._scope_stack[-1].get(vname, 0)
+                self.variables[vname] = run_vars[vname]
+        return True, ExecResult.ADVANCE
+
+    # ── Scope management ───────────────────────────────────────────────
+
+    def _push_scope(self) -> None:
+        self._scope_stack.append(dict(self.variables))
+
+    def _pop_scope(self, frame: dict[str, Any] | None = None) -> None:
+        # Save STATIC vars for the current frame before restoring outer scope.
+        # *frame* should be the already-popped call frame; if not provided,
+        # fall back to peeking at the call stack (legacy callers).
+        if frame is None and self._call_stack:
+            frame = self._call_stack[-1]
+        if frame is not None:
+            sub_name = frame.get('sub_name') or frame.get('func_name') or ''
+            if sub_name in self._static_vars:
+                for vname in list(self._static_vars[sub_name]):
+                    self._static_vars[sub_name][vname] = self.variables.get(vname, 0)
+        if self._scope_stack:
+            self.variables.clear()
+            self.variables.update(self._scope_stack.pop())

qbasic_core/sweep.py

@@ -0,0 +1,82 @@
+"""QBASIC sweep mixin — parameter sweep command."""
+
+from __future__ import annotations
+
+from qiskit import transpile
+from qiskit_aer import AerSimulator
+
+try:
+    import plotille as _plotille
+except ImportError:
+    _plotille = None
+
+
+class SweepMixin:
+    """Parameter sweep command for QBasicTerminal.
+
+    Requires: TerminalProtocol — uses self.variables, self.shots,
+    self.sim_method, self.sim_device, self._noise_model,
+    self.eval_expr(), self.build_circuit().
+    """
+
+    def cmd_sweep(self, rest: str) -> None:
+        """SWEEP var start end [steps] — run circuit for each parameter value.
+
+        When plotille is available, appends a braille line chart of the
+        top-state probability vs. the swept variable.
+        """
+        parts = rest.split()
+        if len(parts) < 3:
+            self.io.writeln("?USAGE: SWEEP <var> <start> <end> [steps]")
+            return
+        var = parts[0]
+        start = self.eval_expr(parts[1])
+        end = self.eval_expr(parts[2])
+        steps = int(parts[3]) if len(parts) > 3 else 10
+        if steps < 1:
+            self.io.writeln("?SWEEP needs at least 1 step")
+            return
+
+        self.io.writeln(f"\nSWEEP {var} from {start} to {end} in {steps} steps:")
+        if steps == 1:
+            values = [start]
+        else:
+            values = [start + (end - start) * i / (steps - 1) for i in range(steps)]
+        backend_opts = {'method': self.sim_method}
+        if self.sim_device == 'GPU':
+            backend_opts['device'] = 'GPU'
+        if self._noise_model:
+            backend_opts['noise_model'] = self._noise_model
+        backend = AerSimulator(**backend_opts)
+        sweep_xs: list[float] = []
+        sweep_ys: list[float] = []
+        for val in values:
+            self.variables[var] = val
+            try:
+                qc, has_measure = self.build_circuit()
+                if has_measure:
+                    qc.measure_all()
+                result = backend.run(transpile(qc, backend), shots=self.shots).result()
+                counts = dict(result.get_counts())
+                ranked = sorted(counts.items(), key=lambda x: -x[1])
+                top = ranked[0]
+                bar_len = int(30 * top[1] / self.shots)
+                top2 = f" |{ranked[1][0]}\u27E9={ranked[1][1]}" if len(ranked) > 1 else ""
+                n_unique = len(ranked)
+                self.io.writeln(f"  {var}={val:8.4f}  |{top[0]}\u27E9 {top[1]:>5}/{self.shots} "
+                               f"{'\u2588' * bar_len}{top2}  ({n_unique} states)")
+                sweep_xs.append(val)
+                sweep_ys.append(top[1] / self.shots)
+            except Exception as e:
+                self.io.writeln(f"  {var}={val:8.4f}  ERROR: {e}")
+
+        # Plotille chart of P(top state) vs variable
+        if _plotille is not None and len(sweep_xs) >= 2:
+            self.io.writeln('')
+            self.io.writeln(_plotille.plot(
+                sweep_xs, sweep_ys,
+                width=60, height=15,
+                X_label=var,
+                Y_label='P(top)',
+                lc='cyan'))
+        self.io.writeln('')