• Setting up your compiler

    Setting up Kipper is a rather straight-forward process. The compiler can be either be configured using code (in case you're using the web bundle or an imported node module) or using console flags which are passed to the CLI that is provided by the @kipper/cli package.

    Depending on which method you're using, you will have to configure the compiler differently although both will have almost the exact same possibilities and feature-sets. For both methods the API docs will provide in-depth info about the behaviour and provided functionality of the compiler.

    The API docs are a work-in-progress and will be slowly, but surely realised with the development of Kipper. As such this page is for now used as a substitute for the in-detail CLI and Module API docs.

    Kipper API

    Kipper provides an API for interacting with its compiler, which can be used to configure and inspect the compilation of a program. This API is per default shipped with the @kipper/core package and the kipper-standalone.js file, as well is provided using flags with the CLI (@kipper/cli).

    For more info view the following sections of this page:

    Configuring the Kipper Compiler in Node.js

    Configuring KipperCompile.compile() can be done using the CompileConfig interface, which defines all available parameters for a compilation.

    Kipper Compiler Parameters

    Parameter Type
    		 Description
    fileName string The name of the file. Per default anonymous-script.
    target KipperTarget The Kipper target instance, which defines the translation behaviour of the Kipper AST nodes.
    optimisationOptions OptimisationOptions

    The options for optimising the Kipper output.

    Defaults to an object with the following values:

    • optimiseInternals: true
    • optimiseBuiltIns: false

    More info down below in Kipper Optimiser Parameters.

    extendBuiltIns Array<BuiltInFunction> Additional built-in functions that should be available in the Kipper program. This extends builtIns and is per default empty.
    builtIns
    		 Array<BuiltInFunction> Standard built-in functions that should be available in the Kipper program.

    If this is defined with new built-in functions that Kipper does not implement per default, the Kipper target class will have to be updated as well to implement the generation of these built-ins.

    Defaults to the function as listed in Built-in Functions.

    Kipper Optimiser Parameters

    Parameter Type Description
    optimiseInternals boolean If set to true, the internal functions (functions generated by the Kipper compiler to provide specific functionality) of the compiled code will be optimised using tree-shaking reducing the size of the output. Defaults to true.
    optimiseBuiltIns boolean If set to true, the built-in functions of the compiled code will be optimised using tree-shaking reducing the size of the output. Defaults to false.

    Example Configuration

    import { KipperCompiler } from "@kipper/core";
import { JSTarget } from "@kipper/target-js";

const compiler = new KipperCompiler();
const result = compiler.compile(
    kipperCode, // A string or a KipperParseStream containing the source code
    {
        fileName: "myProgram.kip",
        target: new JSTarget(),
        optimisationOptions: {
            optimiseInternals: true, // Removes any unused internal function
            optimiseBuiltIns: true, // Removes any unused built-in function
        },
    },
);

    Configuring the Kipper Compiler CLI

    Parameters for the Kipper Compiler CLI in the console.

    Flags Description
    -b, --[no-]optimise-builtins Optimise the generated built-in functions using tree-shaking to reduce the size of the output.
    -e, --encoding=encoding [default: utf8] The encoding that should be used to read the file (ascii,utf8,utf16le).
    -i, --[no-]optimise-internals Optimise the generated internal functions using tree-shaking to reduce the size of the output.
    -o, --output-dir=output-dir [default: build] The build directory where the compiled files should be placed. If the path does not exist, it will be created.
    -s, --string-code=string-code The content of a Kipper file that can be passed as a replacement for the 'file' parameter.
    -t, --target=js|ts [default: js] The target language where the compiled program should be emitted to.
    -w, --[no-]warnings Show warnings that were emitted during the compilation.
    --[no-]abort-on-first-error Abort on the first error the compiler encounters. Same behaviour as '--no-recover'.
    --[no-]log-timestamp Show the timestamp of each log message.
    --[no-]recover Recover from compiler errors and display all detected compiler errors.

    Example CLI Command

    • Simple compilation of a single file (will generate ./build/sample.js):
    kipper compile sample.kip
    • Simple compilation from a string (will generate ./build/anonymous-script.js):
    kipper compile -s "print('Hello world!');"
    • Generating a UTF16-encoded program, where both internals and built-in are optimised (will generate ./build/anonymous-script.js): 
    kipper compile -s "print('Hello world!');" -e utf16le -i -b