DOCSEARCHbyAlgolia
Submit Docs

Koka Language Documentation

repository·dev·Indexed 26 days ago

https://github.com/koka-lang/koka

Koka is a functional programming language with an effect system. This documentation covers building the compiler from source using Stack, Cabal, or minbuild, installing via binary installers for Windows, macOS, and Linux, and profiling programs using GCC, Clang, or Linux perf. It also provides setup guides for editor support in VS Code (including language server features and inlay hints), (Neo)Vim, and Sublime Text.

Tokens
17.2K
Snippets
58
Records
112
Agent score
85%

What's inside Koka

  1. Overview of Perceus memory management

    dev

    Koka uses Perceus, an advanced compilation method for reference counting. Unlike traditional garbage-collected languages, Perceus uses extensive static analysis to optimize reference counts and perform reuse analysis. This allows Koka to:

    • Compile directly to C code without a heavy runtime or garbage collector.
    • Optimize functional-style programs to use in-place updates (Functional But In-Place / FBIP).
    • Achieve performance close to manual memory management (C/C++) while maintaining functional semantics.

  2. Overview of Koka compiler front-ends

    dev

    The Koka compiler provides two main front-ends depending on your development environment needs:

    • langserver: The standard Koka compiler equipped with VS Code language server support. This is the recommended version for interactive development.
    • plain: The Koka compiler and interpreter without language server support. This version is intended for platforms where the Haskell language server library fails to build.

  3. Use dot notation for function calls

    dev

    Koka provides syntactic sugar for function calls using dot notation. An expression like s.encode(3) is desugared to encode(s, 3), where s becomes the first argument. This allows for intuitive chaining of calls and makes it easy to extend 'primitive' methods of any data type by simply writing a new function that takes that type as its first argument.

    function showit( s : string ) -> s.encode(3).length.println

  4. Declare functions in Koka

    dev

    Functions are declared using the function or fun keyword.

    • Use function for top-level functions.
    • Use fun for anonymous function expressions.

    Koka uses a layout rule where semi-colons are automatically inserted for statements and declarations aligned between braces ({ and }). You can also use explicit semi-colons if you want to put multiple statements on a single line.

    function main() 
{
  println("Hello world!") // println output
}

  5. Use the `with` statement for closures and handlers

    dev

    The with statement is a powerful tool that puts all subsequent statements in the current scope into an anonymous function block and passes that block as the last parameter to the function following with.

    Syntax Patterns:

    • with f(e1, ..., eN) $\mapsto$ f(e1, ..., eN, fn() { <body> })
    • with x <- f(e1, ..., eN) $\mapsto$ f(e1, ..., eN, fn(x) { <body> })

    This is particularly useful for:

    1. Concise nesting: Avoiding deeply nested function calls.
    2. Resource management: Using with finally to ensure code runs on exit.
    3. Effect Handlers: Dynamically binding effect operations over a scope.

  6. Compile and package the VS Code extension

    dev

    To build and package the Koka VS Code extension, navigate to the extension directory and use npm to install dependencies and run the build/package scripts.

    cd support/vscode/koka.language-koka
npm install
npm run build
npm run package
cd ../../..

  7. Run the Koka package build script

    dev

    Run the build script from the root of the repository to generate all possible packages. You can customize the build using the following flags:

    • --target="target1,target2": Specify which versions you want to build and package.
    • --package="no": Build only, do not package.
    • --package="only": Package only.

    After completion, distro-specific bundles and installable packages will be located in ./bundle/$version.

  8. Define and use value operations with `val`

    dev

    A subset of operations always tail-resume with a single value, acting like dynamically bound, statically typed variables. You can declare these using the val keyword within an effect block.

    Example of a width value operation:

    effect val width : int

fun pretty-internal( line : string ) : width string
  line.truncate(width)

fun pretty-thin(d : doc) : string
  with val width = 40
  pretty(d)

  9. Define Koka Modules and Top-level Declarations

    dev

    Koka source code is organized into modules. A module can optionally be declared with module <moduleid> and contains a body of declarations enclosed in braces {} or listed directly.

    Top-level declarations include:

    • import / import extern: Import modules or external definitions.
    • fixity: Define operator precedence and associativity (infixl, infixr, infix).
    • val: Define immutable values.
    • fun: Define functions.
    • type / alias / struct: Define types, type aliases, or structures.
    • effect: Define effects.
    • extern: Define external functions.

    Declarations can be marked with pub to make them public.

  10. Build Koka installation packages

    dev

    You can use the package.sh script to automatically configure Docker images and generate Koka installation packages for various Linux platforms. Currently, this is supported for x64 Linux only.

    Supported distributions include:

    • Fedora 34, 35
    • RHEL 8
    • Debian 10, 11
    • Ubuntu 18.04, 20.04, 22.04
    • PopOS 20.04, 21.10
    • Linux Mint 19.3, 20.2
    • Arch Linux, Manjaro
    • OpenSUSE Tumbleweed, Leap 15.3, Leap 15.4