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

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.

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:

• Using top-level await (Not supported in all browsers):

<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",
    "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

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

Also, make sure to try and run a Kipper file after the installation to ensure the Kipper compiler and Node runtime are fully working:

• Use run and directly execute:

  kipper run main.kip

• Or use compile and invoke node (or ts-node if the target is ts)

  kipper compile main.kip --target=js
  node ./build/main.js

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",
    "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);
});