• Quickstart

    Welcome to the Quickstart Guide for the Kipper programming language! Here you will find a concise guide on how to install Kipper and start using it for your own projects.

    Before using Kipper make sure your system or browser is supported! View support list here.

    How to use Kipper?

    The Kipper Compiler supports multiple environments of which the most common ones are:

    1. Running the Kipper Compiler in a browser using @kipper/web. -> Setting up Kipper for the Browser
    2. Running the Kipper Compiler using the @kipper/cli package in a terminal. -> Setting up Kipper for the Terminal
    3. Including the @kipper/core package into a Node.js program. -> Importing Kipper as a module

    Opt-in for development versions

    If you wish to use the newest features of Kipper, you can instead of installing the latest tag install next, which includes features not yet available in the stable release. Note though that they are usually experimental and not fully tested, so edge cases may not work or documentation may be incomplete.

    If you are using next releases or also the next docs, we greatly appreciate any feedback or help! Kipper is open-source and free for anyone, help us make it even better! 🦊❤️

    Setting up Kipper for the Browser

    For running Kipper in the browser, you will have to include the primary kipper-standalone.min.js file, which provides the Kipper source code compatible for relatively modern browsers.

    View the support list to make sure your browser is supported.

    Including the Web Bundle

    The following script tag will include the latest version of the Kipper Compiler for the browser:

    <script src="https://cdn.jsdelivr.net/npm/@kipper/web@latest/kipper-standalone.min.js"></script>

    Once the Kipper file has been loaded, you can access the library using the identifier Kipper, which will be globally available in your HTML file.

    Version Migration Info

    Kipper v0.9.2 uses a different method of including and running Kipper in the browser. If you are still using 0.9.2, please go to this docs page to see how to use it.

    Running the Compiler in an HTML file - Example

    This is a simple example of how to use Kipper in an HTML file. This will compile the string print("Hello world"); down to JavaScript, and evaluate it. If everything worked, you should see the logger output and Hello world! printed to the browser console:

    <script type="module">
        // Define your own logger and compiler, which will handle the compilation
        const logger = new Kipper.KipperLogger((level, msg) => {
            console.log(`[${Kipper.getLogLevelString(level)}] ${msg}`);
        });
    
        // Define your own compiler with your wanted configuration
        const compiler = new Kipper.KipperCompiler(logger, {});
    
        // Compile the code to Typescript
        const result = await compiler.compile(
            `print("Hello world!");`,
            { target: new KipperJS.TargetJS() }, // Configure the compiler to compile to JavaScript
        );
        const jsCode = result.write();
    
        // Finally, run your program
        eval(jsCode);
    </script>
    • Using callbacks:
    <script type="module">
        // Define your own logger and compiler, which will handle the compilation
        const logger = new Kipper.KipperLogger((level, msg) => {
            console.log(`[${Kipper.getLogLevelString(level)}] ${msg}`);
        });
    
        // Define your own compiler with your wanted configuration
        const compiler = new Kipper.KipperCompiler(logger, {});
    
        // Compile the code to Typescript - With a callback
        compiler
            .compile(
                `print("Hello world!");`,
                { target: new KipperJS.TargetJS() }, // Configure the compiler to compile to JavaScript
            )
            .then(
                (result) => {
                    const jsCode = result.write();
    
                    // Finally, run your program
                    eval(jsCode);
                },
                (rejected) => {
                    console.error(rejected);
                },
            );
    </script>

    Setting up Kipper for the Terminal

    To use Kipper in a terminal, you will have to install the package @kipper/cli, which provides the CLI for the Kipper Compiler. This will make the executable program kipper globally available in your project work directory and will allow you to run the Kipper Compiler from the terminal.

    Installing Kipper for a project

    For setting up a project with a specific Kipper version you will have to add the @kipper/cli package to your package.json file. If then installed by your local package manager, the executable kipper will be available in your project's work directory, but not anywhere else.

    Running the following command will install the latest version of Kipper for your project:

    npm install @kipper/cli

    Use the flags --save or --save-dev to add the package to your package.json file permanently, so that it will be installed automatically when running npm install in the future.

    Manual Installation to package.json

    Example package.json:

    {
        "name": "example",
        "version": "0.1.0",
        "description": "An example program using Kipper",
        "keywords": ["kipper", "example"],
        "license": "GPL-3.0-or-later",
        "dependencies": {
            "@kipper/cli": "latest" // <-- Add this line to your dependencies (choose latest, next or a specific version)
        }
    }

    Global Installation

    If you intend to only try out Kipper or use a specific version across your entire system, you can also simply install the CLI package globally:

    npm install -g @kipper/cli

    Important

    If possible avoid installing Kipper globally if you intend to use it inside your own projects, as it can cause issues with locally installed versions (node project dependencies). For a localised and project-dependent kipper installation add kipper to your dependencies as shown previously.

    Post Installation

    After finishing the installation, try to run the following command:

    kipper --version

    If the identifier kipper is not found, try to run Kipper using your project's package manager. For example, if you are using npm, you can run the following code:

    npx kipper

    Important

    Note that some shells may not recognise the `kipper` command even after reloading your shell and/or path variable. In that case please stick to your package manager and invoke `kipper` that way, so for example always use npx kipper instead of just kipper

    Setting up a new project with kipper new

    To create a new Kipper project using the CLI, you can use the Kipper project setup wizard. This will create a new project directory with the necessary files and folders for a Kipper project.

    To create a new project, run the following command:

    kipper new

    You may specify a location, but if not specified, the project will be created in the current working directory.

    Importing Kipper as a module

    To set up Kipper for your personal code, simply add @kipper/core or kipper (also includes the Kipper CLI) to your project dependencies or development dependencies in your package.json file.

    Example package.json:

    {
        "name": "example",
        "version": "0.1.0",
        "description": "An example program using Kipper",
        "keywords": ["kipper", "example"],
        "license": "GPL-3.0-or-later",
        "dependencies": {
            "@kipper/core": "latest" // <-- Add this line to your dependencies (choose latest, next or a specific version)
        }
    }

    Afterwards, you can include the @kipper/core package in your JavaScript or TypeScript file. This package contains the full Kipper Compiler and API, which can be customised according to your needs.

    Kipper is shipped as a Commonjs module and can therefore be imported using require() in Javascript or import in TypeScript.

    Example

    Using JavaScript:

    const fs = require("fs").promises;
    const kipper = require("@kipper/core");
    const kipperJS = require("@kipper/target-js");
    
    const path = "YOUR_FILE.kip";
    fs.readFile(path, "utf8").then(async (fileContent) => {
        // Define your own logger and compiler, which will handle the compilation
        const logger = new kipper.KipperLogger((level, msg) => {
            console.log(`[${level}] ${msg}`);
        });
        const compiler = new kipper.KipperCompiler(logger);
    
        // Compile the code string or stream
        let result = await compiler.compile(fileContent, {
            /* Config - Target must always be specified */
            target: new kipperJS.TargetJS(),
        });
        let jsCode = result.write();
    
        // Running the Kipper program
        eval(jsCode);
    });

    Using TypeScript:

    import { promises as fs } from "fs";
    import * as kipper from "@kipper/core";
    import * as kipperJS from "@kipper/target-js";
    
    const path = "YOUR_FILE.kip";
    fs.readFile(path, "utf8" as BufferEncoding).then(async (fileContent: string) => {
        // Define your own logger and compiler, which will handle the compilation
        const logger = new kipper.KipperLogger((level, msg) => {
            console.log(`[${level}] ${msg}`);
        });
        const compiler = new kipper.KipperCompiler(logger);
    
        // Compile the code string or stream
        let result = await compiler.compile(fileContent, {
            /* Config - Target must always be specified */
            target: new kipperJS.TargetJS(),
        });
        let jsCode = result.write();
    
        // Running the Kipper program
        eval(jsCode);
    });