Naggum usage

Currently there are two dialects of Naggum: high-level Compiler and low-level Assembler.

Naggum Compiler

Command line syntax for Naggum Compiler is:

$ Naggum.Compiler source.naggum... [/r:assembly]...

Each input source file will be compiled to a separate executable assembly (i.e. an .exe file) in the current directory. You can also pass a list of files to be referenced by these assemblies.

.naggum extension is recommended for high-level Naggum files.

Naggum Assembler

Naggum Assembler uses low-level Naggum dialect. Command line syntax is:

$ Naggum.Assembler source.nga...

Each input file may contain zero or more assembly constructs. Every assembly will be saved to its own executable file in the current directory.

.nga extension is recommended for low-level Naggum files.

S-expression syntax

Each Naggum program (either high-level or low-level) is written as a sequence of S-expression forms. In s-expression, everything is either an atom or a list. Atoms are written as-is, lists should be taken into parens.

Possible atom values are:

"A string"
1.4e-5 ; a number
System.Console ; a symbol

A symbol is a sequence of letters, digits, and any of the following characters: +-*/=<>!?..

Lists are simply sequences of s-expressions in parens:

(this is a list)

(this (is ("Also") a.list))

Naggum source code may also include comments. Everything after ; character will be ignored till the end of the line:

(valid atom) ; this is a comment

Low-level syntax

Naggum low-level syntax is closer to CIL. It may be used to define CLI constructs such as assemblies, modules, types and methods. Every .nga file may contain zero or more assembly definitions.

Assembly definition

Assembly defitinion should have the following form:

(.assembly Name
    Item1
    Item2
    ...)

Assembly items can be methods and types. Top level methods defined in an .assembly form will be compiled to global CIL functions.

Type definitions are not supported yet.

Each assembly may contain one entry point method (either a static type method or an assembly global function marked by .entrypoint property).

Method definition

Method definition should have the following form:

(.method Name (argument types) return-type (metadata items)
    body-statements
    ...)

Method argument and return types should be fully-qualified (e.g. must include a namespace: for example, System.Void).

The only supported metadata item is .entrypoint. It marks a method as an assembly entry point.

Method example:

(.method Main () System.Void (.entrypoint)
    (ldstr "Hello, world!")
    (call (mscorlib System.Console WriteLine (System.String) System.Void))
    (ret))

Method body should be a CIL instruction sequence.

CIL instructions

Currently only a small subset of all available CIL instructions is supported by Naggum. This set will be extended in future.

  1. Call instruction:

    (call (assembly type-name method-name (argument types) return-type))
    

    Currently assembly name is ignored; only mscorlib methods can be called. Static assembly function calls are not supported yet.

    Method argument and return types should be fully-qualified.

  2. Load string instruction:

    (ldstr "Hello, world")
    

    Loads a string onto a CLI stack.

  3. Return instruction:

    (ret)
    

    Return from current method.

Example assembly definition

(.assembly Hello
    (.method Main () System.Void (.entrypoint)
        (ldstr "Hello, world!")
        (call (mscorlib System.Console WriteLine (System.String) System.Void))
        (ret)))

High-level syntax

Every high-level Naggum program is a sequence of function definitions and a top-level executable statements. Functions defined in an assembly are also available as public static methods to be called by external assemblies.

Functions are defined using defun special form:

(defun function-name (arg1 arg2)
    statement1
    statement2)

For example:

(defun println (arg)
    (System.Console.WriteLine arg))

Naggum is a Lisp-2, henceforth a function and a variable can share their names.

Currently executable statements may be one of the following.

  1. Let bindings:

    (let ((variable-name expression)
          (variable-name-2 expression-2))
         body
         statements)
    

Creates a lexical scope, evaluates initial values, binds them to corresponding names and evaluates the body, returning the value of last expression.

Naggum’s let is a loner: every one is inherently iterative (like let*) and recursive (like let rec).

  1. Arithmetic statements:

    (+ 2 2)
    
  2. Function calls:

    (defun func () (+ 2 2))
    
    (func)
    
  3. Static CLI method calls:

    (System.Console.WriteLine "Math:")
    
  4. Conditional statements:

    (if condition
        true-statement
        false-statement)
    

If the condition is true (as in “not null, not zero, not false”) it evaluates the true-statement form and returns its result. If the condition evaluates to false, null or zero, then the false-statement form is evaluated and its result is returned from if.

  1. Reduced if statements:

    (if condition
        true-statement)
    
  2. Constructor calls:

    (new Naggum.Runtime.Cons "OK" "FAILURE")
    

Calls an applicable constructor of a type named Naggum.Runtime.Cons with the given arguments and returns an object created.