opencrbasic 1.0.0__tar.gz → 1.1.1__tar.gz

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opencrbasic
-Version: 1.0.0
+Version: 1.1.1
 Summary: Open-source re-implementation of the Campbell Scientific CRBasic pre-compilers (CR6, CR1000X, CR300, CR350)
 Project-URL: Repository, https://github.com/UtrechtUniversity/open-crbasic
 Author: Utrecht University
@@ -38,8 +38,8 @@ Status, measured against the real compilers: `PROGRESS.md`. Design and the v1.0
 ## Scope
 
 - **Gated profiles: CR6 and CR1000X.** On these, v1.0 gates the reference verdict in the relevant
-  area (the FirnMelt/GEUS instruction set and language constructs), the execution mode, and the
-  first error for realistic mistakes on relevant rules, measured on the FirnMelt programs, the 507
+  area (the station/GEUS instruction set and language constructs), the execution mode, and the
+  first error for realistic mistakes on relevant rules, measured on the station programs, the 507
   CRBasic help examples, the 66 GEUS programs, the saved fuzz replay and fresh `--relevant` fuzz
   seeds. The help examples and GEUS programs are not redistributed here; see
   [tests/corpus/README.md](tests/corpus/README.md) for running against local copies. One relevant-area false accept is known: a `Sub` name that is also another routine's
@@ -118,6 +118,22 @@ crbc [options] program [messagefile]
   --report FILE write a JSON report (reference verdict and diagnostics, check findings)
   --config FILE use this opencrbasic.toml (default: nearest ancestor of the program)
   --check CODE=SEVERITY   set a check severity (error|warning|info|off); repeatable
+  --expand FILE expand #Define/#Macro macros into FILE, then compile FILE instead
+```
+
+`#Define` and `#Macro` are an opencrbasic extension, not CRBasic: the reference compilers reject
+them. `--expand` writes plain CRBasic (definitions commented out, uses expanded inline) that
+`CR6Comp.exe` accepts and that is the file to send to the logger; write it next to the source so
+its `Include`s resolve. The language server expands them the same way, so the editor reports
+the expansion's diagnostics on the line of each use. Syntax and rules:
+[`macros.py`](src/opencrbasic/macros.py).
+
+```crbasic
+#Define LOGD(msg) DebugMsg = msg    ' release build: #Define LOGD(msg)
+#Macro LOGV(name, value)
+  DebugMsg = name & "=" & value
+  CallTable Debug
+#EndMacro
 ```
 
 Check configuration and the report schema: `docs/checker.md` "Check configuration and report file".
@@ -143,8 +159,7 @@ result.tables  # list of tdf.TdfTable (Status, DataTables, DataTableInfo, ConstT
 `parser.parse_file()` gives the syntax tree (`syntax.py`) for other tools.
 
 [openloggernet](https://github.com/UtrechtUniversity/open-loggernet) uses opencrbasic when
-`CR6COMP=opencrbasic` is set, and the FirnMelt station repository compiles every program with it in
-CI.
+`CR6COMP=opencrbasic` is set.
 
 ## Editor support
 

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/README.md

@@ -21,8 +21,8 @@ Status, measured against the real compilers: `PROGRESS.md`. Design and the v1.0
 ## Scope
 
 - **Gated profiles: CR6 and CR1000X.** On these, v1.0 gates the reference verdict in the relevant
-  area (the FirnMelt/GEUS instruction set and language constructs), the execution mode, and the
-  first error for realistic mistakes on relevant rules, measured on the FirnMelt programs, the 507
+  area (the station/GEUS instruction set and language constructs), the execution mode, and the
+  first error for realistic mistakes on relevant rules, measured on the station programs, the 507
   CRBasic help examples, the 66 GEUS programs, the saved fuzz replay and fresh `--relevant` fuzz
   seeds. The help examples and GEUS programs are not redistributed here; see
   [tests/corpus/README.md](tests/corpus/README.md) for running against local copies. One relevant-area false accept is known: a `Sub` name that is also another routine's
@@ -101,6 +101,22 @@ crbc [options] program [messagefile]
   --report FILE write a JSON report (reference verdict and diagnostics, check findings)
   --config FILE use this opencrbasic.toml (default: nearest ancestor of the program)
   --check CODE=SEVERITY   set a check severity (error|warning|info|off); repeatable
+  --expand FILE expand #Define/#Macro macros into FILE, then compile FILE instead
+```
+
+`#Define` and `#Macro` are an opencrbasic extension, not CRBasic: the reference compilers reject
+them. `--expand` writes plain CRBasic (definitions commented out, uses expanded inline) that
+`CR6Comp.exe` accepts and that is the file to send to the logger; write it next to the source so
+its `Include`s resolve. The language server expands them the same way, so the editor reports
+the expansion's diagnostics on the line of each use. Syntax and rules:
+[`macros.py`](src/opencrbasic/macros.py).
+
+```crbasic
+#Define LOGD(msg) DebugMsg = msg    ' release build: #Define LOGD(msg)
+#Macro LOGV(name, value)
+  DebugMsg = name & "=" & value
+  CallTable Debug
+#EndMacro
 ```
 
 Check configuration and the report schema: `docs/checker.md` "Check configuration and report file".
@@ -126,8 +142,7 @@ result.tables  # list of tdf.TdfTable (Status, DataTables, DataTableInfo, ConstT
 `parser.parse_file()` gives the syntax tree (`syntax.py`) for other tools.
 
 [openloggernet](https://github.com/UtrechtUniversity/open-loggernet) uses opencrbasic when
-`CR6COMP=opencrbasic` is set, and the FirnMelt station repository compiles every program with it in
-CI.
+`CR6COMP=opencrbasic` is set.
 
 ## Editor support
 

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opencrbasic"
-version = "1.0.0"
+version = "1.1.1"
 description = "Open-source re-implementation of the Campbell Scientific CRBasic pre-compilers (CR6, CR1000X, CR300, CR350)"
 readme = "README.md"
 license = "MIT"
@@ -31,7 +31,8 @@ crbc-lsp = "opencrbasic.lsp.server:main"
 # `uv sync` installs `dev` by default: the test runner and the reverse-engineering tools
 # (`tools/extract_tables.py`, `tools/message_catalog.py` read the exe with pefile), and pygls
 # so the suite can test the language server; pytest-xdist for parallel test runs (`-n`); pyrefly
-# checks the repository (`[tool.pyrefly]`); pre-commit runs ruff and pyrefly before each commit.
+# checks the repository (`[tool.pyrefly]`); pre-commit runs ruff and pyrefly before each commit;
+# openloggernet drives a logger for `tools/logger_oracle.py`.
 dev = [
     "pytest>=8",
     "pefile>=2024.8.26",
@@ -39,6 +40,7 @@ dev = [
     "pytest-xdist>=3.6",
     "pyrefly==1.3.1",
     "pre-commit>=4",
+    "openloggernet>=0.3.0",
 ]
 
 [build-system]

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/__init__.py

@@ -1,3 +1,3 @@
 """Open-source CRBasic (CR6) pre-compiler."""
 
-__version__ = "1.0.0"
+__version__ = "1.1.1"

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/analysis.py

@@ -14,7 +14,7 @@ from .compiler import compile_file
 from .sources import DiskSource, LimitedSource, OverlaySource, RecordingSource, SourceProvider
 
 API_VERSION = 2  # 2: findings, notices, config_error, AnalysisRequest.checks (M6)
-DOCS = "https://github.com/UtrechtUniversity/firnmelt-datalogger/blob/main/opencrbasic/"
+DOCS = "https://github.com/UtrechtUniversity/open-crbasic/blob/main/"
 
 
 def _no_overlays() -> Mapping[Path, bytes]:
@@ -120,6 +120,7 @@ def analyze(request: AnalysisRequest) -> AnalysisResult:
         warn_unused=request.warn_unused,
         source=recorder,
         signature=request.signature,
+        macros=True,
     )
     includes = getattr(result.program_ast, "include_paths", None) or {}
     lowered = {name.lower(): path for name, path in includes.items()}

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/__init__.py

@@ -953,10 +953,9 @@ def _check(program: S.Program, profile: Profile, diags: Diagnostics, result) ->
 
     if not diags.errors:
         # `When Main Sequence Scan %d is running, background calibration will be disabled.`:
-        # round 6, moved here from the unconditional `warnings.check_early` call above -- oracle-
-        # confirmed *not* ungated the way `_check_reachability`/`_check_fnotch` are, unlike this
-        # module's own docstring previously claimed for all of `check_early` (`checker/warnings.py`'s
-        # `check_background_calibration` docstring has the oracle evidence). Independent of
+        # oracle-confirmed *not* ungated the way `_check_reachability`/`_check_fnotch` are
+        # (`checker/warnings.py`'s `check_background_calibration` docstring has the oracle evidence).
+        # Independent of
         # `tables_hook`'s own availability, so called ahead of that guard rather than inside it.
         _run_pass(warnings.check_background_calibration, program, profile, diags, env)
         _run_pass(warnings.check_slow_scan_skips, program, profile, diags, env)

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/cr3xx.py

@@ -389,9 +389,8 @@ def check(program: S.Program, profile, diags: Diagnostics) -> None:
 # `acceptdatarecords_1.CR6`, `SerialOpen (COMC1,...)`'s `COMC1 is not defined.` taints every
 # following two-plus-argument instruction to end of file, `Scan`'s own `Sec` and
 # `AcceptDataRecords`'s own `32769`, despite that finding being **ungated** and thus, in this
-# project's own pass model, skipping tier B -- where the *previous*, narrower version of this
-# function lived -- entirely), this is no longer called from inside the `if not diags.errors:`
-# tier-B block the way `check_expr_cascade` was: `checker/__init__.py` now calls it once,
+# project's own pass model, skipping tier B entirely), this is not called from inside the
+# `if not diags.errors:` tier-B block: `checker/__init__.py` calls it once,
 # unconditionally, after every other diagnostic-producing pass has run, so it can see -- and rewrite
 # -- the complete, final diagnostic list regardless of which tier first tainted the file. It is
 # still a no-op when nothing in the file ever taints (no `_is_cascade_trigger` match and no
@@ -555,7 +554,7 @@ def check_too_many_cascade(program: S.Program, profile, diags: Diagnostics) -> N
     """CR300/CR350 only; a no-op on every other logger and when nothing in the file ever taints
     (see this module's comment above for the oracle evidence and the exact shape implemented).
     Called from `checker/__init__.py` once, unconditionally, after every other pass -- see that
-    comment for why this can no longer be tier-B-only the way `check_expr_cascade` was.
+    comment for why this cannot be tier-B-only.
     """
     if profile.name not in ("cr300", "cr350"):
         return

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/expressions.py

@@ -25,9 +25,8 @@ _TYPE_CODES_PATH = Path(__file__).resolve().parent.parent / "data" / "type_codes
 # separate function (`4`/`16`/`17`/`19` `FUN_004b5db0`, a different failure message). Restricting
 # to this explicit include-list (rather than excluding the handful of kinds known *not* to
 # resolve) is deliberate: the default for an unrecognised kind is "don't check", so a gap in this
-# list only under-reports, never falsely rejects (AGENTS.md's priority order); the `ConstTable`
-# regression this session found during development (`crbasic/Main.CR6`'s
-# `ConstTable(GlobalConfigTable)`, kind `expr_marker`) is the concrete case that shape of bug
+# list only under-reports, never falsely rejects; the station corpus's `Main.CR6`
+# `ConstTable(GlobalConfigTable)` (kind `expr_marker`) is the concrete case that shape of bug
 # looks like.
 _RESOLVED_KINDS = frozenset(
     {
@@ -74,8 +73,7 @@ _CONST_FAMILY_KINDS = frozenset({"const_expr", "const_expr_only", "datatype_kw"}
 # separate `FooBar is not defined.` / `BazQux is not defined.` lines on CR300/CR350, in the source
 # (left-to-right) order `_undefined_names` already walks in. Modelled below as a plain per-logger
 # branch on `profile.name` (both loggers in each pair share identical behaviour, oracle-confirmed
-# side by side) rather than a new `Profile` field, to keep this session's change inside
-# `checker/expressions.py`/`checker/symbols.py` (`PLAN.md`'s ownership split).
+# side by side) rather than a new `Profile` field.
 _WHOLE_EXPR_ECHO_LOGGERS = frozenset({"cr6", "cr1000x"})
 
 # `NAN`/`INF` are accepted as predefined float constants on all four loggers (oracle-confirmed,

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/instr_data.py

@@ -45,13 +45,11 @@ from . import symbols
 # `docs/instructions.md`'s "not independently oracle-confirmed" list for exactly which those are.
 # One more call site exists (the unlabelled string `"Et"`, near the `SampleFieldCal` call site)
 # that could not be attributed to a specific instruction with confidence and is deliberately left
-# out -- AGENTS.md: never guess into a false reject. The other originally-unlabelled string this
-# round found nearby, `"FFT"`, *was* independently confirmed (a fresh scratch probe, `tfft.cr6`,
-# and two CHM corpus files whose `DataTable` bodies contain only `FFT(...)` calls, `fft_1.CR6`/
-# `covspa_1.CR6` -- both were a **false-reject regression** this round's own full difftest re-run
-# caught, from `check_table_structure`'s sibling `Table %s declared with no output fields.` rule
-# below not yet recognising `FFT` as a field producer, before `FFT` was added here too) and is
-# included as `FFT`.
+# out: never guess into a false reject. The other unlabelled string nearby, `"FFT"`, is
+# independently confirmed (a scratch probe, `tfft.cr6`, and two CHM corpus files whose
+# `DataTable` bodies contain only `FFT(...)` calls, `fft_1.CR6`/`covspa_1.CR6`, which compile
+# only when `FFT` also counts as a field producer for `Table %s declared with no output
+# fields.`) and is included as `FFT`.
 TABLE_ONLY_INSTRUCTIONS: dict[str, str] = {
     "CARDOUT": "CardOut",  # checked with the oracle
     "MQTTPUBLISHTABLE": "MQTTPublishTable",

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/instr_rules.py

@@ -1223,7 +1223,7 @@ def check_data_interval(program: S.Program, profile, diags: Diagnostics, env: co
       per-logger difference, not shared with CR300/CR350 (`_SCAN_VALUE_CHECK_LOGGERS`; found the
       same way as `check_scan_params`'s own CR300/CR350 gate, same session).
     - `DataTable interval %d uSec not integrally divisible by scan interval %d uSec.` (function
-      `FUN_004f6540`) -- project knowledge (`knowledge/crbasic/lessons.md` "`DataInterval` versus
+      `FUN_004f6540`) -- project knowledge (open-crbasic-skills `lessons.md` "`DataInterval` versus
       `Scan`": "a table interval must be at least the scan interval and an exact integer multiple
       of it", human-verified against `CR6Comp.exe`), reported at each `CallTable <name>` site whose
       table has a `DataInterval` and which sits directly inside a `Scan...NextScan` block (main

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/structure.py

@@ -2186,7 +2186,7 @@ def check_pass2(
     "Before `BeginProg`" only means the top level of the program, never a statement lexically
     inside a `Sub`/`Function` body (regardless of that body's own textual position, almost always
     before `BeginProg` itself, `docs/checker.md` "Pass model": found as a **regression** against
-    this repository's own `crbasic/Main.CR6` and several siblings, all of which call a built-in
+    the station corpus's `Main.CR6` and several siblings, all of which call a built-in
     function bare, with no `Call` keyword, e.g. `SerialOpen(...)` inside a `Function`/`Sub` defined
     above `BeginProg` -- perfectly ordinary CRBasic, since the body only executes when the
     `Sub`/`Function` is later called from inside `Scan`/`NextScan`, oracle-reconfirmed by re-running
@@ -5120,8 +5120,7 @@ def _check_array_dims(stmt: S.Declaration, diags: Diagnostics, env: consteval.En
     separate variables of the same declaration.
 
     A dimension that does not fold to a constant at all (`NotConstant`) is left alone: no oracle
-    evidence this session found supports guessing at that shape, and AGENTS.md's priority (never
-    reject an accepted program) rules out it.
+    evidence supports guessing at that shape, and a guess could reject an accepted program.
     """
     for index, v in enumerate(stmt.vars):
         before = len(diags.items)
@@ -5779,24 +5778,17 @@ def _check_alias_dims(
        check in this project) into a single **row-major flat offset** (`_alias_flat_offset`:
        `flat = i_n + sum_{k<n} (i_k - 1) * prod(d_{k+1..n})`, the ordinary multi-dimensional-array-
        as-flat-buffer formula, last index varying fastest) that must land in `[1,
-       prod(all declared dims)]`. Round 6's own original account of this check ("only the *first*
-       index is ever checked, however far out of range a later one is") is **superseded**: it was
-       built from two probes (`Public grid(3,3)`: `Alias grid(2,4) = Ts` compiles, `Alias grid(4,2)
-       = Ts` fails) that happen to *also* agree with the flat-offset formula purely by coincidence
-       (`(2-1)*3+4=7` and `(4-1)*3+2=11`, both landing on the correct side of `[1,9]` for unrelated
-       reasons) -- a fresh, wider oracle sweep this round (`docs/checker.md` "Round 7") found the
-       "first index alone" account is wrong in general: `Alias grid(4,-2) = Ts` (first index `4`,
-       out of `[1,3]` by the old account) **compiles clean** (`(4-1)*3+(-2)=7`, in `[1,9]`), while
-       `Alias grid(2,-1) = Ts` (a valid first index, an out-of-range *second* index by the old
-       account, which the old rule never checked at all) also compiles clean
-       (`(2-1)*3+(-1)=2`, in `[1,9]`) -- both correctly predicted by the flat formula, neither by
-       "only check position 0". A **scalar** (no declared dimensions at all) behaves exactly like a
+       prod(all declared dims)]`. Oracle evidence (`docs/checker.md` "Round 7"), for
+       `Public grid(3,3)`: `Alias grid(2,4) = Ts` compiles (`(2-1)*3+4=7`), `Alias grid(4,2) = Ts`
+       fails (`11`), and `Alias grid(4,-2) = Ts` (`7`) and `Alias grid(2,-1) = Ts` (`2`) both
+       compile clean: the first index is not checked on its own. A **scalar** (no declared
+       dimensions at all) behaves exactly like a
        size-1 array (`Public y` / `Alias y(1) = Ts` compiles, `Alias y(2) = Ts` fails: flat
        formula with `dims=(1,)` reduces to `flat=i1`, range `[1,1]`), which is why `declared_all_
        dims` maps every declared variable, not just array ones, the same convention `dim0_sizes`
        already used. Skipped (no check at all, under-reporting only) when any declared dimension or
        any index argument does not fold to a constant (`declared_all_dims`/the tuple-folding loop
-       below, both AGENTS.md-conservative the same way check 3 already was) or when the index
+       below, both conservative the same way check 3 is) or when the index
        tuple's own length does not match the variable's own declared dimension count (no oracle
        evidence gathered for that shape either way).
     3. **`Duplicate Alias`** (round 7; no trailing period, no echoed name): the source side's own

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/terminals.py

@@ -1,8 +1,8 @@
 """Per-logger analog-channel and port terminal model.
 
-Generalises the analog-channel range check (originally CR6-only, hard-coded `U1..U12`) across all
-four loggers, driven by oracle-probed per-logger data (`data/<logger>/terminals.json`; evidence,
-probes and the message-text differences: `docs/loggers.md`, `docs/instructions.md`).
+Models the analog-channel range check for all four loggers, driven by oracle-probed per-logger
+data (`data/<logger>/terminals.json`; evidence, probes and the message-text differences:
+`docs/loggers.md`, `docs/instructions.md`).
 
 Each logger's `terminals.json` names its own channel "kinds" -- CR6 has separate `u_terminal`
 (single-ended-shaped: any `U1..U12`, no oddness constraint; `ACPower`, `CS616`'s `CS616Chan`,

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/warnings.py

@@ -405,15 +405,10 @@ def check_background_calibration(program: S.Program, profile: Profile, diags: Di
     `Invalid symbol in expression` error present (`Delay never reached at run time.` alongside it,
     same probe file). A warning-only file (no errors, e.g. a reachability warning with no error
     anywhere) still gets *both* warnings together, confirming this is specifically errors, not "any
-    diagnostic", that gates it. Moved to `checker/__init__.py`'s own final `if not diags.errors:`
-    tier (alongside `warnings.check`/`tables_hook.attach`, the same "only on an otherwise-clean
-    compile" gate already used there) instead of `check_early`'s unconditional call site -- this is
-    the only change; the rule and message above are unchanged. Found as a side effect of developing
-    `instr_rules.check_scan_min_interval` (this round): dozens of pre-existing `false_accept`/
-    `message_diff` fuzz reproducers (`tests/corpus/fuzz/cr6/message_diff/ba333c2ee146.CR6` and
-    siblings) already showed this exact extra, spurious warning line alongside an unrelated real
-    error -- a genuine, previously-undocumented false-accept-shaped bug independent of this round's
-    own `Scan`-interval work, not a regression it introduced.
+    diagnostic", that gates it. It is therefore called from `checker/__init__.py`'s final
+    `if not diags.errors:` tier (alongside `warnings.check`/`tables_hook.attach`), not from
+    `check_early`'s unconditional call site. Fuzz reproducers such as
+    `tests/corpus/fuzz/cr6/message_diff/ba333c2ee146.CR6` cover the gate.
     """
     data = profile.background_calibration
     if not data:

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/checks.py

@@ -147,7 +147,7 @@ def _ambiguous_names(program: S.Program) -> set[str]:
 def _numeric_concatenation(program: S.Program, profile) -> list[Finding]:
     """OCB002: a String `+` (or `&`) assigned to a numeric variable (`L = 2000 + Mid(S,5,2)`). The
     reference accepts it, but `+` with a String operand concatenates, and the variable receives
-    the converted text: a GPS clock set this way read 2057 (`knowledge/crbasic/lessons.md` "`+` with
+    the converted text: a GPS clock set this way read 2057 (open-crbasic-skills `lessons.md` "`+` with
     a string operand concatenates", hardware 2026-10-22). Only a chain mixing numeric and String
     operands is reported: a String alone (`X = Mid(...)`) is a plain conversion, and Strings joined
     into a number's text (`X = HexStr(6) + "." + HexStr(7)`, GEUS programs) are deliberate."""
@@ -263,8 +263,8 @@ def _zero_divisors(program: S.Program, profile) -> list[Finding]:
 
 def _unsized_string_parameters(program: S.Program, profile) -> list[Finding]:
     """OCB005: a `Sub`/`Function` String parameter without `* size`. It holds 23 characters (24
-    bytes with the terminator) and a longer argument is cut (hardware, `knowledge/crbasic/
-    lessons.md` "Default string parameter size"). Information only: a short argument is fine."""
+    bytes with the terminator) and a longer argument is cut (hardware, open-crbasic-skills
+    `lessons.md` "Default string parameter size"). Information only: a short argument is fine."""
     return [
         Finding(
             "OCB005",
@@ -284,7 +284,7 @@ def _unsized_string_parameters(program: S.Program, profile) -> list[Finding]:
 def _unaligned_intervals(program: S.Program, profile) -> list[Finding]:
     """OCB006: a constant `DataInterval` that divides neither an hour nor a day (`7 Min`, `25 Hr`).
     Its records are phased from the start hour and may not align with midnight (hardware,
-    `knowledge/crbasic/lessons.md` "`DataInterval` phase"). Information only; an interval of 0
+    open-crbasic-skills `lessons.md` "`DataInterval` phase"). Information only; an interval of 0
     (every call) is not reported."""
     env, out = _const_env(program, profile), []
     for st in _statements(program):

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/cli.py

@@ -11,7 +11,8 @@ accepted (matching the exe's own option set) but has no implemented effect: orac
 have none observable from the CLI either. Extra long options: --logger
 {cr6,cr1000x,cr300,cr350} (default: from the file extension, else cr6) and --no-message-file (do
 not write the message file), --strict (opencrbasic checks, `checks.py`, on stderr only), --report FILE
-(JSON report, `docs/checker.md` "Check configuration and report file"), --config FILE and
+(JSON report, `docs/checker.md` "Check configuration and report file"), --expand FILE (expand
+`#Define`/`#Macro` macros into FILE and compile FILE instead, `macros.py`), --config FILE and
 --check CODE=SEVERITY (check configuration; both only act together with --strict or --report).
 Output goes to stdout and to the message file (`<LOGGER>cmple.xxx` by default, e.g. CR6cmple.xxx;
 CRLF line endings);
@@ -47,6 +48,7 @@ class _Options(TypedDict):
     strict: bool
     report: str | None
     config: str | None
+    expand: str | None
     check: list[str]
 
 
@@ -68,6 +70,7 @@ def _parse(argv: list[str]) -> tuple[_Options, list[str]]:
         "strict": False,
         "report": None,
         "config": None,
+        "expand": None,
         "check": [],
     }
     positional: list[str] = []
@@ -75,10 +78,10 @@ def _parse(argv: list[str]) -> tuple[_Options, list[str]]:
     while i < len(argv):
         arg = argv[i]
         if arg.startswith("--"):
-            if arg in ("--logger", "--report", "--config", "--check"):
+            if arg in ("--logger", "--report", "--config", "--expand", "--check"):
                 value = argv[i + 1] if i + 1 < len(argv) else ""
                 i += 2
-            elif arg.split("=", 1)[0] in ("--logger", "--report", "--config", "--check"):
+            elif arg.split("=", 1)[0] in ("--logger", "--report", "--config", "--expand", "--check"):
                 arg, value = arg.split("=", 1)
                 i += 1
             else:
@@ -87,7 +90,7 @@ def _parse(argv: list[str]) -> tuple[_Options, list[str]]:
                 if arg == "--check":
                     opts["check"].append(value)
                 else:
-                    opts[cast(Literal["logger", "report", "config"], arg[2:])] = value  # noqa: F821 -- ruff reads the Literal strings as names
+                    opts[cast(Literal["logger", "report", "config", "expand"], arg[2:])] = value  # noqa: F821 -- ruff reads the Literal strings as names
                 continue
             if arg == "--no-message-file":
                 opts["message_file"] = False
@@ -139,7 +142,7 @@ def _message_bytes(lines: list[str]) -> bytes:
     """`lines` joined the way the message file actually wants them: CRLF throughout, except the
     blank line straight after a `-- Compile Failed!` header, which the real exe writes as a bare
     LF (oracle-confirmed on both a plain failing compile and a `-t`/`-b` one, `docs/cli.md`
-    "Message file layout" -- previously assumed to be a uniform CRLF join, which this replaces).
+    "Message file layout").
     """
     if len(lines) >= 2 and lines[1] == "" and lines[0].endswith("Failed!"):
         return (lines[0] + "\r\n\n" + "\r\n".join(lines[2:]) + "\r\n").encode("latin-1", "replace")
@@ -254,6 +257,20 @@ def main(argv: list[str] | None = None) -> int:
             _write_report(opts["report"], checks.missing_program_report(program.name, profile.name, opts["strict"]))
         return 1
 
+    if opts["expand"]:
+        from . import macros
+
+        try:
+            expanded = macros.expand(program.read_bytes().decode("latin-1"))
+        except macros.MacroError as e:
+            lines = [f"{positional[0]} -- Compile Failed!", "", f"line {e.line}: {e}"]
+            print("\n".join(lines))
+            if opts["message_file"]:
+                _write_message_file(message_path, lines)
+            return 1
+        program = Path(opts["expand"])
+        program.write_bytes(expanded.encode("latin-1", "replace"))
+
     result = compile_file(program, profile, display_name=program.name, warn_unused=opts["u"], provenance=False)
     if opts["p"]:
         from . import preprocess

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/compiler.py

@@ -156,7 +156,7 @@ class CompileResult:
         # no-line `-u` warning, regardless of which included file declared it, prints before every
         # "table declared but never called" warning). `_no_line_kind` below reproduces that
         # ordering by message shape rather than by which module raised it, so this stays correct
-        # without `checker/warnings.py` (a concurrently-owned module) needing to tag its own
+        # without `checker/warnings.py` needing to tag its own
         # diagnostics; a stable sort keeps each kind's own relative (insertion) order within itself.
         # On one line the reachability warning follows that line's errors (oracle: 15 of 15 corpus
         # and fuzz transcripts); other warnings keep their check order.
@@ -200,9 +200,12 @@ def compile_file(
     source: SourceProvider | None = None,
     signature: bool = True,
     provenance: bool = True,
+    macros: bool = False,
 ) -> CompileResult:
     """`provenance=False` (the CLI and the tools) skips the position data only the language server
     reads (`LogicalLine.pieces`, `Program.line_map`, `Stmt.origin`); the compile output is unchanged.
+    `macros=True` (the language server) expands the entry file's `#Define`/`#Macro` macros
+    (`macros.py`), which the reference rejects.
 
     Never lets an unexpected exception escape (`docs/checker.md` "Robustness"): the real
     compiler never crashes on a syntactically-loadable file, so an internal bug in this project
@@ -215,7 +218,7 @@ def compile_file(
     """
     profile = profile or profiles.for_file(path)
     name = display_name or path.name
-    result = _compile_once(path, profile, name, None, source, provenance)
+    result = _compile_once(path, profile, name, None, source, provenance, macros)
     if profile.single_pass:
         # CR300/CR350 stop pulling a `Public`/`Dim` initializer's next line once any error has been
         # reported ahead of the declaration (oracle, 2026-10-10, `docs/checker.md` "Round 8"): re-run
@@ -233,7 +236,7 @@ def compile_file(
             if bad is None or (limit is not None and bad >= limit):
                 break
             limit = bad
-            result = _compile_once(path, profile, name, limit, source, provenance)
+            result = _compile_once(path, profile, name, limit, source, provenance, macros)
     if result.program_ast is None:
         return result
     return _finish(result, path, warn_unused, source, signature)
@@ -246,12 +249,13 @@ def _compile_once(
     pull_limit: tuple[int, ...] | None,
     source: SourceProvider | None = None,
     provenance: bool = True,
+    macros: bool = False,
 ):
     from . import checker, parser
 
     try:
         program, diags = parser.parse_file(
-            path, profile=profile, pull_limit=pull_limit, source=source, provenance=provenance
+            path, profile=profile, pull_limit=pull_limit, source=source, provenance=provenance, macros=macros
         )
     except Exception as exc:
         diags = Diagnostics()

opencrbasic-1.1.1/src/opencrbasic/macros.py

@@ -0,0 +1,161 @@
+"""`crbc --expand FILE`: opencrbasic's own macro step, not a reference-compiler feature.
+
+The reference compilers reject `#Define` (`Unknown instruction`), so a program that uses macros is
+expanded first into plain CRBasic, which any compiler (`crbc`, `CR6Comp.exe`) accepts and which is
+the file to send to the logger. Macros expand inline, so they cost no call depth (the logger runs at
+most four nested `Sub`/`Function` calls).
+
+    #Define DEBUG 1                         object-like, one line
+    #Define LOGD(msg) DebugMsg = msg        function-like, one line (an empty body is allowed)
+    #Macro LOGV(name, value)                function-like, several lines
+      DebugMsg = name & "=" & value
+      CallTable Debug
+    #EndMacro
+
+- Names and parameters are case-insensitive, like CRBasic. A function-like name not followed by
+  `(` is left alone; a macro is defined from its line on and cannot be redefined.
+- Nothing inside a `"..."` string or a `'` comment is expanded. A one-line body loses its
+  trailing comment.
+- A macro body is expanded again after substitution, without expanding itself (no recursion).
+- Every other line, `#If` and the other reference directives included, is kept as written apart
+  from the expansion of macro names; the definition lines become comments so line numbers before
+  the first multi-line expansion stay the same. The lines of a multi-line expansion take the
+  indentation of the line that uses it.
+- A macro call must close on its own line. Macros in `Include` files are not read or expanded.
+- The language server expands macros the same way while analysing (`source.py`, the entry file
+  only), so a program with macros gets the diagnostics of its expansion, each on the line of the
+  macro use. `crbc` without `--expand` compiles like the reference and rejects `#Define`.
+"""
+
+import re
+import textwrap
+
+_DEFINE_RE = re.compile(r"^\s*#\s*(Define|Macro)\s+([A-Za-z_]\w*)(?:\(([^)]*)\))?(.*)$", re.IGNORECASE)
+_END_RE = re.compile(r"^\s*#\s*EndMacro\b", re.IGNORECASE)
+# strings and comments are copied whole; a number or `&H`/`&B` literal is never a name
+_TOKEN_RE = re.compile(r'"[^"\n]*"?|\'[^\n]*|\d\w*|&[HhBb]\w*|[A-Za-z_]\w*|.', re.DOTALL)
+
+
+class MacroError(Exception):
+    def __init__(self, line: int, message: str):
+        super().__init__(message)
+        self.line = line
+
+
+class _Macro:
+    __slots__ = ("params", "body")
+
+    def __init__(self, params: list[str] | None, body: str):
+        self.params = params  # None: object-like
+        self.body = body
+
+
+def _strip_comment(text: str) -> str:
+    return "".join(t for t in _TOKEN_RE.findall(text) if not t.startswith("'"))
+
+
+def _call_args(text: str, i: int, line: int, name: str) -> tuple[list[str], int]:
+    """The arguments of the call whose `(` is at `text[i]`, and the index after its `)`."""
+    args, current, depth = [], [], 0
+    for m in _TOKEN_RE.finditer(text, i + 1):
+        tok = m.group()
+        if tok == "\n":
+            break
+        if tok == ")" and depth == 0:
+            args.append("".join(current).strip())
+            return ([] if args == [""] else args), m.end()
+        if tok == "," and depth == 0:
+            args.append("".join(current).strip())
+            current = []
+            continue
+        depth += {"(": 1, ")": -1}.get(tok, 0)
+        current.append(tok)
+    raise MacroError(line, f"Macro {name}: missing ).")
+
+
+def _expand(text: str, macros: dict[str, _Macro], line: int, disabled: frozenset[str] = frozenset()) -> str:
+    out: list[str] = []
+    i = 0
+    while m := _TOKEN_RE.match(text, i):
+        tok, i = m.group(), m.end()
+        key = tok.upper()
+        macro = macros.get(key)
+        if macro is None or key in disabled:
+            out.append(tok)
+            continue
+        body = macro.body
+        if macro.params is not None:
+            j = i
+            while j < len(text) and text[j] in " \t":
+                j += 1
+            if j >= len(text) or text[j] != "(":
+                out.append(tok)
+                continue
+            args, i = _call_args(text, j, line, tok)
+            if len(args) != len(macro.params):
+                raise MacroError(line, f"Macro {tok} takes {len(macro.params)} argument(s), got {len(args)}.")
+            values = dict(zip(macro.params, args, strict=True))
+            body = "".join(values.get(t.upper(), t) for t in _TOKEN_RE.findall(body))
+        body = _expand(body, macros, line, disabled | {key})
+        head = text[text.rfind("\n", 0, m.start()) + 1 : m.start()]
+        indent = head[: len(head) - len(head.lstrip(" \t"))]
+        out.append(body.replace("\n", "\n" + indent))
+    return "".join(out)
+
+
+class Macros:
+    """The macros of one file, fed its lines in order (`expand` here, the loader for the editor)."""
+
+    def __init__(self):
+        self.table: dict[str, _Macro] = {}
+        self._open: tuple[str, list[str] | None, int, list[str]] | None = None  # a #Macro being read
+
+    def feed(self, text: str, line: int) -> str | None:
+        """`text` with macros expanded, or None when it is part of a definition."""
+        if self._open is not None:
+            if _END_RE.match(text):
+                name, params, start, body = self._open
+                self._open = None
+                self._define(name, params, textwrap.dedent("\n".join(body)).strip("\n"), start)
+            else:
+                self._open[3].append(text)
+            return None
+        d = _DEFINE_RE.match(text)
+        if d is None:
+            return _expand(text, self.table, line)
+        kind, name, rest = d.group(1).upper(), d.group(2), d.group(4)
+        params = None if d.group(3) is None else [p.strip().upper() for p in d.group(3).split(",")]
+        if params == [""]:
+            params = []
+        if params is not None and (
+            not all(re.fullmatch(r"[A-Za-z_]\w*", p) for p in params) or len(set(params)) < len(params)
+        ):
+            raise MacroError(line, f"Macro {name}: invalid parameter list.")
+        if kind == "MACRO":
+            if params is None or _strip_comment(rest).strip():
+                raise MacroError(line, f"#Macro {name} needs a (parameter list) and its body on the following lines.")
+            self._open = (name, params, line, [])
+        else:
+            self._define(name, params, _strip_comment(rest).strip(), line)
+        return None
+
+    def finish(self) -> None:
+        if self._open is not None:
+            raise MacroError(self._open[2], f"#Macro {self._open[0]} without #EndMacro.")
+
+    def _define(self, name: str, params: list[str] | None, body: str, line: int) -> None:
+        if name.upper() in self.table:
+            raise MacroError(line, f"Macro {name} is already defined.")
+        self.table[name.upper()] = _Macro(params, body)
+
+
+def expand(text: str) -> str:
+    """`text` with its `#Define`/`#Macro` definitions commented out and their uses expanded."""
+    newline = "\r\n" if "\r\n" in text else "\n"
+    macros = Macros()
+    out = []
+    for n, raw in enumerate(text.splitlines(), 1):
+        expanded = macros.feed(raw, n)
+        out.append("'" + raw if expanded is None else expanded.replace("\n", newline))
+    macros.finish()
+    return newline.join(out) + (newline if text.endswith(("\n", "\r")) else "")

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/parser.py

@@ -3174,6 +3174,7 @@ def parse_file(
     pull_limit: tuple[int, ...] | None = None,
     source: SourceProvider | None = None,
     provenance: bool = True,
+    macros: bool = False,
 ) -> tuple[S.Program, Diagnostics]:
     """`provenance=False` skips the pieces/line-map/origin data only the language server reads (the CLI
     path); everything the checker sees is unchanged. `profile` is normally left to the file's own extension (`profiles.for_file`, the historical
@@ -3191,6 +3192,7 @@ def parse_file(
         _CR3XX_INCLUDE_EXTS.get((profile or _profile_for(path.name)).name),
         source,
         provenance,
+        macros,
     )
     pull_log = diags.pull_log
     parser = _Parser(profile or _profile_for(path.name), diags, provenance)

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/src/opencrbasic/source.py

@@ -29,6 +29,7 @@ from pathlib import Path
 from typing import NamedTuple
 
 from .diagnostics import Diagnostics
+from .macros import MacroError, Macros
 from .sources import DiskSource, SourceProvider
 
 _INCLUDE_RE = re.compile(r'^\s*Include\s*\(?\s*"([^"]*)"\s*\)?\s*$', re.IGNORECASE)
@@ -302,7 +303,9 @@ class _Loader:
         cr3xx_exts: tuple[str, ...] | None = None,
         source: SourceProvider | None = None,
         provenance: bool = True,
+        macros: bool = False,
     ):
+        self.macros = Macros() if macros else None  # the entry file's macros (`macros.py`)
         self.provenance = provenance  # False: skip `LogicalLine.pieces` (only the language server reads them)
         self.source = source or DiskSource()
         self.includes: dict[str, Path] = {}  # include display name -> the path it resolved to
@@ -416,6 +419,22 @@ class _Loader:
             if text.strip() == "":
                 i += 1
                 continue
+            if self.macros is not None and occ == 0:
+                try:
+                    expanded = self.macros.feed(text, start_line)
+                except MacroError as e:
+                    self.diags.error(e.line, str(e), filename)
+                    expanded = None
+                if expanded != text:
+                    # an expansion is reported, and spans, where the macro is used; no `pieces`
+                    for part in (expanded or "").split("\n"):
+                        if part.strip():
+                            phys = (start_line, i + 1)
+                            out.append(
+                                LogicalLine(part, last_line - shift, filename, section, phys=phys, occurrence=occ)
+                            )
+                    i += 1
+                    continue
             pulls, bad = 0, None
             orig = text
             orig_pieces = pieces
@@ -570,13 +589,19 @@ def load_program(
     cr3xx_exts: tuple[str, ...] | None = None,
     source: SourceProvider | None = None,
     provenance: bool = True,
+    macros: bool = False,
 ) -> tuple[list[LogicalLine], Diagnostics]:
     """Load `path` and every file it `Include`s/`IncludeSection`s, as one logical-line stream."""
     path = Path(path)
     diags = Diagnostics()
-    loader = _Loader(path.parent, diags, own_ext, pull_init, cr3xx_exts, source, provenance)
+    loader = _Loader(path.parent, diags, own_ext, pull_init, cr3xx_exts, source, provenance, macros)
     loader.pull_limit = pull_limit
     lines = loader.load_file(path, section=None, in_include=False)
+    try:
+        if loader.macros is not None:
+            loader.macros.finish()
+    except MacroError as e:
+        diags.error(e.line, str(e), path.name)
     diags.pull_log = loader.pull_log
     diags.pull_site = loader.site
     diags.include_paths = loader.includes

{opencrbasic-1.0.0 → opencrbasic-1.1.1}/tests/corpus/README.md

@@ -1,21 +1,21 @@
-# Test corpora
-
-| Directory | Contents | In git |
-|---|---|---|
-| `firnmelt/` | The FirnMelt station programs and libraries, a snapshot of `crbasic/` in [firnmelt-station](https://github.com/UtrechtUniversity/firnmelt-station) at monorepo commit `bd4c30c1` (2026-11-01). Tests pin results to these exact files, so refresh them only together with the expectations. | yes |
-| `fuzz/` | Saved fuzz reproducers seeded from `firnmelt/`, replayed by `tools/fuzz_replay.py`. | yes |
-| `chm/` | The 507 complete example programs in Campbell's CRBasic help. | no |
-| `../../examples/Logger Programs/` | The 66 GEUS station programs used as a CR1000X corpus. | no |
-
-The help examples and GEUS programs belong to others and are not redistributed
-([docs/legal.md](../../docs/legal.md)). Tests that need them skip when they are absent. To run
-those tests locally:
-
-1. Extract the CRBasic help (the `.chm` installed with CRBasic Editor) into `extracted_chm/` at the
-   repository root, for example with `7z x CRBasic.chm -oextracted_chm`.
-2. `uv run python tools/extract_chm_examples.py` writes `tests/corpus/chm/`.
-3. Put the GEUS programs, if you have them, in `examples/Logger Programs/`.
-4. For the differential tools, copy the Campbell compilers into `compiler/` (README, "How it was
-   built").
-
-All of these paths are git-ignored.
+# Test corpora
+
+| Directory | Contents | In git |
+|---|---|---|
+| `station/` | A field station's CR6 programs and libraries (2026-11-01 snapshot). Tests pin results to these exact files, so refresh them only together with the expectations. | yes |
+| `fuzz/` | Saved fuzz reproducers seeded from `station/`, replayed by `tools/fuzz_replay.py`. | yes |
+| `chm/` | The 507 complete example programs in Campbell's CRBasic help. | no |
+| `../../examples/Logger Programs/` | The 66 GEUS station programs used as a CR1000X corpus. | no |
+
+The help examples and GEUS programs belong to others and are not redistributed
+([docs/legal.md](../../docs/legal.md)). Tests that need them skip when they are absent. To run
+those tests locally:
+
+1. Extract the CRBasic help (the `.chm` installed with CRBasic Editor) into `extracted_chm/` at the
+   repository root, for example with `7z x CRBasic.chm -oextracted_chm`.
+2. `uv run python tools/extract_chm_examples.py` writes `tests/corpus/chm/`.
+3. Put the GEUS programs, if you have them, in `examples/Logger Programs/`.
+4. For the differential tools, copy the Campbell compilers into `compiler/` (README, "How it was
+   built").
+
+All of these paths are git-ignored.