The Ape Programming Language

Try Ape in your browser on Ape Playground.

About

Ape is an easy to use programming language and library written in C, by Krzysztof Gabis. It's an offspring of Monkey language (from Writing An Interpreter In Go and Writing A Compiler In Go books by Thorsten Ball), but it evolved to be more procedural with variables, loops, operator overloading, modules, and more.

Current state

It's under development so everything in the language and the api might change.

Example

fn contains_item(to_find, items) {
    for (item in items) {
        if (item == to_find) {
            return true
        }
    }
    return false
}

const cities = ["Warszawa", "Rabka", "Szczecin"]
const city = "Warszawa"
if (contains_item(city, cities)) {
    println(`found ${city}!`)
}

Installation

Run:

$ npm i apelang.c

And then include ape.h as follows:

#include "node_modules/apelang.c/ape.h"

You may also want to include ape.c as follows:

#ifndef __APELANG_C__
#define __APELANG_C__
#include "node_modules/apelang.c/ape.c"
#endif

This will include both the function declaration and their definitions into a single file.

Embedding

Add ape.h and ape.c to your project and compile ape.c with a C compiler before linking.

#include "ape.h"

int main() {
    ape_t *ape = ape_make();
    ape_execute(ape, "println(\"hello world\")");
    ape_destroy(ape);
    return 0;
}

An example that shows how to call Ape functions from C code and vice versa can be found here.

Language

Ape is a dynamically typed language with mark and sweep garbage collection. It's compiled to bytecode and executed on internal VM. It's fairly fast for simple numeric operations and not very heavy on allocations (custom allocators can be configured). More documentation can be found here.

Basic types

bool, string, number (double precision float), array, map, function, error

Operators

Math:
+ - * / %

Binary:
^ | & << >>

Logical:
! < > <= >= == != && ||

Assignment:
= += -= *= /= %= ^= |= &= <<= >>=

Defining constants and variables

const constant = 2
constant = 1 // fail
var variable = 3
variable = 7 // ok

Strings

const str1 = "a string"
const str2 = 'also a string'
const str3 = `a template string, it can contain expressions: ${2 + 2}, ${str1}`

Arrays

const arr = [1, 2, 3]
arr[0] // -> 1

Maps

const map = {"lorem": 1, 'ipsum': 2, dolor: 3}
map.lorem // -> 1, dot is a syntactic sugar for [""]
map["ipsum"] // -> 2
map['dolor'] // -> 3

Conditional statements

if (a) {
    // a
} else if (b) {
    // b
} else {
    // c
}

Loops

while (true) {
    // body
}

var items = [1, 2, 3]
for (item in items) {
    if (item == 2) {
        break
    } else {
        continue
    }
}

for (var i = 0; i < 10; i++) {
    // body
}

Functions

const add_1 = fn(a, b) { return a + b }

fn add_2(a, b) {
    return a + b
}

fn map_items(items, map_fn) {
    const res = []
    for (item in items) {
        append(res, map_fn(item))
    }
    return res
}

map_items([1, 2, 3], fn(x){ return x + 1 })

fn make_person(name) {
    return {
        name: name,
        greet: fn() {
            println(`Hello, I'm ${this.name}`)
        },
    }
}

Errors

const err = error("something bad happened")
if (is_error(err)) {
    println(err)
}

fn() {
    recover (e) { // e is a runtime error wrapped in error
        return null
    }
    crash("something bad happened") // crashes are recovered with "recover" statement
}

Modules

import "foo" // import "foo.ape" and load global symbols prefixed with foo::

foo::bar()

import "bar/baz" // import "bar/baz.ape" and load global symbols prefixed with baz::
baz::foo()

Operator overloading

fn vec2(x, y) {
    return {
        x: x,
        y: y,
        __operator_add__: fn(a, b) { return vec2(a.x + b.x, a.y + b.y)},
        __operator_sub__: fn(a, b) { return vec2(a.x - b.x, a.y - b.y)},
        __operator_minus__: fn(a) { return vec2(-a.x, -a.y) },
        __operator_mul__: fn(a, b) {
            if (is_number(a)) {
                return vec2(b.x * a, b.y * a)
            } else if (is_number(b)) {
                return vec2(a.x * b, a.y * b)
            } else {
                return vec2(a.x * b.x, a.y * b.y)
            }
        },
    }
}

Splitting and joining

ape.c can be split into separate files by running utils/split.py:

python3 utils/split.py --input ape.c --output-path ape

It can be joined back into a single file with utils/join.py:

python3 utils/join.py --template utils/ape.c.templ --path ape --output ape.c

Visual Studio Code extension

A Visual Studio Code extension can be found here.

My other projects

• parson - JSON library
• kgflags - command-line flag parsing library
• agnes - header-only NES emulation library

License

The MIT License (MIT)