Getting Started

This page takes you from an empty machine to a running, tested Refingere program. It takes a few minutes. You'll need a terminal, and each step shows exactly what to type.

1. Download the compiler

The compiler is a single file for each platform, with nothing else to install, packed in an archive. Pick your system:

Download the archive for your processor:

Unpack refingere from it into a folder on your PATH:

~/.local/bin is on the PATH on most distributions; if it isn't on yours, add export PATH="$HOME/.local/bin:$PATH" to your shell's profile.

Then open a new terminal and check it works - it lists its options:

The first run unpacks the compiler's standard library into ~/.cache/refingere (%LOCALAPPDATA%\refingere on Windows), once - with the compiler as it is once it's done that library, so a run only compiles your own files.

2. Write your first program

Make a folder for it, anywhere:

In hello, create a file called main.rfn with any text editor, and put this in it. In VS Code, the Refingere extension highlights it for you.

@main marks greet as the function the program starts with. There can be at most one per folder. &stdout is the program's standard output, one of the context values every program can read, and writeText writes to it. \n ends the line.

3. Run it

In hello, run:

The compiler checks every .rfn file in the folder, compiles them into one program and, when there are no errors, calls greet - any errors are listed instead, and nothing runs. The folder it works on is the current one - give another as rfn --run ../somewhere, or a single file.

4. Add a test

Tests live right next to the code. Change main.rfn to:

@test makes a function a test. Its name is in backticks, so it can be a whole sentence. The test replaces &stdout for everything it calls: inject stdout := output gives greet an in-memory stream instead of the terminal, so the test can read back what was printed. A test passes unless it ends in an error, so the check is an ordinary if that reaches error when the text is wrong. Context explains how inject works.

Run the tests with --test:

Each test is listed with PASS or FAIL and its name, followed by a count like 1/1 passed. When one fails, the command exits with status 1.

5. Keep it running while you edit

Add --watch and the compiler stays open, checking and running again every time you save a .rfn file - or testing again, with --test --watch. Stop it with Ctrl+C.

Try it: with the watcher running, add a second file to hello. Every file in a folder sees every other file's definitions, so there's nothing to import:

in the same folder, no import needed

6. Start a project from a template

rfn --new starts a project from a template, the way bun create does: program for a program like hello, with a test and a README, or website for a web page with its logic in Refingere. Without a folder or template, it asks.

A website is served while you work on it with rfn --web, and built for publishing with rfn --web --compile - see Websites for what's in the template.

When something's wrong

--check only checks the files. When it finds a problem, it prints the file, the line and column, and the line itself with a ^ under the spot, and nothing runs until it's fixed:

  • This has no @main function to compile - --run needs a function marked @main in the folder it was given.
  • refingere: command not found - the folder you put it in isn't on your PATH, or the terminal was opened before it was. Open a new one, or run it by its full path.
  • no such file '...' - the folder or file is relative to the folder you run the command in. Run it from inside hello, or give the full path.

Next steps