langrpg/README.md

# Rust RPG Lang

An implementation of the RPG language from IBM.

Language reference: https://www.ibm.com/docs/en/i/7.5.0?topic=introduction-overview-rpg-iv-programming-language

## Usage

### Building

```rust-langrpg/README.md
cargo build --release
```

### Running

The compiler ships as a standalone binary that loads the embedded BNF grammar, builds a parser, and runs a suite of RPG IV snippet examples to demonstrate the grammar in action:

```rust-langrpg/README.md
cargo run --bin demo
```

You will see output similar to:

```rust-langrpg/README.md
=== RPG IV Free-Format Parser ===

[grammar] Loaded successfully.
[parser]  Built successfully (all non-terminals resolved).

=== Parsing Examples ===

  ┌─ simple identifier (identifier) ─────────────────────
  │  source : "myVar"
  │  result : OK
  └──────────────────────────────────────────────
...
=== Summary ===
  total   : 42
  matched : 42
  failed  : 0

All examples parsed successfully.
```

### Hello World in RPG IV

The following is a complete Hello World program written in RPG IV free-format syntax, as understood by this parser:

hello.rpg:

```rust-langrpg/README.md
CTL-OPT DFTACTGRP(*NO);

DCL-S greeting CHAR(25) INZ('Hello, World!');

DCL-PROC main EXPORT;
  DSPLY greeting;
  RETURN;
END-PROC;
```

Breaking it down:

- `CTL-OPT DFTACTGRP(*NO);` — control option spec declaring the program does not run in the default activation group
- `DCL-S greeting CHAR(25) INZ('Hello, World!');` — standalone variable declaration: a 25-character field initialised to `'Hello, World!'`
- `DCL-PROC main EXPORT; ... END-PROC;` — a procedure named `main`, exported so it can be called as a program entry point
- `DSPLY greeting;` — displays the value of `greeting` to the operator message queue
- `RETURN;` — returns from the procedure

To validate this program, execute the compiler to build the data:

```sh
cargo run --release -- -o main hello.rpg
```

## Implementation

The RPG language was converted to an BNF, and fed into the bnf crate (https://docs.rs/bnf/latest/bnf/).

The parse tree generated here is then given to LLVM, via Inkwell (https://crates.io/crates/inkwell) to create executable binaries.

The binary can run standalone on a Linux system. Only the built-in function make hello world are implemented, and link to functions writen in Rust that are available as a shared library.