Skip to content

Latest commit

 

History

History
198 lines (168 loc) · 5.71 KB

reference.md

File metadata and controls

198 lines (168 loc) · 5.71 KB

Fun Language Reference (Comprehensive)

Overview

Fun is a statically-typed, C-transpiling language focused on performance and clarity. The compiler emits readable C and relies on the system C toolchain for linking and execution.

Numeric Model

  • num is a signed 64-bit integer (C int64_t).
  • dec is a 64-bit floating-point number (C double).
  • Fixed-width integers: i8, i16, i32, i64, u8, u16, u32, u64.
  • Fixed-width floats: f32 (float), f64 (double).
  • Arbitrary-width integers: iN / uN (emitted as _BitInt(N) / unsigned _BitInt(N) when width is not a standard 8/16/32/64).
  • bin is boolean (bool).
  • chr is a character (char).
  • str is a null-terminated string (char*).
  • raw is an opaque/void type (void in C; use raw* for void*).

Source Structure

  • File extension: .fn
  • Statements end with ;.
  • Blocks are delimited with {}.
  • Comments: // single-line.

Imports

  • imp std.c.io; imports a C header signature module.
  • imp std.string; imports Fun stdlib modules.
  • Relative imports are supported (e.g., imp ..foo.bar;).
  • Import aliases are supported: imp mod1 as one; then use one.symbol.
  • Aliases are the supported way to avoid duplicate exported symbol collisions across imported modules.
    • Example:
      • imp mod1 as one;
      • imp mod2 as two;
      • num a = one.pick();
      • num b = two.pick();

Types

Built-in Types

  • num, dec, f32, f64, i8, i16, i32, i64, u8, u16, u32, u64, iN, uN, bin, chr, str, raw

Arrays

  • Syntax: num[] arr = [1, 2, 3];
  • Array literals require uniform element types.

Pointers

  • Pointer depth: Type*.
  • Example: Node* next;.

Compounds (Structs)

compound Point {
  num x;
  num y;
}

Quirks (Interfaces)

quirk Shape {
  area() num;
}

Implementations

impl Point {
  translate(num dx, num dy) {
    self.x += dx;
    self.y += dy;
  }
}

impl Rectangle Shape {
  area() num { ret self.w * self.h; }
}

Generics

  • Compounds and impls can be generic: compound Vec<T> { ... }.
  • Use Vec<num> etc. where required.

Variables

  • Variables can be explicitly typed or inferred with let.
num x = 1;
str name = "fun";
let count = add(1, 2);

Functions

fun add(num a, num b) num {
  ret a + b;
}
  • No nested function declarations.
  • Use ret for return.
  • Generic functions are supported:
fun id<T>(T x) T { ret x; }

Control Flow

If / Elif / Else

if x > 0 {
  ...
} elif x == 0 {
  ...
} else {
  ...
}

For

  • Range: for i : 0..10 { ... }
  • Array: for item : arr { ... }
  • Indexed: for i, item :: arr { ... }
  • While-style (condition): for i < len { ... }
  • Infinite loop: for true { ... }
  • This style is used in stdlib (for example std/string.fn, std/net.fn, and std/fs.fn).

Fit (Pattern Matching)

fit c {
  .Red -> { ... },
  .Green -> { ... },
  _ -> { ... }
}
  • Missing variants may produce warnings unless _ is present.

Defer

  • Expression: defer close(fd);
  • Block: defer { cleanup(); }
  • Runs in LIFO order before function exit.

Inline Assembly

asm volatile (out y: "=r" = y; in x: "r" = x; clobber "memory") {
  mov x0, x0
};
  • asm arch x86_64 { ... }; guards by target architecture.
  • Block contents are preserved as raw text (including whitespace/comments).
  • Fun does not validate asm syntax inside the block; final validity is determined by the selected C toolchain assembler/dialect.
  • Example: jmp $ can fail under clang/GAS inline asm, while local-label form (1: ... jmp 1b) is often accepted in that dialect.
  • Pass computed values through operands, e.g. num x = 21 + 21; num y = 0; asm volatile (out y: "=r" = y; in x: "r" = x) { mov %[x], %[y] };.
  • Use string form for explicit escaping: asm "...";.

C Interop

  • Import C headers via imp std.c.*;.
  • C constants (e.g., NULL, INT_MAX) are allowed when headers are imported.
  • num maps to int64_t; for printf, use PRId64 (from <inttypes.h>) or cast to long long and use %lld.

C Compiler Selection

By default, fun uses zig cc. You can override the compiler with environment variables:

  • FUN_CC: compiler command. If it contains {src} and {out}, it is treated as a full template.
  • FUN_CC_ARGS: extra arguments appended after the base command.

Examples:

  • FUN_CC=clang
  • FUN_CC=zig and FUN_CC_ARGS="cc"
  • FUN_CC="clang -O2 {src} -o {out}"

Formatting

  • fun -fmt -in file.fn formats a file in place.
  • fun -fmt-all -in file.fn formats local imports (skips std.*).
  • Asm block contents are preserved as raw text.

Tooling (fls)

  • Language Server for diagnostics and formatting.
  • Diagnostics use fun -no-exec under the hood.

Standard Library (high level)

  • std.array: array helpers
  • std.io: file helpers + print utilities
  • std.vec: dynamic vectors
  • std.map: generic maps (Map<K, V>) with typed keys/values and bytewise hashed lookups by default
  • std.set: sets built on maps
  • std.option: generic Option<T> container
  • std.result: generic Result<T> container
  • std.collections: collection quirks (len/is_empty)
  • std.string: string helpers
  • std.json, std.toml: minimal serialization helpers
  • std.time, std.rand, std.math, std.path, std.net, etc.
  • std.sys: environment and process helpers (sys_exit, sys_abort, sys_system)
  • std.net: URL parsing + pure Fun POSIX TCP/HTTP helpers (POSIX sockets)

CLI

fun -in <input_file> [-out <output_file>] [-no-exec] [-outf] [-ast] [-help]

Errors and Warnings

  • Type mismatches, unknown symbols, and incomplete quirk implementations are errors.
  • Fit exhaustiveness and pointer-return warnings are emitted as warnings.