DOCSEARCHbyAlgolia
Submit Docs

NanoLang Documentation

repository·main·Indexed 20 days ago

https://github.com/jordanhubbard/nanolang

A minimal, formally proved programming language designed for machine and human readability. NanoLang features a stack-based virtual machine (NanoISA), transpiles to C, and supports targets like WebAssembly and LLVM. Key architectural features include a co-process FFI with shared-memory mailbox, a cooperative CPS/coroutine async model, and Coq-backed formal verification. The language enforces mandatory shadow tests for verification and provides editor support for VS Code, Emacs, and Vim/Neovim, including LSP and DAP binaries.

Tokens
387.5K
Snippets
1.3K
Records
1.7K
Agent score
67%

What's inside NanoLang

  1. Overview of NanoLang API Modules

    main

    NanoLang provides a wide range of built-in modules categorized by functionality. These modules are automatically generated from source code via reflection and cover the following domains:

    • Standard Library: log (structured logging), coverage (code coverage), and StringBuilder (string manipulation).
    • SDL Family (Graphics & Audio): sdl (window/input), sdl_image (image loading), sdl_mixer (audio), and sdl_ttf (font rendering).
    • Terminal: ncurses for text-based user interfaces.
    • Network: curl (HTTP client), http_server (simple HTTP server), and uv (async I/O via libuv).
    • Data: sqlite for database bindings.
    • Graphics: opengl, glew, glfw, and glut for 3D graphics and window management.
    • Physics: bullet for physics engine bindings.
    • Utilities: filesystem, preferences, event (event handling), vector2d (2D math), and proptest (property-based testing).

  2. Overview of NanoLang capabilities and vision

    main

    NanoLang is a minimal, LLM-friendly programming language designed for performance and portability. It compiles to C and requires shadow tests for all compiled code.

    Core Features:

    • Compilation: Compiles to C for high performance or to .nvm bytecode for the NanoISA Virtual Machine.
    • Syntax: Supports both infix (a + b) and prefix ((+ a b)) notation for operators.
    • Self-Hosting: The language is fully self-hosted (the NanoLang compiler is written in NanoLang).
    • Type System: Includes primitives, arrays, structs, enums, unions, generics, tuples, first-class functions, and affine types.
    • Verification: The core language semantics are formally verified in Coq (type soundness, progress, determinism, and semantic equivalence).
    • Standard Library: Includes 66+ functions covering math, strings, binary strings, arrays, I/O, OS, and checked math.
    • FFI: Supports over 30 FFI modules (e.g., SDL, OpenGL, curl, Python bridge) using a process-isolated co-process model.

  3. What is NanoLang?

    main

    NanoLang is a compiled systems programming language designed specifically for LLM (Large Language Model) code generation. It aims to solve the problem of inconsistent code styles produced by LLMs by enforcing exactly one canonical way to write each language construct.

    Key technical characteristics:

    • Transpilation: It transpiles to C for native performance.
    • Memory Management: Uses Automatic Memory Management (ARC) with zero-overhead reference counting (available since v2.3.0).
    • Optimization: Features LLM-powered autonomous optimization via continuous profiling (available since v2.3.0).
    • Syntax Philosophy: Uses a 'Canonical Syntax' approach where every operation has one primary form, though operators support dual notation.
    • Safety: Requires mandatory 'Shadow Tests' for every function at compile-time.
    • Interop: Supports full FFI (Foreign Function Interface) for calling C libraries.

  4. Overview of NanoLang language features

    main

    NanoLang is a production-ready, formally verified language with the following core capabilities:

    Type System

    • Static Typing: Supports Hindley-Milner type inference and local type inference (annotations are optional when unambiguous).
    • Primitive Types: Includes standard primitives.
    • Complex Types: Supports Structs (Product Types), Enums, Unions, and Generics (via monomorphization).
    • Pattern Matching: Supports match guards (Val(u) if u.n > 0 =>) and or-patterns (| A | B =>).

    Control Flow & Concurrency

    • Async/Await: Implemented via CPS transformation.
    • Coroutines: Native support for coroutines.
    • Parallelism: par-let x=e1 y=e2 in body provides hints for parallel evaluation.
    • Algebraic Effects: Uses effect, perform, and handle syntax.

    Syntax & Operators

    • F-string interpolation: f"Hello {name}!"
    • Pipe operator: x |> f |> g
    • Anonymous functions: fn(x: int) -> int { return (* x 2) }
    • Tuple destructuring: let (q, r) = (divmod 17 5)
    • Dual Notation: Supports both Prefix (S-expression style) and Infix (conventional style).

  5. Overview of the Beads Module

    main

    The stdlib/beads.nano module provides programmatic access to the Beads issue tracker from NanoLang code. It wraps the bd command-line tool to provide a type-safe API for querying, creating, and managing issues directly from your programs. This is particularly useful for automating issue creation from failing assertions.

    Dependencies:

    • bd command-line tool (must be installed and in PATH)
    • stdlib/process.nano (for shell execution)
    • stdlib/json.nano (for parsing output)

  6. Overview of Nanolang LSP Implementation

    main
    The Nanolang Language Server Protocol (LSP) implementation provides IDE-like features for the Nanolang language, including code completion, go-to-definition, error diagnostics, and navigation. It is designed to work with various LSP clients such as VS Code, Vim, and Emacs via JSON-RPC over stdio.

  7. Understand the NanoLang test strategy and goals

    main

    The NanoLang testing framework is designed to ensure correctness across the entire compilation pipeline. The primary goals are to:

    1. Verify lexer + parser correctness: Ensure source code is correctly tokenized and structured into an AST.
    2. Verify validation rules: Ensure semantic checks (like type checking and identifier resolution) work as expected.
    3. Verify compilation determinism and schema conformance: Ensure the compiler produces consistent output that adheres to the defined schema.

  9. Current limitations of the NanoLang module system

    main

    As of the current version, NanoLang lacks several features found in mature module systems like Python, Go, or Elixir. Developers should be aware of these limitations:

    • No Module Introspection: There is no way to list exports, check if a function exists, or retrieve module metadata programmatically.
    • Scattered Unsafe Blocks: Unsafe operations (like FFI calls) require noisy, individual unsafe { ... } blocks around every call, rather than marking an entire module as unsafe.
    • Modules are not First-Class: There is no Module type, meaning modules cannot be passed as arguments to functions.
    • No Safety Metadata: Modules do not carry metadata regarding their safety, making it impossible for the compiler or tools to warn users about potentially dangerous imports.

  10. Use Nanolang LSP features in VS Code

    main

    The extension integrates with nanolang-lsp to provide a full Language Server Protocol (LSP) experience. Supported features include:

    • Diagnostics: Real-time reporting of type errors and syntax errors.
    • Completions: Auto-completion for identifiers, keywords, and types.
    • Hover: Displaying type information when hovering over code elements.
    • Go to definition: Jumping directly to variable or function declarations.
    • Semantic tokens: Enhanced code coloring and token classification.
    • Format on save: Automatically formats your code using nano-fmt --write via the textDocument/formatting handler.

  12. Modern NanoLang features overview

    main

    Modern NanoLang development utilizes several key features to improve code structure and safety:

    • Enums: For defining named integer constants.
    • Structs: For grouping related data fields.
    • Top-level constants: For global configuration using let.
    • Dynamic arrays: GC-managed arrays (e.g., array<int>).
    • Type casting: Explicit conversions between types (e.g., int to float).
    • Unary operators: Support for - and not.