Navi Language Skill

Navi (/ˈnævi/) is a high-performance, statically-typed compiled language designed for complex computing tasks. It offers script-like execution with compiled performance comparable to Go, Rust, and C.

Core Characteristics

• Statically typed with type inference
• No NULL pointer exceptions - once compiled, code runs reliably
• Modern optional types (similar to Rust's Option)
• Comprehensive error handling with throws, try, try?, try!
• Built-in concurrency with spawn and channels (single-threaded concurrency)
• Cross-platform: Linux, Windows, macOS, WebAssembly

Quick Reference

Basic Syntax

// Entry point (main must have throws)
fn main() throws {
    let name = "World";
    let message = `Hello ${name}.`;  // String interpolation
    println(message);  // Auto-imported from std.io
}

// Functions
fn add(a: int, b: int): int {
    return a + b;
}

// Structs
struct User {
    name: string,
    email: string?,  // Optional field
    active: bool = true,  // Default value
}

impl User {
    fn new(name: string): User {
        return User { name, email: nil };
    }
}

Key Syntax Rules

• Statements end with ;
• Use 4 spaces for indentation
• // for single-line comments, /// for doc comments
• String interpolation uses backticks: `value: ${x}`
• File extension: .nv

Important Syntax Limitations

If and Switch are STATEMENTS, not expressions:

// ❌ WRONG - Cannot assign if/switch directly
let status = if (active) { "on" } else { "off" };
let day = switch (n) { case 1: "Mon"; default: "Other"; };

// ✅ CORRECT - Use statements, then assign
let status = "";
if (active) {
    status = "on";
} else {
    status = "off";
}

Scientific notation requires explicit sign:

// ❌ WRONG
let num = 1.5e10;

// ✅ CORRECT
let num = 1.5e+10;  // or 1.5e-10 for negative exponent

Map access with [] vs .get():

let scores = {"Alice": 95, "Bob": 87};

// ❌ WRONG - scores["key"] returns non-optional, can't use ||
let score = scores["Eve"] || 0;

// ✅ CORRECT - Use .get() which returns optional type
let score = scores.get("Eve") || 0;

// ✅ Also correct - Direct access (but key must exist)
let alice_score = scores["Alice"];  // OK if key exists

// ✅ Also correct - Check before access
if (scores.get("Eve") != nil) {
    let score = scores["Eve"];
}

Type System Essentials

// Primitives (all 64-bit)
let n: int = 100;
let f: float = 3.14;
let b: bool = true;
let s: string = "text";  // Immutable UTF-8
let c: char = '🎉';

// Optional types (key to NULL safety)
let value: string? = nil;
let result = value || "default";  // Unwrap or default
let length = value?.len();  // Safe chaining (returns nil if value is nil)
println(value!);  // Unwrap (panics if nil - use sparingly)

// Collections
let array = [1, 2, 3];
let map = {"key": "value"};
let empty: [int] = [];

Error Handling Pattern

// Declare function can throw
fn divide(a: int, b: int): int throws {
    if (b == 0) {
        throw "Division by zero";
    }
    return a / b;
}

// Handle errors
let result = try? divide(10, 0);  // Returns int? (nil on error)
let result = try divide(10, 2);   // Propagate error up
let result = try! divide(10, 2);  // Panic on error

// Do-catch block
do {
    let r = try divide(10, 0);
} catch (e) {
    println(e.error());
}

Control Flow Patterns

// If-let for optionals
if (let value = optional) {
    println(value);  // value is unwrapped here
}

// Let-else for early returns
let value = optional else {
    return;
};
// value is unwrapped here

// Switch with type matching
switch (let v = value.(type)) {
    case int:
        println("integer");
    case string:
        println("string");
    default:
        println("other");
}

// For loops
for (let i in 0..10) {  // Range
    println(`${i}`);
}

for (let item in array) {  // Array
    println(item);
}

for (let k, v in map) {  // Map
    println(`${k}: ${v}`);
}

Concurrency Basics

use std.time;

fn main() throws {
    let ch = channel::<int>();

    // Spawn concurrent task (not parallel - single thread)
    spawn {
        time.sleep(0.1.seconds());
        try! ch.send(42);
    }

    let result = try ch.recv();
    println(`${result}`);
}

Worker Pattern

use std.worker.Worker;

fn main() throws {
    // Create worker with closure
    let worker = try Worker.create(|worker| {
        let msg = try worker.recv::<string>()!;
        try worker.send(msg.to_uppercase());
    });

    try worker.send("hello");
    let response = try worker.recv::<string>();
    println(response);  // "HELLO"
}

Navi Stream Integration

use nvs.macd;  // Import .nvs file as module

fn main() throws {
    // Create instance of NVS indicator
    let indicator = macd.new();

    // Execute with market data
    indicator.execute(
        time: 1234567890,
        open: 100.0,
        high: 105.0,
        low: 99.0,
        close: 103.0,
        volume: 1000.0,
        turnover: 100000.0
    );

    // Access exported variables
    println(`hist=${indicator.hist:?}`);
    println(`signal=${indicator.signal:?}`);
    println(`macd=${indicator.macd:?}`);
}

Variadic Arguments

// Accept arbitrary number of arguments
fn sum(values: ..int): int {
    let total = 0;
    for (let n in values) {
        total += n;
    }
    return total;
}

sum(1, 2, 3);           // Call with multiple args
let nums = [2, 3, 4];
sum(..nums);            // Spread array
sum(1, ..nums, 5);      // Mix regular and spread

// With other parameters
fn format(prefix: string, parts: ..string): string {
    return prefix + parts.join(",");
}

Common Patterns

Safe Optional Handling

// Pattern 1: Unwrap or default
let name = user?.name || "Unknown";

// Pattern 2: If-let
if (let user = optional_user) {
    process(user);
}

// Pattern 3: Let-else (early return)
let user = optional_user else {
    return;
};
process(user);

// Pattern 4: Method chaining
let email = user?.profile?.email || "none";

Resource Management

fn process_file(path: string) throws {
    let file = try open_file(path);

    defer {
        file.close();  // Always runs when function exits
    }

    try file.read();
    // defer executes here (LIFO if multiple defer blocks)
}

Builder Pattern

impl Config {
    fn new(): Config {
        return Config { /* defaults */ };
    }

    fn with_port(self, port: int): Config {
        self.port = port;
        return self;
    }
}

let config = Config.new().with_port(8080);

CLI Commands

navi run              # Run main.nv
navi run file.nv      # Run specific file
navi test             # Run all tests
navi test file.nv     # Run tests in file
navi test --doc       # Run doc tests
navi build            # Build project
navi compile          # Show bytecode

Testing

test "addition" {
    let result = add(2, 3);
    assert result == 5;
    assert_eq result, 5;
    assert_ne result, 0;
}

/// Doc test example
/// ```nv
/// assert_eq add(1, 2), 3;
/// ```
fn add(a: int, b: int): int {
    return a + b;
}

Best Practices

Naming Conventions

• snake_case: variables, functions, fields (user_name, get_user)
• CamelCase: types, structs, enums (User, HttpRequest)
• SCREAMING_SNAKE_CASE: constants (MAX_SIZE)

When to Use Each Error Handler

• try - When error should propagate up (most common)
• try? - When failure is acceptable, convert to optional
• try! - When failure is unexpected (use sparingly)
• do-catch - When you need custom error handling logic

Optional Type Guidelines

• Use || for simple defaults
• Use ?. for safe chaining
• Prefer if let for conditional logic
• Use let else for early returns

Concurrency Notes

• spawn is concurrent, not parallel (single-threaded)
• Tasks interleave but don't run simultaneously
• Use channels for communication between tasks
• Blocking operations block entire runtime

When to Load References

Load reference files when you need detailed information:

• syntax.md - Full syntax reference with all language constructs
• types.md - Complete type system including interfaces, unions, type aliases
• error-handling.md - Comprehensive error handling patterns and custom errors
• concurrency.md - Advanced concurrency patterns, channels, and spawn details
• modules.md - Module system, imports, visibility rules
• testing.md - Testing framework, annotations, doc tests
• patterns.md - Common idiomatic patterns and anti-patterns

Use Read tool to load these files from ~/.claude/skills/navi/references/ when needed.

Resources

• Official Site: https://navi-lang.org
• Standard Library: https://navi-lang.org/stdlib/
• GitHub: https://github.com/navi-language/navi
• Installation: curl -sSL https://navi-lang.org/install | sh