CLI and REPL

Theory

CLI (Command Line Interface) and REPL (Read-Eval-Print Loop) serve different development modes in PriyoScript. CLI is file-oriented and deterministic, making it ideal for repeatable execution, project workflows, and CI automation. REPL is interactive and stateful, making it ideal for experimentation, quick checks, and iterative learning. PriyoScript supports both flows with common diagnostics tooling (-errors, -explain) and runtime tracing (-trace) so users can move from exploration to production without changing language semantics.

Core command summary

CLI essentials

Help and diagnostics

Trace helpers and filters

REPL command summary

Program Examples

Example 1: Show Help

monalisa -h

Output (short):

PriyoScript CLI help...

Explanation: verifies installation and available command options.

Example 2: Run a File

monalisa hello.priyo

Output:

Hello, PriyoScript!

Explanation: standard production execution path for .priyo scripts.

Example 3: Start REPL

monalisa -repl

Output (short):

Hey, this is PriyoScript REPL...
priyo>

Explanation: opens interactive shell with persistent in-session state.

Example 4: REPL Session

priyo> priyoKeep x = 12
priyo> priyoTell(x * 2)
24

Output:

24

Explanation: second line uses variable from previous line because REPL keeps environment alive.

Example 5: Error Discovery Commands

monalisa -errors
monalisa -explain PSYN-002

Output (short):

List of error codes...
Explanation for PSYN-002...

Explanation: helps users map runtime/syntax failures to exact docs and fixes.

Example 6: Trace Mode

monalisa -trace examples/basics/for-loop.priyo

Output (short):

[TRACE #1] examples/basics/for-loop.priyo <main> ip=0 op=...
[TRACE #2] examples/basics/for-loop.priyo <main> ip=1 op=...
...

Explanation: shows VM instruction-by-instruction flow for deep debugging.

Filter examples:

monalisa -trace -trace-op CALL_METHOD,RETURN examples/basics/for-loop.priyo
monalisa -trace -trace-format json -trace-frame "<main>" examples/basics/for-loop.priyo

Example 7: Breakpoint-Style Hook

monalisa {
  priyoKeep total = 10
  prakritiThink("after-total")
  priyoTell(total)
}

Output (short):

[BREAK #1] label="after-total"
10

Explanation: prakritiThink(...) marks checkpoints inside trace output.

Example 8: Useful REPL commands

priyo> .help
priyo> .load examples/basics/main.priyo
priyo> .editor
edit> priyoKeep n = 10
edit> priyoTell(n * 5)
edit> .run
priyo> .reload
priyo> .env
priyo> .type 10 + 32
priyo> .history
priyo> .reset
priyo> .exit

Output (short):

REPL commands list...
Loaded: examples/basics/main.priyo
Editor mode enabled...
50
Reloaded: examples/basics/main.priyo
Bindings:
type: number
value: 42
REPL history:
Runtime state reset.

Explanation: supports structured iteration in interactive mode.

Example 9: REPL persistence file

PriyoScript REPL saves session history automatically to:

.priyo_repl_history.json

You can keep this file for continuity or remove it to start with clean persisted history.

Execution Flow

CLI flow:

1. You pass file path.
2. CLI loads full source.
3. Parser/compiler/VM run once.
4. Program exits with output or error.
5. Each run starts with a clean runtime process.

REPL flow:

1. You type one line/snippet.
2. REPL evaluates it immediately.
3. State stays in memory for next line.
4. History is persisted to .priyo_repl_history.json on exit.
5. You repeat until .exit.
6. .reset clears runtime state and module cache for clean retry.
7. Optional editor mode (.editor) lets you draft multi-line snippets before running .run.

Trace flow:

1. You run with -trace (optional -trace-* filters).
2. VM emits execution lines for each instruction.
3. If prakritiThink(...) exists, VM prints a breakpoint marker.
4. On runtime error, PriyoScript includes source-level stack context.
5. Use trace output to isolate exact failing sequence.

Comparison With Other Languages

Node.js CLI/REPL:

• node file.js
• node (interactive REPL)

Python CLI/REPL:

• python script.py
• python (interactive shell)

Java:

• Compile + run model (javac, java) and optional JShell for REPL-like experience.

C:

• Compile then execute binary (gcc, ./a.out), no default built-in REPL.

PriyoScript:

• monalisa file.priyo
• monalisa -repl
• monalisa -trace file.priyo

Difference summary:

• PriyoScript behaves like modern interpreted workflows (Node/Python) with dedicated language diagnostics.
• PriyoScript adds built-in error-code explanation flow (-errors and -explain) for beginner-friendly debugging.

Inspiration and Official References

• Node.js CLI and REPL concepts:
  https://nodejs.org/api/cli.html
  https://nodejs.org/api/repl.html
• Python interpreter and command line:
  https://docs.python.org/3/tutorial/interpreter.html
• Java JShell:
  https://docs.oracle.com/en/java/javase/21/jshell/introduction-jshell.html
• C compile-run workflow (GCC docs):
  https://gcc.gnu.org/onlinedocs/