Skip to content

Readme.md

Latest commit

 

History

History
364 lines (279 loc) · 10.9 KB

Readme.md

File metadata and controls

364 lines (279 loc) · 10.9 KB

FROG logo

Reference CLI

Command-line surface for the non-normative FROG reference implementation
FROG — Free Open Graphical Language

Contents

1. Overview

This directory contains the command-line surface of the non-normative FROG reference implementation. Its role is to expose a small, explicit, stage-aware toolchain for the first executable vertical slices of FROG.

The CLI is not a language specification layer. It is a practical implementation-facing shell around the published:

  • source loading,
  • validation,
  • Execution IR derivation,
  • lowering,
  • backend contract emission,
  • and runtime execution path.

Its purpose is to make the first executable reference corridor observable and testable without collapsing the repository's architectural stages into one opaque command.

2. Status and Boundary

This directory is non-normative. It does not define:

  • the language,
  • the canonical source format,
  • the validated program meaning,
  • the open Execution IR,
  • the backend contract boundary,
  • or the runtime as a normative semantic owner.

Those remain owned by the published specification layers and by the non-CLI reference modules under Implementations/Reference/.

The CLI exists to make those published boundaries executable and inspectable. It must not become a hidden source of language truth.

3. Current Role

At the current stage of the repository, the CLI serves four practical purposes:

  • provide explicit stage entry points for the first executable slice,
  • make intermediate stage results observable during reference-implementation work,
  • support repeatable command-line execution of the minimal published example path,
  • and preserve attribution between the canonical .frog source and every intermediate artifact.

The CLI should therefore remain compact, explicit, and easy to audit before it expands to broader UI-oriented and state-oriented slices.

4. Current Campaign Priority

The current reference priority is the first complete executable vertical slice built around: 

Examples/05_bounded_ui_accumulator/main.frog

That slice is intentionally small but cross-layer complete. It combines:

  • front-panel declaration,
  • u16 numeric widgets,
  • widget_value participation,
  • widget_reference participation,
  • frog.ui.property_write on face_color,
  • one canonical for_loop structure,
  • explicit local memory through frog.core.delay,
  • one public output,
  • and one first runtime corridor.

The CLI must therefore prioritize that slice over older narrower regressions when command behavior and documentation are updated.

5. Command Surface

The reference command model is: 

frogc validate <file.frog>
frogc derive-ir <file.frog>
frogc lower <file.frog> [--backend-family <family_id>]
frogc emit-contract <file.frog> [--backend-family <family_id>]
frogc run <file.frog> [--backend-family <family_id>]

The exact user-facing surface may evolve, but the stage separation should remain explicit. The CLI should mirror the published architecture rather than collapsing multiple stages into one opaque tool behavior.

For the first executable corridor, the recommended backend-family identifier is: 

llvm_cpu_v1

This identifier is a backend-family contract target. It does not redefine FROG itself. LLVM remains downstream from FROG.

6. Relation with the Reference Pipeline

The CLI is the operational shell of the reference pipeline described under: 

Implementations/Reference/

Its commands should remain aligned with the stage boundaries used by the reference implementation:

  • validate — confirm that source belongs to the supported validated subset,
  • derive-ir — derive an open execution-facing representation with recoverable attribution,
  • lower — specialize the open IR for a selected backend family,
  • emit-contract — produce the handoff consumed by a backend or runtime,
  • run — execute through runtime-side contract consumption.

The CLI should make those stages visible. It should not silently bypass them while still claiming to represent the full pipeline.

7. Current Entry Points

A compact demonstration entry point may exist in this directory for early executable slices. That is acceptable as long as it remains explicitly non-normative and does not blur ownership of the stages.

In the current reference direction, the practical CLI entry point may be: 

frog_demo_pipeline.py

while the implementation logic progressively lives in specialized modules under: 

Implementations/Reference/
├── Loader/
├── Validator/
├── Deriver/
├── Lowerer/
├── ContractEmitter/
└── Runtime/

This is the preferred direction because it preserves a simple command-line surface without turning one convenience script into accidental architecture.

8. Backend-Family Posture

The CLI may expose backend-family selection through: 

--backend-family <family_id>

For the first complete executable slice, two postures are useful:

  • DEFAULT_BACKEND_FAMILY — the conservative internal reference family used by the current Python demo path,
  • llvm_cpu_v1 — the first explicit LLVM-oriented backend-family contract target.

The CLI must preserve the following distinction: 

FROG source / validation / open IR
    !=
backend family
    !=
runtime-private realization

A command such as: 

frogc emit-contract Examples/05_bounded_ui_accumulator/main.frog --backend-family llvm_cpu_v1

means:

  • derive a backend-facing contract suitable for an LLVM-oriented consumer family,
  • not redefine the language in LLVM terms,
  • and not erase the open FROG pipeline stages that come before backend handoff.

9. Design Rules

  • Commands should reflect published architectural boundaries.
  • Commands should fail explicitly rather than silently skipping invalid stages.
  • Intermediate artifacts should remain observable.
  • The CLI should remain stage-aware rather than pretending one monolithic command is the architecture.
  • The CLI should remain small enough to audit.
  • Example-specific shortcuts, if any, must remain explicit and non-normative.
  • Backend-family choice must remain explicit when it matters.
  • Front-panel presentation metadata may be preserved in artifacts, but must remain distinguished from executable semantic surfaces.

10. Relation with Examples and Stage Results

The CLI exists partly to make stage results inspectable against named examples. That means a user should be able to run one published example and inspect at least:

  • the validation result,
  • the derived Execution IR,
  • the lowered form,
  • the emitted backend contract,
  • and the runtime-visible result.

For the current campaign, the reference example is: 

Examples/05_bounded_ui_accumulator/main.frog

The CLI should make that example easy to execute and easy to inspect, including the preservation of:

  • the canonical for_loop structure,
  • explicit local memory,
  • widget_value paths,
  • widget_reference paths,
  • and object-style face_color writes.

11. What this Directory Must Not Do

This directory must not:

  • become the hidden owner of source validity rules,
  • redefine the canonical source model,
  • redefine the validated semantic layer,
  • collapse FROG Execution IR into backend-family detail,
  • collapse backend contract into runtime-private realization,
  • treat SVG face-template resources as executable semantic truth,
  • or bypass intermediate stages while still pretending to preserve them.

12. Summary

The CLI is the command-line shell of the non-normative FROG reference implementation. Its job is to expose a small, stage-aware, inspectable path across:

  • validation,
  • Execution IR derivation,
  • lowering,
  • backend contract emission,
  • and runtime execution.

For the current campaign, it should be centered primarily on the first complete executable slice: 

Examples/05_bounded_ui_accumulator/main.frog

That keeps the command surface aligned with the repository’s real short-term credibility target: one complete, explicit, end-to-end executable corridor.