--- title: adaengine/gravity-lang framework: Swift Package Catalog role: article path: packages/adaengine/gravity-lang --- # adaengine/gravity-lang **Gravity** is a powerful, dynamically typed, lightweight, embeddable programming language written in C without any external dependencies (except for stdlib). It is a class-based concurrent scripting language with modern Swift-like syn ## What Gravity code looks like ```swift class Vector { // instance variables var x = 0; var y = 0; var z = 0; // constructor func init (a = 0, b = 0, c = 0) { x = a; y = b; z = c; } // instance method (built-in operator overriding) func + (v) { if (v is Int) return Vector(x+v, y+v, z+v); else if (v is Vector) return Vector(x+v.x, y+v.y, z+v.z); return null; } // instance method (built-in String conversion overriding) func String() { // string interpolation support return "[\(x),\(y),\(z)]"; } } func main() { // initialize a new vector object var v1 = Vector(1,2,3); // initialize a new vector object var v2 = Vector(4,5,6); // call + function in the vector object var v3 = v1 + v2; // returns string "[1,2,3] + [4,5,6] = [5,7,9]" return "\(v1) + \(v2) = \(v3)"; } ``` ## Features * multipass compiler with optimizer * dynamic typing * classes and inheritance * higher-order functions and classes * lexical scoping * coroutines (via fibers) * nested classes * closures * garbage collection (mark-and-sweep) * operator overriding * string interpolation * enums, modules, and structs (value types) * switch/case and ranges * optional modules (Math, File, JSON, ENV) * powerful embedding API with bridging support * built-in unit tests * built-in JSON serializer/deserializer * **optional semicolons** ## Building **Make (Linux / macOS / BSD)** ```bash make # Build the gravity CLI executable make mode=debug # Debug build with symbols make lib # Build shared library (libgravity.dylib/so/dll) make staticlib # Build static library (libgravity.a) make example # Build the C embedding API example make clean # Clean all build artifacts ``` **CMake (cross-platform, including Windows)** ```bash cmake -B build cmake --build build cmake -B build -DBUILD_CLI=OFF cmake --build build ``` Requires a C99 compiler. No external dependencies. ## Usage ```bash ./gravity file.gravity # Compile and execute a source file ./gravity -c file.gravity # Compile to bytecode (outputs gravity.g) ./gravity -o out.json -c file.gravity # Compile to a specific output file ./gravity -x gravity.g # Execute precompiled bytecode ./gravity -i 'return 2 + 3' # Execute inline code ./gravity -t test/unittest # Run unit tests ``` ## Testing ```bash ./gravity -t test/unittest # Run all unit tests via the VM ./test/unittest/run_all.sh # Run all unit tests via shell script (with per-test timeouts) ./gravity test/unittest/somefile.gravity # Run a single test file ``` The `test/` directory also contains `fuzzy/` (randomised fuzzing inputs) and `infiniteloop/` (tests that must terminate with a runtime error rather than hang). ## Project Structure ``` src/ ├── cli/ Command-line interface ├── compiler/ Lexer, parser, AST, semantic analysis, IR, optimizer, codegen ├── runtime/ Stack-based VM, built-in types and core methods ├── shared/ Value representation, opcodes, hash table, array, memory/GC ├── optionals/ Optional modules: Math, File, JSON, ENV └── utils/ Debug disassembler, JSON serialization, file I/O, UTF-8 ``` For a comprehensive technical deep-dive into the implementation, see [ARCHITECTURE.md](ARCHITECTURE.md). ## Embedding API Gravity is designed to be embedded inside a host application. The complete API lives in `src/runtime/gravity_vm.h` and `src/compiler/gravity_compiler.h`. A minimal example: ```c #include "gravity_compiler.h" #include "gravity_core.h" #include "gravity_vm.h" static void report_error(gravity_vm *vm, error_type_t type, const char *description, error_desc_t desc, void *xdata) { printf("%s\n", description); } int main(void) { const char *source = "func main() { return 6 * 7; }"; gravity_delegate_t delegate = {.error_callback = report_error}; // compile gravity_compiler_t *compiler = gravity_compiler_create(&delegate); gravity_closure_t *closure = gravity_compiler_run(compiler, source, strlen(source), 0, true, true); // create VM and transfer compiler-owned objects into it gravity_vm *vm = gravity_vm_new(&delegate); gravity_compiler_transfer(compiler, vm); gravity_compiler_free(compiler); // execute and read result if (gravity_vm_runmain(vm, closure)) { gravity_value_t result = gravity_vm_result(vm); gravity_value_dump(vm, result, NULL, 0); // prints: 42 } gravity_vm_free(vm); gravity_core_free(); return 0; } ``` See [`examples/example.c`](examples/example.c) and the [embedding documentation](https://gravity-lang.org) for the full bridging API. ## Special thanks Gravity was supported by a couple of open-source projects. The inspiration for closures comes from the elegant Lua programming language; specifically from the document Closures in Lua. For fibers, upvalues handling and some parts of the garbage collector, my gratitude goes to Bob Nystrom and his excellent Wren programming language. A very special thanks should also go to my friend **Andrea Donetti** who helped me debugging and testing various aspects of the language. ## Documentation The Getting Started page is a guide for downloading and compiling the language. There is also a more extensive language documentation. Official [wiki](https://github.com/marcobambini/gravity/wiki) is used to collect related projects and tools. For implementation internals, see the [Architecture Document](ARCHITECTURE.md). ## Where Gravity is used * Gravity is the core language built into Creo (https://creolabs.com) * Gravity is the scripting language for the Untold game engine (https://youtu.be/OGrWq8jpK14?t=58) ## Changelog See [CHANGELOG.md](CHANGELOG.md) for a summary of changes across versions. ## Community [![GitHub Discussions](https://img.shields.io/badge/discussions-GitHub-blue)](https://github.com/marcobambini/gravity/discussions) Questions, ideas, and general discussion are welcome in [GitHub Discussions](https://github.com/marcobambini/gravity/discussions). ## Contributing Contributions to Gravity are welcomed and encouraged!
More information is available in the official [CONTRIBUTING](CONTRIBUTING.md) file. * Open an issue: * if you need help * if you find a bug * if you have a feature request * to ask a general question * Submit a pull request: * if you want to contribute ## License Gravity is available under the permissive MIT license. ## Package Metadata Repository: adaengine/gravity-lang Default branch: master README: README.md