View on GitHub


A toy programming language.

toy.h - A Toy Programming Language

If you’re looking how to use Toy directly, try Otherwise, this header may help learn how Toy works internally.


These headers define a bunch of useful macros, based on what platform you build for.

The most important macro is TOY_API, which specifies functions intended for the end user.

Core Pipeline

From source to execution, each step is as follows:

source   -> lexer       -> token
token    -> parser      -> AST
AST      -> compiler    -> bytecode
bytecode -> interpreter -> result

I should note that the parser -> compiler phase is actually made up of two steps - the write step and the collate step. See Toy_compileString() in repl/repl_tools.c for an example of how to compile properly.

Building Block Structures

Literals represent any value within the language, including some internal ones that you never see.

Literal arrays are contiguous arrays within memory, and are the most heavily used structure in Toy.

Literal dictionaries are unordered key-value hashmaps, that use a running strategy for collisions.

Other Components

You probably won’t use these directly, but they’re a good learning opportunity.

Toy_Scope holds the variables of a specific scope within Toy - be it a script, a function, a block, etc. Scopes are also where the type system lives at runtime. They use identifier literals as keys, exclusively.

Toy_RefString is a utility class that wraps traditional C strings, making them less memory intensive and faster to copy and move. In reality, since strings are considered immutable, multiple variables can point to the same string to save memory, and you can just create a new one of these vars pointing to the original rather than copying entirely for a speed boost. This module has it’s own memory allocator system that is plugged into the main memory allocator.

Toy_RefFunction acts similarly to Toy_RefString, but instead operates on function bytecode.