FIR - Friendly Intermediate Representation

FIR (Friendly Intermediate Representation) is a human-readable intermediate representation designed for compiler backends and language implementation education. Unlike traditional programming languages, FIR is intended to be generated by compilers rather than written by humans, though its readable syntax makes it valuable for debugging and understanding compilation processes.

FIR serves as an educational example of interpreter implementation, demonstrating dynamic typing, Abstract Syntax Tree (AST) design, Intermediate Representation (IR) for execution, and language design principles for simplicity and extensibility.

FIR is dynamically typed, supporting integers, floats, strings, booleans, and arrays. It features functions, control flow (if/goto), arithmetic operations, and I/O.

Installation

Prerequisites

• .NET 8.0 SDK

Building

Clone or download the repository, then build the project:

dotnet build

Deployment

To build and test the project:

./build.bat

To create a self-contained executable for distribution:

./deploy.ps1

This will publish the FIR CLI as a self-contained executable in the ./publish directory. You can distribute the contents of this directory as a standalone FIR interpreter.

The deploy script defaults to Windows x64, but you can specify other runtimes:

./deploy.ps1 -Runtime linux-x64

Or change the output directory:

./deploy.ps1 -OutputDir ./my-publish

Usage

FIR is designed as an intermediate representation for compiler backends, but includes tools for direct execution to support education and debugging.

Command Line Interface (CLI)

Execute FIR IR code from files:

dotnet run -- <fir-file>

Example:

dotnet run -- examples/hello.fir

Read-Eval-Print Loop (REPL)

For interactive experimentation and learning (note: requires running from FIRRepl project or modifying FIR.csproj to include FIRRepl.cs):

dotnet run

In REPL mode:

• Enter FIR instructions to execute them immediately
• State is maintained across inputs
• Built-in commands:
  • :help - Show help
  • :quit - Exit
  • :clear - Reset state
  • :show_vars - Display current variables

Note: While the REPL is useful for learning and testing, FIR is primarily intended to be generated by compilers rather than written interactively.

IR Instruction Set

FIR provides a low-level instruction set designed to be generated by compilers. While human-readable for educational purposes, FIR programs are typically produced by language frontends rather than written manually.

Data Types

• Integers: 42
• Floats: 3.14
• Strings: "hello"
• Booleans: true, false
• Arrays: [1, 2, "three"]

Instructions

• Assignment: set x 10
• Arithmetic: add result x y, sub, mul, div
• Output: print value
• Input: input var
• Control flow: if x == 5 goto label, goto label, label mylabel
• Functions: func myfunc, call result myfunc arg1 arg2, return value, endfunc
• Arrays: get_index result arr 0, len result arr
• Strings: concat result "hello" "world", str_len result "string", substring result "string" start length
• Math: sin result angle, cos result angle, pow result base exponent

Expressions

Expressions in assignments and operations:

• Literals as above
• Variables: myvar
• Arrays: [1, 2, 3]

Comments

• # comment or // comment

Examples

See the examples/ directory for sample FIR IR code (these demonstrate what compiler-generated FIR might look like):

• hello.fir - Basic function definition and call with output
• fibonacci.fir - Iterative Fibonacci calculation using goto loops
• functions.fir - Function definitions, calls, and parameter passing
• arrays.fir - Array creation, indexing, and length operations
• strings.fir - String manipulation and comparison
• simple.fir - Basic arithmetic and control flow
• math.fir - Mathematical function calls (sin, cos, pow)
• string_ops.fir - String operations (length, substring, concatenation)
• advanced.fir - Complex example combining arrays, functions, and math
• error_demo.fir - Error handling and debugging scenarios

API Reference

For detailed API documentation, see api.md.

Error Handling

FIR provides descriptive error messages for:

• Parse errors with position information
• Runtime errors with context (undefined variables, type mismatches, etc.)

Contributing

This is an educational project focused on compiler and interpreter design. FIR serves as a platform for learning about:

• Intermediate representation design
• Compiler backend implementation
• Interpreter architecture
• Language implementation techniques

Feel free to experiment and extend FIR's features, particularly in areas like optimization passes, additional data types, or compilation targets.