README.md
1# Minilang is a small extensible scripting language for embedding in C/C++ applications
2
3Minilang is a simple language designed to be embedded into C/C++ applications with minimal fuss and maximum effect.
4
5## Key Features
6
7Minilang was designed from the ground up to be embedded into C/C++ applications. As a result, it has a rich API for embedding that support a wide range of use cases.
8
9### Minimal Dependencies
10
11Minilang only has one required dependency, the [Hans-Boehm conservative garbage collector](https://github.com/ivmai/bdwgc), which is commonly available in the standard repositories of most Linux distributions, in Homebrew on macOS and easily built from source.
12
13### Code Safety
14
15Minilang's VM is safe, there is no way to access raw memory to perform unsafe type-casting, indexing operations are bounds checked, arguments to internal functions are type-checked, etc. Minilang only provides core functionality by default, and does not provide file or network functions, module loading, or any other potentially unsafe functions.
16
17### Extensible
18
19Although Minilang's core functionality is intentionally restricted, functionality can be easily added by the host application, either globally or each time Minilang code is loaded. For example, there is no built-in `print()` function, one must be added by the host application. This extra step means that the `print()` function can write to a file or log instead if desired, or even send text across a websocket to display in a browser.
20
21### Flexible Code Loading
22
23The C API provides functions for incremental source code loading, allowing Minilang to be used for interactive sessions such as REPL shells and notebooks as well as loading complete Minilang code from files, databases, etc.
24
25### Source Level Debugging
26
27The C API also provides features for source level debugging of Minilang code. The host application can specify a debugger when running any function and the VM will invoke the debugger at breakpoints, errors, etc. The debugger API is flexible, debugging can be implementing in a console, desktop GUI or even across a network.
28
29### Stackless Execution and One-Shot Continuations
30
31Minilang uses a stackless VM for execution. Moreover, every function call passes the calling state to the called function, returns are implemented by resuming the calling state. This provides a number of additional features:
32
33* **Inline Asynchronous Calls** Any Minilang function call can be asynchronous without any change in the calling code.
34* **Parallel Asynchronous Calls** Multiple asynchronous calls can also be launched in parallel, with the calling state resumed automatically when all the calls have completed. Minilang is thus suitable for scripting complex workflows in distributed applications.
35* **Preemptive Multitasking** Minilang can optionally use a scheduler to swap the running VM state.
36
37### Per-Context Settings
38
39Every Minilang state has an associated context which is inherited by default from the calling state but can be explicitly set by the host application. The context stores local settings such as the current debugger, preemptive scheduler, etc. The host application can register additional context settings.
40
41### Multi-tenant Support
42
43Combining all of the above features, Minilang is ideal for multi-tenant distributed applications.
44
45## History
46
47Minilang was originally designed for [Rabs](https://github.com/wrapl/rabs), an imperative
48parallel build system. As result, it was designed with the following requirements:
49
50* **Minimal dependencies:** Minilang only has one required dependency, the [Hans-Boehm conservative garbage collector](https://github.com/ivmai/bdwgc), which is commonly available in the standard repositories of most Linux distributions, in Homebrew on macOS and easily built from source.
51* **Allow callbacks for identifier lookups:** This allows build functions in Rabs to use dynamic (context aware) scoping.
52* **Easy to add functions in C:** It is easy to add new functions to Minilang as required.
53* **Easy to store Minilang objects in C:** References to build functions can be easily stored and called when required.
54* **Full support for closures:** Closures (functions which capture their surrounding scope) make complex build functions simpler to write and store.
55* **Closures are hashable:** Checksums can be computed for Minilang functions (using SHA256) in order to check if a target needs to be rebuilt.
56
57Additional features have been added since the original use in Rabs.
58
59* **Configurable builds** Minilang can be built with Rabs (as well as Make) enabling several optional features as desired.
60* **Module system** Minilang files can be loaded as modules, with imports and exports.
61* **Gnome introspection suppport** Minilang can be built with support for Gnome introspection, providing automatic bindings for a wide range of libraries including GUI, networking, etc.
62* **Continuation based implementation** Function calls are implemented using one-short continuation based approach. This adds (optional) support for the following:
63 - **Asynchronous calls**
64 - **Cooperative multitasking**
65 - **Preemptive multitasking**
66
67## Simple example
68
69> example1.c
70
71```c
72#include <stdio.h>
73#include <minilang/minilang.h>
74
75static ml_value_t *print(void *Data, int Count, ml_value_t **Args) {
76 ml_value_t *StringMethod = ml_method("string");
77 for (int I = 0; I < Count; ++I) {
78 ml_value_t *Result = Args[I];
79 if (Result->Type != MLStringT) {
80 Result = ml_simple_call(StringMethod, 1, &Result);
81 if (Result->Type == MLErrorT) return Result;
82 if (Result->Type != MLStringT) return ml_error("ResultError", "string method did not return string");
83 }
84 fwrite(ml_string_value(Result), 1, ml_string_length(Result), stdout);
85 }
86 fflush(stdout);
87 return MLNil;
88}
89
90int main(int Argc, char **Argv) {
91 ml_init();
92 stringmap_t *Globals = stringmap_new();
93 stringmap_insert(Globals, "print", ml_cfunction(NULL, print));
94 ml_value_state_t *State = ml_value_state_new(NULL);
95 ml_load_file((ml_state_t *)State, (ml_getter_t)stringmap_search, Globals, "example1.mini", NULL);
96 if (State->Value->Type == MLErrorT) {
97 ml_error_print(State->Value);
98 exit(1);
99 }
100 ml_call((ml_state_t *)State, State->Value, 0, NULL);
101 if (State->Value->Type == MLErrorT) {
102 ml_error_print(State->Value);
103 exit(1);
104 }
105}
106```
107
108> example1.mini
109
110```lua
111for X in 1 .. 10 do
112 print('{X} ')
113end
114print('done.\n')
115```
116
117> output
118```sh
119$ gcc -o example1 example1.c -lminilang -lgc
120$ ./example1
1211 2 3 4 5 6 7 8 9 10 done.
122$
123```
124
125## Building
126
127### Using make
128
129```console
130$ git clone https://github.com/wrapl/minilang
131$ cd minilang
132$ make -j4
133$ make install PREFIX=/usr/local
134```
135
136This will build and install a vanilla version of Minilang in `PREFIX`.
137
138### Using Rabs
139
140```console
141$ git clone https://github.com/wrapl/minilang
142$ cd minilang
143$ rabs -p4 -DPREFIX=/usr/local install
144```
145
146This will build and install a vanilla version of Minilang in `PREFIX`.
147
148Additional options can be enabled when building Minilang with Rabs. For example, to enable GTK+ support, pass `-DGTK` when building.
149
150```console
151$ rabs -p4 -DPREFIX=/usr/local -DGTK install
152```
153
154Currently the following optional features are available:
155
156| Build Flags | Description |
157| --- | --- |
158| `-DMATH` | Adds additional maths functions, including multi-dimensional numeric arrays |
159| `-DGTK` | Adds Gnome introspection support |
160| `-DCBOR` | Adds support for serializing and deserializing Minilang values to/from CBOR |
161| `-DSCHEDULER` | Adds support for preemptive multitasking |
162| `-DMODULES` | Adds support for loading Minilang files as modules. Enables `-DSCHEDULER` |
163| `-DASM` | Uses assembly code implementations for certain features on supported platforms |
164| `-DTABLES` | Adds a table type (similar to a dataframe, datatable, etc). Enables `-DMATH` |
165| `-DQUEUES` | Adds a priority queue type |
166
167## Documentation
168
169Full documentation can be found [here](https://minilang.readthedocs.io).