Quickstart Copy Section

Getting started Copy Chapter

Install Copy Section

git clone https://github.com/marcobambini/gravity.git
	cd gravity
	make

If you want to access the gravity compiler globally just add it to your PATH.

Configure your editor Copy Section

Command line Copy Section

./gravity --help

To compile a gravity file to a exec.json executable:

./gravity -c myfile.gravity -o exec.json

To execute a precompiled json executable file:

./gravity -x exec.json

To directly execute a gravity file (without first serializing it to json):

./gravity myfile.gravity

Unit Tests Copy Section

./gravity -t path_to_test_folder

Hello World Copy Section

func main() {
		System.print("Hello World!")
	}

---

README Copy Section

<p align="center">
<img src="assets/images/logo.png" height="90px" alt="Gravity Programming Language" title="Gravity Programming Language">
</p>

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 a modern Swift like syntax.

Gravity supports procedural programming, object-oriented programming, functional programming and data-driven programming. Thanks to special built-in methods, it can also be used as a prototype-based programming language.

Gravity has been developed from scratch for the Creo project in order to offer an easy way to write portable code for the iOS and Android platforms. It is written in portable C code that can be compiled on any platform using a C99 compiler. The VM code is about 4K lines long, the multipass compiler code is about 7K lines and the shared code is about 3K lines long. The compiler and virtual machine combined, add less than 200KB to the executable on a 64 bit system.

Comments in the C code make it easy to read and understand.

What Gravity code looks like Copy Chapter

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 Copy Chapter

---

Coverpage Copy Section

<p align="center">
<img src="assets/images/logo.png" height="90px" alt="Gravity Programming Language" title="Gravity Programming Language">
</p>

Gravity <small>0.8.0</small>

An embeddable programming language.

* Simple and lightweight
* No external dependencies
* Register based virtual machine

GitHub
Get Started

---

Sidebar Copy Section

* INTRODUCTION

* Overview
* Getting Started

* LANGUAGE GUIDE

* Syntax
* Operators
* Types
* Object
* Int
* Float
* String
* Bool
* Null
* List
* Map
* Enum
* Range
* Function
* Closure
* Class
* Control Flow
* Loops
* Fibers

* OPTIONALS

* System class
* Math class
* File class
* ENV class

* ADVANCED

* Embedding
* Extending
* Introspection
* Unit test
* Contributing

---

Bool Copy Section

Bool Copy Section

The Bool data type can have only two values, they are the literals true and false. A Bool value expresses the validity of a condition (tells whether the condition is true or false).

var a = true;
	var b = false;

---

Class Copy Section

Class Copy Chapter

Every value in Gravity is an object, and every object is an instance of a class. Classes define an object's behavior and state. Behavior is defined by methods which live in the class. Every object of the same class supports the same methods. State is defined in fields, whose values are stored in each instance.<br><br>Like functions a Class is a first class object, that means that it can be stored in local variables (even in Lists or Maps), passed as a function parameter or returned by a function. Gravity supports nested classes and single inheritance.

Defining a class Copy Section

class Italy {
	}

Instantiate a class Copy Section

var instance = Italy();

Methods Copy Section

class Italy {
		func print() {
			System.print("Hello from Italy");
		}
	}

Properties Copy Section

class Italy {
		var population = 60656000;
		var area = 301340; // in km2
		func density() {
			return population/area;
		}
	}
	func main() {
		var it = Italy();
		return it.density();	// returns 201
	}

Class methods and properties Copy Section

class Italy {
		static var population = 60656000;
		static var area = 301340; // in km2
		static func density() {
			return population/area;
		}
	}
	func main() {
		return Italy.density();
	}

Class constructors and destructors Copy Section

Class destructors get called when the object gets deleted/goes out of scope.
To add a destructor to your class, create a method called deinit().

class MyClass {
  private var _value;
  // Constructor - called when the class is instantiated
  func init(value) {
    System.print("MyClass instantiated with value: " + value);
    _value = value;
  }
  // Destructor - Called when the object instance of this class is destroyed/goes out of scope.
  func deinit() {
    System.print("MyClass instance deinitialized");
  }
}
func main() {
  // Instantiate MyClass
  var instance = MyClass("Hello, World!");
}

Getters and Setters: Copy Section

class foo {
		private var _a = 12;
		var a {
			set {_a = value * 100;} // value is default parameter name
			get {return _a/2;}
		};
		var b {
			// in this case b is a write-only property
			set (newb) {_a = newb * 50;}	// parameter name can be specified
		};
	}
	func main() {
		var f = foo();
		f.a = 14;       // 14*100 = 1400
		return f.a;     // 1400/2 = 700
	}

Adding methods at runtime: Copy Section

class foo {
		func f1() {System.print("Hello from f1");}
	}
	func main() {
		var obj = foo();
		obj.f1();	// Output: Hello from f1
		// add a new f2 method to obj instance
		obj.bind("f2", {System.print("Hello from f2");});
		obj.f2();	// Output: Hello from f2
		// replace f1 method
		obj.bind("f1", {System.print("Hello from f1 new");});
		obj.f1();	// Output: Hello from f1 new
		// with unbind you can remove an existing method
		obj.unbind("f2");
		obj.f2();	// RUNTIME ERROR: Unable to find f2
	}

Nested classes: Copy Section

class Database {
		public var query;
		class RecordSet {
			public var sql;
			public func run() {
				if (!sql) return 0;
				System.print(sql);
				return sql.length();
			}
			func init() {
				System.print("RecordSet init called");
			}
		}
		func init() {
			System.print("Database init called");
			query = RecordSet();
		}
	}
	func main() {
		var db = Database();
		db.query.sql = "Hello World from Gravity!";
		return db.query.run();
	}

Inheritance Copy Section

class Bird {
		func talk() {
			System.print("Cheep")
		}
	}
	class Owl : Bird {
		func talk() {
			System.print("Hoot")
		}
	}
	func main() {
		var bird = Bird()
		bird.talk() // Output: Cheep
		var owl = Owl()
		owl.talk() // Output: Hoot
	}

Access specifiers Copy Section

---

Closure Copy Section

Closure Copy Chapter

Closures are self-contained blocks of functionality that can be passed around and used in your code. Closures can capture and store references to any constants and variables from the context in which they are defined. Closures can be nested and can be anonymous (without a name):

func f1(a) {
		return func(b) {
			return a + b;
		}
	}
	func main() {
		var addTen = f1(10);
		return addTen(20);	// result is 30
	}

Disassemble Copy Section

func sum (a,b) {
		return a + b;
	}
	func main() {
		System.print(sum.disassemble());
	}
	// Output:
	// 000000 ADD 3 1 2
	// 000001 RET 3

---

Contrib Copy Section

Contributing Copy Chapter

If you find any grammatical issue, please report it using Github Issues. Or, if some sentence or paragraph is difficult to understand, feel free to make a pull request. This manual is in active development and I'll regularly update and improve it. I am not a native English speaker so feel free to correct me if something is not properly written.<br><br>If you have any question related to the material or the development of the language, feel free to open a GitHub issue or to contact me.

About me Copy Section

---

Controlflow Copy Section

Control flow Copy Chapter

Gravity provides a variety of control flow statements. Control flow is used to determine which chunks of code are executed and how many times. Branching statements and expressions decide whether or not to execute some code and looping ones execute something more than once.

If statement Copy Section

var counter = 30;
			if (counter <= 10) {
				// do something here
			}

The if statement can provide an alternative set of statements, known as an else clause, for situations when the if condition is false. These statements are indicated by the else keyword:

var counter = 30;
			if (counter <= 10) {
				// do something here
			} else {
				// do something else here
			}

More complex if statement:

var counter = 30;
			if (counter <= 10) {
				// do something here
			} else if (counter <= 20) {
				// do something else here
			} else {
				// do something else here
			}

---

Embedding Copy Section

Embedding Copy Chapter

Gravity can be easily embedded into any C/C++ code. Suppose to have the following Gravity code:

func sum (a, b) {
    return a + b
}
func mul (a, b) {
    return a * b
}
func main () {
    var a = 10
    var b = 20
    return sum(a, b) + mul(a, b)
}

To keep the code as simple as possible I skipped any error check condition that would be required. The bare minimum C code to embed the above Gravity code would be:

/ Detailed source-code truncated for AI context efficiency. /

To load and execute a myfile Gravity source code from disk the required changes would be minimum:

int main (void) {
    size_t size = 0;
    const char *source_code = file_read("myfile.gravity", &size);
    
    ...
    
    // compile Gravity source code into bytecode (embedded into a closure)
    // notice the change of the is_static bool parameter to false
    gravity_closure_t *closure = gravity_compiler_run(compiler, source_code, size, 0, false, true);
    
    ...
}

To directly execute the mul Gravity function and pass some parameter from C to Gravity some minor changes need to be performed:

/ Detailed source-code truncated for AI context efficiency. /

---

Enum Copy Section

Enum Copy Chapter

Enums defines a common type for a group of related values. If you are familiar with C, you will know that C enumerations assign related names to a set of integer values. Enums in Gravity are much more flexible and enable you to assign any literal value (Int, Float, String, Bool):

enum state {
		nothing,                // default to 0
		active,                 // default to 1
		inactive,               // default to 2
		undetermined = 666,
		error                   // 667
	}
	enum math {
		pi = 3.141592,
		e = 2.718281,
		goldratio = 1.618033
	}
	enum company {
		ceo = "Gauss",
		cto = "Eurel",
		cfo = "Nostradamus"
	}
	enum mixed {
		one = "Hello World",
		two = 3.1415,
		three = 666,
		four = true
	}
	func main() {
		var a = state.active;    // a = 1
		var b = math.pi;         // b = 3.1415
		var c = company.ceo;     // c = "Gauss"
		var d = mixed.four;      // d = true
	}

Enum is a static operator, which means that at compile time the real value of the enum item is automatically replaced by Gravity.

---

Env Copy Section

ENV Copy Chapter

Class methods Copy Section

// read an env variable
var value = ENV.get("VAR_NAME")
// write an env value
ENV.set("VAR_KEY", "VAR_VALUE")
// list all env variables
var list = ENV.keys()

Class Constants Copy Section

var max_arg = ENV.argc - 1 
var my_arg = ENV.argv[max_arg]

---

Extending Copy Section

Extending Gravity Copy Chapter

Gravity can be extended at runtime using the C API (please read the Embedding section before proceeding).

Three steps are required:
1. Create a new class
2. Add methods and properties to the class
3. Register this class inside the VM

In this simple example we'll create a "Foo" class with a "sum" method in C and then we'll execute it from Gravity.

/ Detailed source-code truncated for AI context efficiency. /

---

Fiber Copy Section

Fiber Copy Chapter

func main() {
		var fiber = Fiber.create({
			System.print("fiber 1");
			Fiber.yield()
			System.print("fiber 2");
		});
		System.print("main 1");
		fiber.call()
		System.print("main 2");
		fiber.call()
		System.print("main 3");
	}
	// Output:
	// main 1
	// fiber 1
	// main 2
	// fiber 2
	// main 3

A Fiber is created with create:

Fiber.create( {
		System.print("\(self) is the current fiber")
	})

var closure = {
    System.print("1")
    Fiber.yield()
    System.print("2")
    Fiber.yield()
    System.print("3")
    Fiber.yield()
    System.print("Done")
}
var fiber = Fiber.create(closure)
fiber.call()
// prints 1
fiber.call()
// prints 2
fiber.call()
// prints 3
fiber.call()
// prints Done
System.print(fiber.isDone())
// prints true

There are 2 types of yield:
1. Fiber.yield() it returns the controll to the function calling call()
2. Fiber.yieldWaitTime(seconds) it returns the controll to the function calling call() and also store the current time internally.

The later enable a call check of the total time in seconds passed since last call(). If the time amount is not enough the call is void and the fiber is not entered.

Example:

To implement a function that do some stuff every second, like a timer, a way is to use Fiber.yieldWaitTime(seconds)

var fiber = Fiber.create({
  var keepGoing = true
  while (keepGoing) {
    keepGoing = doSomeStuff()
    Console.write("Waiting")
    Fiber.yieldWaitTime(1.0)
    Console.write("Elapsed time: \(self.elapsedTime())")
  }
})
...
// Note: this strict loop is just for reference, not a real case.
while (!fiber.isDone()) {
  fiber.call()
}

---

File Copy Section

File Copy Chapter

Class methods example Copy Section

func main() {
  var target_file = "FULL_PATH_TO_A_TEXT_FILE_HERE";
  var target_folder = "FULL_PATH_TO_A_FOLDER_HERE";
  // FILE TEST
  var size = File.size(target_file);
  var exists = File.exists(target_file);
  var is_dir = File.is_directory(target_file);
  var data = File.read(target_file);
	 
  System.print("File: " + target_file);
  System.print("Size: " + size);
  System.print("Exists: " + exists);
  System.print("Is Directory: " + is_dir);
  System.print("Data: " + data);
	 
  // FOLDER TEST
  func closure (file_name, full_path, is_directory) {
    if (is_directory) {
      System.print("+ \(file_name)");
    } else {
      System.print("    \(file_name)");
    }
  }
	 
  var recursive = true;
  var n = File.directory_scan(target_folder, recursive, closure);
	 
  // return the number of file processed
  return n;
}

Read/write buffer example Copy Section

func main() {
  var target_file = "FULL_PATH_TO_A_TEXT_FILE_HERE";
  // WRITE TEST
  // 2nd argument to open is the same as the mode argument to the fopen function
  // https://pubs.opengroup.org/onlinepubs/009695399/functions/fopen.html
  var f = File.open(target_file, "w+");
  f.write("This is the first line\n");
  f.write("This is the second line\n");
  f.write("This is the third line\n");
  f.close();
  // READ TEST
  f = File.open(target_file, "r");
  var data = f.read(40);
  f.close();
  return data;
}

Read line example Copy Section

func main() {
    var target_file = "FULL_PATH_TO_A_TEXT_FILE_HERE";
    var f = File.open(target_file, "w+");
    
    f.write("This is the first line\n");
    f.write("This is the second line\n");
    f.write("This is the third line\n");
    
    f.close();
    
    f = File.open(target_file, "r");
    while (!f.isEOF()) {
        var line = f.read("\n");
        System.print(line);
    }
    
    f.close();
    
    return 0;
}

---

Float Copy Section

Float Copy Section

In most dynamically typed programming language both Integers and Float are internally represented by a C double value.

In a modern 64bit system, this implementation leads to some issue because some integer values cannot be correctly represented by a double value (for more details please read Storage of integer values in double).

In Gravity Int and Float are internally represented by two different types to mitigate rounding errors.

An Float represents a 64 bit floating point number (can optionally be compiled as 32 bit floating point number):

var a = 3.1415;   // float
	var b = 1.25e2;   // scientific notation
	var f = 30.5.radians  // returns the result of converting 30.5 degrees to radians
	var f = 3.14.degrees. // returns the result of converting 3.14 radians to degrees

The Float class exposes also a min/max property used to know at runtime lower/upper bound values:

var min = Float.min;    // 2.22507e-308 in 64bit systems
	var max = Float.max;    // 1.79769e+308 in 64bit systems

Other useful methods:

var f = 3.1415;       // float
	var f1 = f.ceil();    // result is 4 (ceil computes the smallest integer value not less than f)
	var f2 = f.round();   // result is 3 (round computes the nearest integer value to f)
	var f3 = f.floor();   // result is 3 (floor computes the largest integer value not greater than f)

---

Func Copy Section

Function Copy Chapter

Functions are first class objects like Int or String and can be stored in local variables (even in Lists or Maps), passed as function parameters or returned by a function. Functions can be implemented in Gravity or in a native language with calling conventions compatible with ANSI C.<br><br>Functions are called by value. This means that foo(1) calls the function which is the value of the variable foo. Calling a value that is not a function (or does not implement the exec method) will raise a runtime error.

func main() {
		var a = 10;
		var b = 20;
		return a + b;
	}

func f1() {
		return 10;
	}
	func f2() {
		return f1;
	}
	func main() {
		// a is now function f2
		var a = f2;
		// b is now the return value of f2 which is function f1
		var b = a();
		// return value is f1() which is 10
		return b();
		// above code is equivalent to
		return f2()();
	}

Function parameters Copy Section

func sum(a, b) {
		return a + b;
	}
	// execute the sum function
	// and returns 30 as result
	sum(10,20);

If a function is called with missing arguments (less than declared), the missing values are set to undefined.

// sum modified to take in account missing arguments
	func sum(a, b) {
		// equivalent to if (a == undefined) a = 30;
		if (!a) a = 30;
		// equivalent to if (b == undefined) b = 50;
		if (!b) b = 50;
		return a + b;
	}
	// execute the sum function without any argument
	// a has a 30 default value and b has a 50 default value
	// return value is 80
	sum();

If a function is called with more arguments (more than declared), the additional arguments can be accessed using the _args array.

// sum modified to accept a variable number of arguments
	func sum() {
		var tot = 0;
		for (var i in 0..<_args.count) {
			tot += _args[i];
		}
		return tot;
	}
	// execute the sum function with a variable number
	// of arguments returns 550 as result
	sum(10,20,30,40,50,60,70,80,90,100);

Recursion Copy Section

func fibonacci (n) {
		if (n<2) return n;
		// could be written as return _func(n-2) + _func(n-1)
		return fibonacci(n-2) + fibonacci(n-1);
 	}
	func main() {
		return fibonacci(20);
 	}

Returning values Copy Section

---

Int Copy Section

Int Copy Section

In most dynamically typed programming language both Integers and Float are internally represented by a C double value.

In a modern 64bit system, this implementation leads to some issue because some integer values cannot be correctly represented by a double value (for more details please read Storage of integer values in double).

In Gravity Int and Float are internally represented by two different types to mitigate rounding errors.

An Int represents a 64 bit signed number (can optionally be compiled as 32 bit signed number):

var a = 123;        // decimal
	var b = 0xFF;       // hexadecimal
	var c = 0O7777;     // octal
	var d = 0B0101;     // binary
	var e = Int.random(1, 10) // returns a random int between 1 and 10 inclusive
	var f = 30.radians // returns the result of converting 30 degrees to radians
	var f = 3.degrees  // returns the result of converting 3 radians to degrees

An Int can also be used as a convenient way to execute loops:

5.loop() {
		System.print("Hello World");
	}
	// result
	// Hello World
	// Hello World
	// Hello World
	// Hello World
	// Hello World

The Int class exposes a min/max property used to know at runtime lower/upper bound values:

var min = Int.min;    // -9223372036854775808 in 64bit systems
	var max = Int.max;    //  9223372036854775807 in 64bit systems

---

Introspection Copy Section

Introspection Copy Section

Type introspection is a core feature of Gravity. In Gravity, the Object class (ancestor of every class) provides methods for checking the instance's class.

All Objects now responds to the following methods:

Object.introspection();
	Object.methods();
	Object.properties();

Each method support two optional parameters:
* param1 a Bool value (default false), if set to true returns extended information
* param2 a Bool value (default false), if set to true it scan super classes hierarchy
Result can be a List or a Map (in case of param1 set to true).

Examples:

List.introspection();
  // returns: [sort,reduce,loop,sorted,contains,filter,count,reverse,iterate,push,remove,pop,storeat,loadat,reversed,indexOf,next,map,join]
  
  List.introspection(true);
  // returns: [sorted:[isvar:false,name:sorted],next:[isvar:false,name:next],sort:[isvar:false,name:sort],filter:[isvar:false,name:filter],storeat:[isvar:false,name:storeat],map:[isvar:false,name:map],indexOf:[isvar:false,name:indexOf],reversed:[isvar:false,name:reversed],contains:[isvar:false,name:contains],loop:[isvar:false,name:loop],reduce:[isvar:false,name:reduce],count:[isvar:true,name:count,readonly:true],loadat:[isvar:false,name:loadat],iterate:[isvar:false,name:iterate],remove:[isvar:false,name:remove]...

---

List Copy Section

List Copy Chapter

Lists (or arrays) are simple sequence of objects, their size is dynamic and their index starts always at 0. They provide fast random access to their elements. You can create a list by placing a sequence of comma-separated expressions inside square brackets:

var r = [1, 2, "Hello", 3.1415, true];
	// list has a count property
	var n = r.count;	// n is 5

Accessing items Copy Section

var names = ["Mark", "Andrew", "Paul", "Ross", "Frank", "Max"];
	names[0];	// "Mark"
	names[2];	// "Paul"

Negative indices count backwards from the end:

var names = ["Mark", "Andrew", "Paul", "Ross", "Frank", "Max"];
	names[-1];	// "Max"
	names[-2];	// "Frank"

Iterating items Copy Section

var people = ["Mark", "Andrew", "Paul", "Ross", "Frank", "Max"];
	for (var name in people) {
		System.print("Current name is " + name);
	}

Adding items Copy Section

var list = [10,20,30,40,50];
	list[30] = 22;	// list contains now 31 elements (index 0...30)

List as a stack Copy Section

var list = [10,20,30,40,50];
	list.push(100);		// add 100 to the list
	var v1 = list.pop();	// pop 100
	var v2 = list.pop();	// pop 50

List Contains Copy Section

var list = [1, 2, "Hello", 3.1415, true];
	return list.contains(3.1415); // Returns: true

List Join Copy Section

var list = [1,2,3,4,5];
	list.join(" + "); // Becomes: "1 + 2 + 3 + 4 + 5"

List Map Copy Section

var numbers = [1,2,3,4,5,6,7,8,9,10]
  var squared = numbers.map(func(num) {
    return num*num
  })
  // squared is now equal to [1,4,9,16,25,36,49,64,81,100]

List Filter Copy Section

var numbers = [1,2,3,4,5,6,7,8,9,10]
  var even = numbers.filter(func(num) {
    return !(num % 2)
  })
  // even is now equal to [2,4,6,8,10]

List Reduce Copy Section

var numbers = [1,2,3,4,5,6,7,8,9,10]
  var sum = numbers.reduce(0, func(num1, num2) {
    return num1+num2
  })
  // sum is now equal to 55

List Sort Copy Section

var fruits = ["Banana", "Orange", "Apple", "Mango"];
  fruits.sort();
  // fruits is now [Apple,Banana,Mango,Orange]
  
  var numbers = [10, 3.14, 82, 1, 7];
  numbers.sort();
  // numbers is now [1,3.14,7,10,82]
  
  // if you need to customize the sort algorithm you can provide a closure
  func compare (a, b) {
    return (a < b);
  }
  
  var fruits = ["Banana", "Orange", "Apple", "Mango"];
  fruits.sort(compare);
  // fruits is now [Orange,Mango,Banana,Apple]

---

Loop Copy Section

Loop Copy Chapter

While loop</h4> Copy Section

func main() {
		var i = 0;
		while (i < 50000) {
			i += 1;
		}
		return i;
	}

Repeat-while loop</h4> Copy Section

func main() {
		var i = 0;
		repeat {
			i += 1;
		} while (i < 50000);
		return i;
	}

For loop</h4> Copy Section

var count = 0;
	for (var i in 0...40) {
		count += i;
	}
	return count;

Loop method</h4> Copy Section

func main() {
		4.loop({System.print("Hello World");});
	}
	// Output:
	// Hello World
	// Hello World
	// Hello World
	// Hello World

If we need to access the current index of the loop we can just rewrite the closure:

func main() {
		var target = 5;
		target.loop(func (value){System.print("Hello World " + value);});
	}
	// Output:
	// Hello World 0
	// Hello World 1
	// Hello World 2
	// Hello World 3
	// Hello World 4

func main() {
		var target = 0...4;
		target.loop(func (value){System.print("Hello World " + value);});
	}
	// also in reverse order
	func main() {
		var target = 4...0;
		target.loop(func (value){System.print("Hello World " + value);});
	}

Loop within a Lists:

func main() {
		var target = [10,20,30,40,50,60,70,80,90];
		target.loop(func (value){System.print("Hello World " + value);});
	}

Loop within a String:

func main() {
                var s = "abcdefghijklmnopqrstuvwxyz";
                var vowels = ""
                s.loop(func (c) {
                        if (c == "a" or
                            c == "e" or
                            c == "i" or
                            c == "o" or
                            c == "u") {
                                vowels += c;
                        }
                })
                System.print(vowels)  // aeiou
        }

func main() {
		var target = ["key1":10,"key2":20,"key3":30,"key4":40];
		target.loop(func (key){System.print(key);});
	}
	// Output:
	// key1
	// key2
	// key4
	// key3

---

Map Copy Section

Map Copy Chapter

Maps are associative containers implemented as pairs each of which maps a key to a value. You can create a map by placing a series of comma-separated entries inside square brackets. Each entry is a key and a value separated by a colon:

// create a new map with 4 entries
	var d = ["Mark":1, "Andrew":2, "Paul":3, "Ross":4];
	// map has a count property
	var n = d.count;	// n is 4
	// create an empty map
	var map = [:];

Looking up values Copy Section

var names = ["Mark":1, "Andrew":2, "Paul":3, "Ross":4];
	names["Mark"];      // 1
	names["Andrew"];    // 2

Iterating items Copy Section

var people = ["Mark":1, "Andrew":2, "Paul":3, "Ross":4];
	for (var name in people.keys()) {
		System.print("Current name is " + name);
	}

Adding items Copy Section

var people = ["Mark":1, "Andrew":2, "Paul":3, "Ross":4];
	people["Kiara"] = 5;	// people now contains the "Kiara" key with value 5

Removing items Copy Section

var people = ["Mark":1, "Andrew":2, "Paul":3, "Ross":4];
	people.remove("Paul");
	people.remove("Ross");
	return people.count; // 2 is returned in this case

Retrieving keys Copy Section

var people = ["Mark":1, "Andrew":2, "Paul":3, "Ross":4];
	return people.keys; // ["Mark", "Andrew", "Paul", "Ross"] is returned in this case

Checking for a key Copy Section

var people = ["Mark":1, "Andrew":2, "Paul":3, "Ross":4];
	return people.hasKey("Max"); // false is returned in this case because the "Max" key is not in the people map

---

Math Copy Section

Math Copy Chapter

Mathematical Constants Copy Section

Math.PI;      // pi (~3.141593)
	Math.E;       // e (~2.718282)
	Math.LN2;     // natural log of 2 (ie. Math.log(2) = ~0.693147)
	Math.LN10;    // natural log of 10 (ie. Math.log(10) = ~2.302585)
	Math.LOG2E;   // log base 2 of e (~1.442695)
	Math.LOG10E;  // log base 10 of e (~0.434294)
	Math.SQRT2;   // sqrt of 2  (ie. Math.sqrt(2) = ~1.414214)
	Math.SQRT1_2; // sqrt of 0.5  (ie. Math.sqrt(0.5) = ~0.707107)

Absolute Values Copy Section

Math.abs(-10); // returns 10
	Math.abs(10);  // also returns 10

Trig Functions Copy Section

Math.acos(-1);     // returns pi
	Math.asin(0.5);    // returns 0.523599 ( = pi/6)
	Math.atan(1);      // returns 0.785398 ( = pi/4 )
	Math.atan2(-1,-1); // returns -2.356194 ( = -3pi/4 )
	Math.cos(Math.PI);     // returns -1
	Math.cos(180.radians); // returns -1 (same as above)
	Math.sin(Math.PI);     // returns 0
	Math.tan(Math.PI/4);   // returns 1

Ceiling, Floor Copy Section

Math.ceil(4.1)  // returns 5
	Math.floor(4.1) // returns 4

Rounding Copy Section

Math.round(4.1) // returns 4
	Math.round(4.5) // returns 5
	Math.round(65.34634) // returns 65.0
	Math.round(65.34634,1) // returns 65.3
	Math.round(65.34634,2) // returns 65.35

Exponents and Radicals Copy Section

// e to the power of x
	Math.exp(1) // returns 2.718282 (e)
	Math.exp(2) // returns 7.389056 (e^2)
	// x to the power of y
	Math.pow(2,3); // returns 8
	Math.sqrt(9); // 3
	Math.cbrt(8); // 2
	Math.xrt(4,16); // 2 (4th root of 16)

Logarithms Copy Section

// log base e
	Math.log(Math.E) // returns 1
	Math.log10(10)   // returns 1
	Math.logx(2,2)   // returns 1
	Math.logx(2,4)   // returns 2

Max and Min Copy Section

Math.max(-1,10,2); // Returns 10
	Math.min(-1,10,2); // Returns -1

Random Number Copy Section

Math.random()      // Returns a random number between 0.0 and 1.0
	Math.random(N)     // Returns a random number between 0 and N (or between 0.0 and N.0 if N is Float)
	Math.random(N1,N2) // Returns a random number between N1 and N2 (they must be both Int or Float)

GCF and LCM Copy Section

Math.gcf(12,15,21); // 3
	Math.lcm(6,15,2);   // 30

---

Null Copy Section

Null Copy Section

It indicates the absence of a value. If you call a method that doesn’t return anything and get its returned value, you get null back. The null data type is also used to initialize uninitialized variables with a default value.

class Newton {
		var mass = 10;
		var acceleration;
		func force() {
			return mass * acceleration;
		}
	}
	func f2() {
		var sir = Newton();
		// acceleration instance variable has no default value
		// so it is automatically set to null
		return sir.force();
	}
	func f1() {
		var a;
		// a is uninitialized so it has a default null value
		return a;
	}

---

Object Copy Section

Object Copy Section

Object is the root class of every object inside Gravity. Through the Object class, objects inherit a basic interface to the runtime system and the ability to behave as Gravity objects.

All the built-in Gravity type are built from the base Object class and when you declare a new Class in Gravity without a super class then it is set by default to Object.

The new Introspection feature is built on top of the base Object class (so any other Class automatically inherits that feature).

Built-in types Copy Chapter

Gravity has some built-in types that extend and overrides methods and classes from the base Object class:
* Int
* Float
* String
* Bool
* Null
* Class
* Function
* Fiber
* Instance
* List
* Map
* Range
* Function
* Closure
* Fiber

Special internal methods Copy Chapter

The Class class overrides the exec method in order to implement Object instantiation and initialization:

var foo = Foo()
  // means execute the exec method of the Foo class

All these special methods are implemented by the base Object class in order to provide most the basic functionalities that an user expects for a modern object oriented programming language.

---

Operators Copy Section

Operators Copy Chapter

An operator is a special symbol or phrase that you use to check, change, or combine values. For example, the addition operator (+) adds two numbers, as in var i = 1 + 2, and the logical AND operator (&&) combines two Boolean values, as in if (flag1 && flag2).
<br><br>
Gravity supports most standard C operators and improves several capabilities to eliminate common coding errors. The assignment operator (=) does not return a value, to prevent it from being mistakenly used when the equal to operator (==) is intended. Gravity also provides two range operators as a shortcut for expressing a range of values.

Arithmetic Operators Copy Section

var n1 = 1 + 2        // equals 3
	var n2 = 5 - 3        // equals 2
	var n3 = 2 * 3        // equals 6
	var n4 = 10.0 / 2.5   // equals 4.0
	var n5 = 9 % 4        // equals 1

Assignment Operator Copy Section

var a = 50;       // a = 50
	var b = a;        // b = 50
	var c = a  b;    // c = 50  50

Comparison Operators Copy Section

* Equal (==)
* Not equal (!=)
* Less than (<)
* Less than or equal (<=)
* Greater than (>)
* Greater than or equal (>=)
* Identical (===)
* Not identical (!==)
* Type check (is)
* Pattern match (~=)

1 == 1      // true because 1 is equal to 1
	1 != 2      // true because 1 is not equal to 2
	1 < 2       // true because 1 is less than 2
	1 <= 1      // true because 1 is less than or equal to 1
	1 > 2       // false because 1 is not greater than 2
	1 >= 1      // true because 1 is greater than or equal to 1
	1 === 1     // true because 1 is identical to 1 (same value and same class)
	1 is Int    // true because 1 is of class Int

Logical Operators Copy Section

* Logical NOT (!)
* Logical AND (&&)
* Logical OR (||)

!1          // false because 1 is true
	1 && 0      // false because one of the two values is false
	1 || 0      // true because one of the two values is true

Bitwise Operators Copy Section

* Bitwise shift left (<<)
* Bitwise shift right (>>)
* Bitwise AND (&)
* Bitwise OR (|)
* Bitwise XOR (^)
* Bitwise NOT or one's complement (~)

var n = 0B00110011;
	var n1 = n << 2             // equals 11001100
	var n2 = n >> 2             // equals 00001100
	var n3 = n & 0B00001111     // equals 00000011
	var n4 = n | 0B00001111     // equals 00111111
	var n5 = n ^ 0B00001111     // equals 00111100
	var n6 = ~n;                // equals 11001100

Compound Assignment Operators Copy Section

---

Range Copy Section

Range Copy Section

A range is an object that represents a consecutive range of numbers. Syntax for this type has been directly inspired by Swift.

// a represents a range with values 1,2,3
	var a = 1...3;
	// b represents a range with values 1,2
	var b = 1..<3;
	// Ranges have also a conveniente count property
	var n1 = a.count;	// n1 is now 3
	var n2 = b.count;	// n2 is now 2

A range is expecially useful in for loops:

for (var i in 1...10) {
		// repeat for 10 times (with i from 1 to 10)
	}

---

String Copy Section

String Copy Section

Strings are an immutable sequence of characters. String literals can be surrounded with double or single quotes. Gravity supports UTF-8 strings and characters.

/ Detailed source-code truncated for AI context efficiency. /

Strings can contain inline expressions with backslash and parentheses.

var amount = 7
	var fruit = "apples"
	var n = "You have \(amount) \(fruit)!"  // n is now "You have 7 apples!"

---

Syntax Copy Section

Syntax Copy Chapter

Gravity syntax is designed to be familiar to people coming from C-like languages like Javascript, Swift, C++, C# and many more. We started working on this new language a year before Apple announced Swift and we were happily surprised to discovered how similar both syntax appear.
>In Gravity semicolon separator ; is completely optional.

What Gravity code looks like:

class Rectangle {
		// instance variables
		var width;
		var height;
		// instance method
		func area() {
			return width*height;
		}
		// constructor
		func init(w, h) {
			width = w;
			height = h;
		}
	}
	func main() {
		// initialize a new Rectangle object
		var r = Rectangle(20, 10);
		// return value is 20*10 = 200
		return r.area();
	}

Comments Copy Section

// This is a line comment

/*
		This
		is
		a
		multi-line
		comment
	*/

#!/path/to/gravity
	func main() {
		System.print("Execute as: path/to/file.gravity");
		System.print("Instead of: gravity path/to/file.gravity");
	}

Include Copy Section

// adder.gravity
	func add(x, y) {
		return x+y;
	}

// main.gravity
	#include "adder.gravity"
	func main() {
		System.print("5+4=" + add(5,4));
	}

Import Copy Section

Reserved Keywords Copy Section

if in or is for var and not func else true enum case null
	file lazy super false break while class const event _func
	_args struct repeat switch return public static extern
	import module default private continue internal undefined

Identifiers Copy Section

a
	_thisIsValid
	Hello_World
	foo123
	BYE_BYE

Blocks and Scope Copy Section

// file scope can refer to a name
	// before it has been fully declared
	func f1() {
	    return f2();
	}
	func f2() {
	    return 42;
	}
	// block scope can be nested and
	// can hide other local variables
	func f3() {
		var a = 10;
		if (a > 0) {
			var a = 20;
		}
		// 10 is returned here
		return a;
	}

---

System Copy Section

System Copy Chapter

Print methods Copy Section

func main() {
		// print to stdout and add a newline character
		System.print("Hello World");
		// print to stdout without any newline character appended
		System.put("Hello World");
	}

Garbage collector methods Copy Section

func main() {
		// disable GC
		System.gcEnabled = false;
		// ratio used during automatic recomputation of the new gcthreshold value
		var ratio = System.gcRatio;
		// minimum GC threshold size
		var minthreshold = System.gcMinThreshold;
		// memory required to trigger a GC
		var threshold = System.gcThreshold;
		// enable GC
		System.gcEnabled = true;
	}

Time related methods Copy Section

func main() {
		var t1 = System.nanotime();
		perform_my_task();
		var t2 = System.nanotime();
		// return elapsed time in ms
		return ((t2-t1) / 1000000.0);
	}

System Exit Copy Section

func main() {
		foo(); // Do something useful
		System.exit(5);
	}

# Returns: 5
	$ echo $?

---

Types Copy Section

Values and Types Copy Chapter

Gravity is a dynamically typed language so variables do not have a type, although they refer to a value that does have a type. In Gravity everything is an object (with methods you can call and instance variables you can use). Basic built-in types are of class Object, Int, Float, String, Bool, Null, Class, Function, Fiber, Instance, List, Map and Range.

Manifest Typing Copy Section

Gravity supports manifest typing, so you can specify which type is associated with an Object with a syntax like:

var s:String = "Hello World";
var n:Int = 100;

It can also be used in func parameters:

func sum (a:Int, b: Int) {
	return a + b;
}

Manifest typing is currently used in autocompletion feature, full static type checking will be introduced in a future release.

---

Unittest Copy Section

Unit Test Copy Chapter

#unittest {
	name: "A simple add operation.";
	error: NONE;
	result: 33;
};
func main() {
	var a = 11;
	var b = 22;
	return a + b;
}

A unit test can also be written in order to be able to check for syntax, semantic and runtime errors. For syntax and semantic errors the user can also specify row and column of the expected generated error.

---

ARCHITECTURE Copy Section

Gravity Language Architecture

This document provides a detailed technical description of the Gravity programming language implementation, covering the full compilation pipeline, runtime virtual machine, type system, garbage collector, embedding API, and supporting infrastructure.

Table of Contents Copy Chapter

- 1. High-Level Overview
- 2. Compilation Pipeline
- 2.1 Lexer
- 2.2 Parser
- 2.3 Abstract Syntax Tree (AST)
- 2.4 Semantic Analysis — Pass 1
- 2.5 Semantic Analysis — Pass 2
- 2.6 Code Generation (AST → IR)
- 2.7 IR Representation
- 2.8 Optimizer & Bytecode Emission
- 3. Runtime Virtual Machine
- 3.1 VM Structure
- 3.2 Instruction Dispatch
- 3.3 Instruction Set
- 3.4 Instruction Encoding
- 3.5 Stack and Call Frames
- 3.6 Fiber (Coroutine) Model
- 3.7 Execution Flow
- 3.8 Fast-Path Optimizations
- 4. Value System and Type Hierarchy
- 4.1 Value Representation
- 4.2 Object Header and GC Metadata
- 4.3 Built-in Types
- 4.4 Functions and Closures
- 4.5 Upvalues
- 4.6 Classes and Instances
- 5. Garbage Collector
- 6. Core Data Structures
- 6.1 Hash Table
- 6.2 Dynamic Array
- 6.3 Memory Management
- 7. Optional Modules
- 7.1 Registration Pattern
- 7.2 Math Module
- 7.3 File Module
- 7.4 JSON Module
- 7.5 ENV Module
- 8. Embedding API
- 8.1 Compiler API
- 8.2 VM API
- 8.3 Delegate Pattern
- 8.4 Bridging
- 9. Utilities
- 10. CLI
- 11. Build System
- 12. Test Infrastructure

---

1. High-Level Overview Copy Chapter

Gravity is a dynamically typed, embeddable programming language written in portable C99 with zero external dependencies (only stdlib). It features Swift-like syntax and supports procedural, object-oriented, functional, and prototype-based programming paradigms.

The implementation follows a classic multi-pass compiler architecture that produces register-based bytecode executed by a stack-based virtual machine with coroutine (fiber) support.

Source Layout Copy Section

src/
├── cli/            CLI entry point (gravity.c)
├── compiler/       Lexer, parser, AST, semantic analysis, IR, optimizer, codegen
├── runtime/        Virtual machine (gravity_vm), built-in types (gravity_core)
├── shared/         Value representation, opcodes, hash table, dynamic array, memory/GC
├── optionals/      Optional modules: Math, File, JSON, ENV
└── utils/          Debug disassembler, JSON serialization, file I/O, UTF-8 utilities

Full Pipeline Copy Section

Source Code
    │
    ▼
┌──────────┐
│  Lexer   │  Character stream → Token stream
└────┬─────┘
     ▼
┌──────────┐
│  Parser  │  Token stream → Abstract Syntax Tree
└────┬─────┘
     ▼
┌──────────────┐
│ Semacheck 1  │  Gather non-local declarations into symbol tables
└──────┬───────┘
       ▼
┌──────────────┐
│ Semacheck 2  │  Resolve identifiers, detect upvalues, validate scopes
└──────┬───────┘
       ▼
┌──────────────┐
│   Codegen    │  AST → IR instructions (virtual registers)
└──────┬───────┘
       ▼
┌──────────────┐
│  Optimizer   │  Constant folding, dead code elimination, label resolution
└──────┬───────┘
       ▼
┌──────────────┐
│  Bytecode    │  Packed 32-bit instruction words
└──────┬───────┘
       ▼
┌──────────────┐
│     VM       │  Register-based execution with computed goto dispatch
└──────────────┘

The compiler entry point (gravity_compiler_run in gravity_compiler.c) orchestrates this pipeline: it creates a mini VM for GC during compilation, runs the parser to produce an AST, applies both semantic passes, generates IR code, optimizes it into final bytecode, and returns a gravity_closure_t ready for execution.

---

2. Compilation Pipeline Copy Chapter

2.1 Lexer Copy Section

Files: src/compiler/gravity_lexer.c, src/compiler/gravity_lexer.h

The lexer is a zero-allocation streaming tokenizer that scans source code character-by-character, producing tokens without copying or modifying the input buffer. Token values are pointers into the original source string.

#### Lexer State

struct gravity_lexer_t {
    const char *buffer;           // source buffer (not owned)
    uint32_t    offset;           // current byte offset
    uint32_t    position;         // current character position (UTF-8 aware)
    uint32_t    length;           // buffer length in bytes
    uint32_t    lineno;           // 1-based line number
    uint32_t    colno;            // 0-based column number
    uint32_t    fileid;           // source file identifier
    gtoken_s    token;            // current token
    bool        peeking;         // in peek mode
    gravity_delegate_t *delegate; // error callback
};

#### Token Structure

struct gtoken_s {
    gtoken_t    type;      // token type (enum)
    uint32_t    lineno;    // line number
    uint32_t    colno;     // column at end of token
    uint32_t    position;  // byte offset of first character
    uint32_t    bytes;     // length in bytes
    uint32_t    length;    // length in UTF-8 characters
    uint32_t    fileid;    // source file ID
    gbuiltin_t  builtin;   // builtin identifier (__LINE__, __FILE__, etc.)
    const char *value;     // pointer into source buffer (NOT null-terminated)
};

#### Token Categories (~80 total)

| Category | Count | Examples |
|----------|-------|---------|
| General | 8 | EOF, ERROR, COMMENT, STRING, NUMBER, IDENTIFIER, SPECIAL, MACRO |
| Keywords | 36 | func, class, var, const, if, else, for, while, return, import, enum, switch, true, false, null, undefined, super, isa, ... |
| Operators | 36 | +, -, *, /, %, &, \|, ^, ~, <<, >>, <, <=, ==, !=, ===, !==, ~=, &&, \|\|, =, +=, ..<, ..., ... |
| Punctuators | 10 | (, ), [, ], {, }, ;, :, ., , |

#### Key Features

- UTF-8 support: Tracks both byte offset and character position separately using utf8_charbytes(). Handles 1–4 byte sequences.
- Number literals: Decimal, hexadecimal (0x), binary (0b), octal (0o), floating-point with scientific notation (1.25e-2). Uses state-machine with lookahead.
- String literals: Single (') and double (") quoted strings with backslash escapes. Multi-line strings tracked across line boundaries.
- String interpolation: Detected as LITERAL_STRING_INTERPOLATED for "text \(expr)" syntax.
- Nested block comments: / ... / ... / ... / with a nesting depth counter.
- Builtin identifiers: __LINE__, __FILE__, __COLUMN__, __CLASS__, __FUNC__ resolved during lexing.
- Line separators: CR, LF, CR+LF, NEL (U+0085), LS (U+2028).

---

2.2 Parser Copy Section

Files: src/compiler/gravity_parser.c, src/compiler/gravity_parser.h

The parser uses a Pratt parser (top-down operator precedence) to build an Abstract Syntax Tree. It supports a lexer stack for #include directives and maintains a declaration scope stack for context tracking.

#### Parser State

struct gravity_parser_t {
    lexer_r              *lexer;        // stack of lexers (for includes)
    gnode_r              *declarations; // declaration scope stack
    gnode_r              *statements;   // statement list being built
    gravity_delegate_t   *delegate;     // error callbacks
    uint32_t              nerrors;      // accumulated error count
    uint32_t              unique_id;    // unique identifier counter
    uint32_t              depth;        // statement nesting depth
    uint32_t              expr_depth;   // expression nesting depth
};

#### Precedence Levels

PREC_LOWEST       =   0
PREC_ASSIGN       =  90    =  +=  -=  *=  /=  %=  <<=  >>=  &=  |=  ^=
PREC_TERNARY      = 100    ?:
PREC_LOGICAL_OR   = 110    ||
PREC_LOGICAL_AND  = 120    &&
PREC_COMPARISON   = 130    <  <=  >  >=  ==  !=  ===  !==  ~=
PREC_ISA          = 132    is
PREC_RANGE        = 135    ..<  ...
PREC_TERM         = 140    +  -  |  ^
PREC_FACTOR       = 150    *  /  %  &
PREC_SHIFT        = 160    <<  >>
PREC_UNARY        = 170    +  -  !  ~
PREC_CALL         = 200    .  (  [

Each grammar rule carries a prefix handler, infix handler, precedence level, and a right-associativity flag:

typedef struct {
    parse_func  prefix;      // prefix expression handler (or NULL)
    parse_func  infix;       // infix expression handler (or NULL)
    prec_level  precedence;  // binding power
    const char *name;        // operator name for diagnostics
    bool        right;       // right-associative
} grammar_rule;

#### Statement Types

- Compound statements (blocks)
- Variable/constant declarations (var, const, with optional type annotations and initialization)
- Function declarations (with parameters, default values)
- Class declarations (with inheritance, access modifiers, struct flag)
- Enum declarations
- Module declarations
- Control flow: if/else, switch/case/default, for, while, repeat
- Jump statements: break, continue, return
- Expression statements
- Empty statements

#### Error Recovery

- One error per line: Suppresses cascading errors from the same source line.
- Token synchronization: parse_skip_until() advances to a recovery point (e.g., next statement boundary).
- Recursion limits: MAX_RECURSION_DEPTH = 1000 for statements, MAX_EXPRESSION_DEPTH = 512 for expressions.

---

2.3 Abstract Syntax Tree (AST) Copy Section

Files: src/compiler/gravity_ast.c, src/compiler/gravity_ast.h

The AST uses a non-uniform node design — each node type has its own struct, but all share a common base for dispatch. A visitor pattern (gvisitor_t) is used for all tree traversals.

#### Node Types (21 total)

Statements (7):

| Node | Purpose |
|------|---------|
| NODE_LIST_STAT | Root/global statement list |
| NODE_COMPOUND_STAT | Block with local scope and symbol table |
| NODE_LABEL_STAT | Switch case/default label |
| NODE_FLOW_STAT | if/else, switch, ternary |
| NODE_JUMP_STAT | break, continue, return |
| NODE_LOOP_STAT | while, repeat, for loops |
| NODE_EMPTY_STAT | Empty statement |

Declarations (6):

| Node | Purpose |
|------|---------|
| NODE_ENUM_DECL | Enumeration definition |
| NODE_FUNCTION_DECL | Function (with params, defaults, upvalue list) |
| NODE_VARIABLE_DECL | Variable/constant declaration group |
| NODE_CLASS_DECL | Class (with superclass, protocols, ivar counts) |
| NODE_MODULE_DECL | Module definition |
| NODE_VARIABLE | Individual variable within a declaration |

Expressions (8):

| Node | Purpose |
|------|---------|
| NODE_BINARY_EXPR | Binary operations |
| NODE_UNARY_EXPR | Unary operations |
| NODE_FILE_EXPR | __FILE__ constant |
| NODE_LIST_EXPR | Array/map literals |
| NODE_LITERAL_EXPR | Numbers, strings, booleans |
| NODE_IDENTIFIER_EXPR | Variable references |
| NODE_KEYWORD_EXPR | true, false, null, undefined, super |
| NODE_POSTFIX_EXPR | Calls, subscripts, property access (with subtypes) |

#### Base Node

typedef struct {
    gnode_n   tag;            // node type discriminant
    uint32_t  refcount;       // reference counting for shared nodes
    uint32_t  block_length;   // byte length (for autocompletion)
    gtoken_s  token;          // source location
    bool      is_assignment;  // assignment target flag
    void     *decl;           // enclosing declaration
} gnode_t;

#### Location Tracking

After semantic analysis, each identifier is annotated with a resolved location:

typedef enum {
    LOCATION_LOCAL,             // local variable
    LOCATION_GLOBAL,            // global variable
    LOCATION_UPVALUE,           // closure upvalue
    LOCATION_CLASS_IVAR_SAME,   // instance variable (same class)
    LOCATION_CLASS_IVAR_OUTER   // instance variable (outer class)
} gnode_location_type;
typedef struct {
    gnode_location_type type;
    uint16_t index;             // symbol index
    uint16_t nup;               // upvalue or outer index
} gnode_location_t;

#### Visitor Pattern

typedef struct gvisitor {
    uint32_t nerr;
    void    *data;              // visitor-specific state
    void    *delegate;          // error callback delegate
    // 22 callbacks — one per node type, plus pre/post hooks
    void (*visit_pre)(visitor, node);
    void (*visit_post)(visitor, node);
    void (*visit_list_stmt)(visitor, node);
    void (*visit_compound_stmt)(visitor, node);
    void (*visit_function_decl)(visitor, node);
    // ... one for each AST node type
} gvisitor_t;

The dispatch function gvisit() calls visit_pre, then the node-specific callback based on node->tag, then visit_post.

---

2.4 Semantic Analysis — Pass 1 Copy Section

File: src/compiler/gravity_semacheck1.c

The first semantic pass gathers all non-local declarations into symbol tables, enabling forward references. It does not perform full name resolution or type checking.

#### What It Does

1. Creates symbol tables for each scope (global, class, module, enum).
2. Inserts function, class, enum, module, and variable declarations.
3. Reports duplicate declaration errors.
4. Assigns instance variable indices for class members.
5. Applies name mangling for static class members (prefixed with "$").

#### Symbol Table

struct symboltable_t {
    ghash_r    *stack;    // stack of hash tables (nested scopes)
    uint16_t    count1;   // local variable counter
    uint16_t    count2;   // instance variable counter
    uint16_t    count3;   // static variable counter
    symtable_tag tag;     // GLOBAL, FUNC, CLASS, MODULE, or ENUM
};

This pass enables forward references — a function can call another function declared later in the same scope:

func foo() { return bar(); }
func bar() { return 42; }

---

2.5 Semantic Analysis — Pass 2 Copy Section

File: src/compiler/gravity_semacheck2.c

The second semantic pass validates all identifiers within function bodies, resolves variable references, and detects closure upvalues.

#### What It Does

1. Validates all identifier references (reports "undefined variable" errors).
2. Resolves each identifier to its declaration and sets the location field.
3. Detects upvalue usage and builds upvalue lists for closures.
4. Validates declaration nesting constraints.
5. Checks break/continue appear only inside loops.
6. Validates module declarations are at global scope.

#### Identifier Lookup Order

The lookup traverses the declaration stack from innermost to outermost:

1. Local scope (current compound statement)
2. Enclosing function scopes
3. Enclosing class scopes (including superclass hierarchy)
4. Module scope
5. Global scope

#### Declaration Nesting Rules

What can be declared inside each construct:

│   func    var    enum   class   module
-------------------------------------------------
func     │   YES     YES    NO     YES     YES
var      │   YES     NO     NO     YES     YES
enum     │   YES     NO     NO     YES     YES
class    │   YES     NO     NO     YES     YES
module   │   NO      NO     NO     NO      NO
-------------------------------------------------

---

2.6 Code Generation (AST → IR) Copy Section

File: src/compiler/gravity_codegen.c

The code generator walks the AST using the visitor pattern and emits IR instructions with virtual registers. It maintains a context stack of functions and classes being compiled.

struct codegen_t {
    gravity_object_r  context;    // stack of functions/classes
    gnode_class_r     superfix;   // superclass resolution stack
    uint32_t          lasterror;  // last error line
    gravity_vm       *vm;         // mini VM for GC during codegen
};

#### Key Responsibilities

- Operator mapping: Converts token operators to opcodes (e.g., TOK_OP_ADD → ADD).
- Implicit self: Inserts self parameter for instance methods.
- Super calls: Emits LOADS instruction for superclass method lookup.
- Collection literals: LISTNEW/MAPNEW + SETLIST instructions.
- Range literals: RANGENEW with inclusive/exclusive flag.
- String interpolation: Converts "text \(expr)" into string concatenation operations.
- Closures: CLOSURE instruction references the function in the constant pool; CLOSE releases upvalues when scope exits.

---

2.7 IR Representation Copy Section

Files: src/compiler/gravity_ircode.c, src/compiler/gravity_ircode.h

The IR is a flat sequence of instructions with virtual registers, acting as the bridge between the AST and final packed bytecode.

#### IR Instruction

typedef struct {
    opcode_t  op;              // operation code
    optag_t   tag;             // metadata tag
    int32_t   p1, p2, p3;     // operand parameters
    union {
        double  d;             // embedded float constant (DOUBLE_TAG)
        int64_t n;             // embedded int constant (INT_TAG)
    };
    uint32_t  lineno;          // source line for debug info
} inst_t;

#### Instruction Tags

| Tag | Meaning |
|-----|---------|
| NO_TAG | Normal instruction |
| INT_TAG | Carries an embedded integer literal |
| DOUBLE_TAG | Carries an embedded float literal |
| LABEL_TAG | Label marker (resolved to offset by optimizer) |
| SKIP_TAG | Dead instruction (removed by optimizer) |
| RANGE_INCLUDE_TAG | Inclusive range flag |
| RANGE_EXCLUDE_TAG | Exclusive range flag |
| PRAGMA_MOVE_OPTIMIZATION | Hint for move elimination |

#### Register Allocation

The IR uses a bitmask-based register allocator (256 registers max = 32 bytes of bitmask):

- Local registers [0 .. nlocals-1]: Reserved for parameters and local variables.
- Temp registers [nlocals .. 255]: Allocated/freed for expression evaluation.
- Register 0 is always reserved.

Key operations:
- ircode_register_push_temp() — allocate the next free temp register.
- ircode_register_pop() — free the most recently allocated temp register.
- ircode_register_first_temp_available() — find first free temp slot.

#### Label Management

Three separate label stacks manage control flow:
- label_true — target for true branch of conditionals.
- label_false — target for false branch.
- label_check — target for loop checks and safety guards.

---

2.8 Optimizer & Bytecode Emission Copy Section

Files: src/compiler/gravity_optimizer.c, src/compiler/gravity_optimizer.h

The optimizer is the final compilation stage. It converts IR instructions into packed 32-bit bytecodes, resolves labels, and applies peephole optimizations.

#### Optimizations Performed

1. Constant folding: Arithmetic on constant operands evaluated at compile time.

LOADI r1, 5 ; LOADI r2, 3 ; ADD r0, r1, r2  →  LOADI r0, 8

2. Dead code elimination: Unreachable instructions after unconditional jumps/returns are marked SKIP and removed.

3. Move elimination: Redundant MOVE instructions are detected via PRAGMA_MOVE_OPTIMIZATION hints and removed when safe.

4. Label resolution: Symbolic labels are mapped to concrete instruction offsets.

#### 32-Bit Instruction Encoding

Standard (3 operands):  [ opcode:6 | A:8 | B:8 | C:10 ]
LOADI (immediate):      [ opcode:6 | A:8 | sign:1 | N:17 ]
JUMP (offset):          [ opcode:6 | N:26 ]

---

3. Runtime Virtual Machine Copy Chapter

3.1 VM Structure Copy Section

Files: src/runtime/gravity_vm.c, src/runtime/gravity_vm.h

The VM is an opaque struct (gravity_vm) with the following key components:

struct gravity_vm {
    // Execution
    gravity_fiber_t     *fiber;       // current fiber (coroutine)
    gravity_hash_t      *context;     // global variable table
    gravity_delegate_t  *delegate;    // runtime delegate
    uint32_t             pc;          // program counter
    bool                 aborted;     // runtime error flag
    // Recursion limits
    uint32_t             maxccalls;   // max nested C calls (default: 100)
    uint32_t             nccalls;     // current C call depth
    gravity_int_t        maxrecursion;// max recursive depth (0 = unlimited)
    // Garbage collector
    int32_t              gcenabled;   // reference-counted enable flag
    gravity_object_t    *gchead;      // linked list of all GC objects
    gravity_object_r     graylist;    // mark phase gray list
    gravity_object_r     gctemp;      // temporary GC-protected objects
    gravity_int_t        memallocated;// total allocated memory
    gravity_int_t        gcthreshold; // GC trigger threshold (default: 5MB)
    gravity_int_t        gcminthreshold; // minimum threshold (default: 1MB)
    gravity_float_t      gcratio;     // threshold growth ratio (default: 0.5)
    // Callbacks
    vm_transfer_cb       transfer;    // object allocation hook
    vm_cleanup_cb        cleanup;     // VM cleanup hook
    vm_filter_cb         filter;      // selective cleanup filter
};

An internal operator name cache (cache[GRAVITY_VTABLE_SIZE]) holds pre-computed strings for operator method names ("+", "-", "*", etc.) to avoid repeated allocations during dispatch.

---

3.2 Instruction Dispatch Copy Section

File: src/runtime/gravity_vmmacros.h

The VM uses computed goto for instruction dispatch (GCC/Clang), falling back to a switch statement on MSVC:

// Computed goto (GCC/Clang):
#define DISPATCH()  goto dispatchTable[OPCODE_GET_OPCODE(ip)]
// Switch fallback (MSVC):
#define INTERPRET_LOOP  switch (OPCODE_GET_OPCODE(*ip))
#define CASE_CODE(x)    case x:

Computed goto provides O(1) dispatch with no branch prediction overhead. Each opcode is a label address stored in a static table, and DISPATCH() performs an indirect jump.

Key macros in the dispatch loop:

| Macro | Purpose |
|-------|---------|
| OPCODE_GET_OPCODE(inst) | Extract 6-bit opcode |
| OPCODE_GET_ONE8bit_ONE18bit(inst, A, N) | Decode register + immediate |
| OPCODE_GET_THREE8bit(inst, A, B, C) | Decode three register operands |
| LOAD_FRAME() | Synchronize local variables from fiber state |
| STORE_FRAME() | Save local variables back to fiber state |
| PUSH_FRAME(closure, stackstart, dest, nargs) | Create a new call frame |
| FN_COUNTREG(f, nargs) | Compute register window size: max(nparams, nargs) + nlocals + ntemps |

---

3.3 Instruction Set Copy Section

The VM implements 56 opcodes (6-bit opcode field supports up to 64):

#### General (5)

| Opcode | Description |
|--------|-------------|
| RET0 | Return null |
| HALT | Stop VM execution |
| NOP | No operation |
| RET | Return value from register |
| CALL | Call function/closure |

#### Load/Store (13)

| Opcode | Semantics |
|--------|-----------|
| LOAD | R(A) = R(B)[R(C)] — property access |
| LOADAT | R(A) = R(B)[R(C)] — subscript access |
| LOADS | Super property access |
| LOADK | R(A) = K(Bx) — load constant from pool |
| LOADG | R(A) = G[K(Bx)] — load global |
| LOADI | R(A) = N — load inline integer |
| LOADU | R(A) = U(B) — load upvalue |
| MOVE | R(A) = R(B) — register copy |
| STORE | R(B)[R(C)] = R(A) — property write |
| STOREAT | R(B)[R(C)] = R(A) — subscript write |
| STOREG | G[K(Bx)] = R(A) — store global |
| STOREU | U(B) = R(A) — store upvalue |

#### Jump (2)

| Opcode | Semantics |
|--------|-----------|
| JUMP | Unconditional jump (26-bit signed offset) |
| JUMPF | Jump if false (18-bit signed offset) |

#### Arithmetic & Logic (19)

| Opcode | Operation |
|--------|-----------|
| ADD, SUB, MUL, DIV, REM | Arithmetic |
| AND, OR | Logical and/or |
| LT, GT, LEQ, GEQ | Ordered comparison |
| EQ, NEQ | Equality |
| EQQ, NEQQ | Strict equality (identity) |
| ISA | Instance-of check |
| MATCH | Pattern match (~=) |
| NEG, NOT | Unary negation/logical not |

#### Bitwise (6)

| Opcode | Operation |
|--------|-----------|
| LSHIFT, RSHIFT | Bit shifts |
| BAND, BOR, BXOR | Bitwise and/or/xor |
| BNOT | Bitwise complement |

#### Collections (4)

| Opcode | Semantics |
|--------|-----------|
| MAPNEW | R(A) = new Map(B) |
| LISTNEW | R(A) = new List(B) |
| RANGENEW | R(A) = new Range(B, C, flag) |
| SETLIST | Populate list/map from register range |

#### Closures (2)

| Opcode | Semantics |
|--------|-----------|
| CLOSURE | Create closure from function constant |
| CLOSE | Close open upvalues at register level |

#### Special (1)

| Opcode | Semantics |
|--------|-----------|
| CHECK | Clone struct value (enforces value semantics) |

#### Operator Vtable

Each class defines operator methods via a vtable indexed by GRAVITY_VTABLE_INDEX:

typedef enum {
    GRAVITY_ADD_INDEX,    // "+"
    GRAVITY_SUB_INDEX,    // "-"
    GRAVITY_MUL_INDEX,    // "*"
    GRAVITY_DIV_INDEX,    // "/"
    // ... one for each overloadable operator
    GRAVITY_EXEC_INDEX    // "()" — call
} GRAVITY_VTABLE_INDEX;

---

3.4 Instruction Encoding Copy Section

All instructions are 32 bits wide with varying field layouts:

Standard 3-operand:   [ opcode:6 ][ A:8 ][ B:8 ][ C:10 ]
Immediate (LOADI):    [ opcode:6 ][ A:8 ][ sign:1 ][ N:17 ]
Jump (JUMP):          [ opcode:6 ][ N:26 ]

Operand extraction uses bit shifts and masks:

#define OPCODE_GET_OPCODE(v)                ((v >> 26) & 0x3F)
#define OPCODE_GET_THREE8bit(v, A, B, C)    A = (v >> 18) & 0xFF; \
                                            B = (v >> 10) & 0xFF; \
                                            C = v & 0x3FF;
#define OPCODE_GET_ONE8bit_ONE18bit(v, A, N) A = (v >> 18) & 0xFF; \
                                             N = v & 0x3FFFF;

---

3.5 Stack and Call Frames Copy Section

#### Call Frame

typedef struct {
    uint32_t           *ip;          // instruction pointer
    uint32_t            dest;        // destination register for return value
    uint16_t            nargs;       // actual argument count
    gravity_list_t     *args;        // implicit _args array (if needed)
    gravity_closure_t  *closure;     // closure being executed
    gravity_value_t    *stackstart;  // first stack slot of this frame
    bool                outloop;     // set when called from gravity_vm_runclosure
} gravity_callframe_t;

#### Stack Layout Per Frame

stackstart[0]          = self (implicit first parameter)
stackstart[1..n]       = explicit parameters
stackstart[n+1..m]     = local variables
stackstart[m+1..p]     = temporary values

#### Sliding Register Window

When a CALL instruction executes, the register window for the callee starts at r2+1 (where r2 is the callable register). This sliding window design minimizes value copying between frames:

Caller:     [ ... | self | arg1 | arg2 | ... ]
                    ↑
                    rwin = r2 + 1 → callee's stackstart
Callee:     [ self | arg1 | arg2 | locals... | temps... ]

The stack grows on demand (power-of-2 reallocation). When the stack is reallocated, all frame pointers are adjusted to maintain consistency. The stack never shrinks.

---

3.6 Fiber (Coroutine) Model Copy Section

Fibers are Gravity's concurrency primitive. Each fiber has its own stack and call frame array, enabling cooperative multitasking.

typedef struct {
    gravity_class_t    *isa;
    gravity_gc_t        gc;
    // Stack
    gravity_value_t    *stack;        // value stack buffer
    gravity_value_t    *stacktop;     // current stack pointer
    uint32_t            stackalloc;   // allocated capacity
    // Call frames
    gravity_callframe_t *frames;      // frame buffer
    uint32_t             nframes;     // frames in use
    uint32_t             framesalloc; // allocated capacity
    // Closures
    gravity_upvalue_t   *upvalues;    // open upvalue linked list
    // Status
    gravity_fiber_status status;      // NEVER_EXECUTED, RUNNING, ABORTED, TERMINATED, TRYING
    char                *error;       // error message
    bool                 trying;      // inside try block
    gravity_fiber_t     *caller;      // parent fiber
    gravity_value_t      result;      // final result
    // Timing (for yield with timeout)
    nanotime_t           lasttime;
    gravity_float_t      timewait;
    gravity_float_t      elapsedtime;
} gravity_fiber_t;

Fiber status values: FIBER_NEVER_EXECUTED, FIBER_RUNNING, FIBER_ABORTED_WITH_ERROR, FIBER_TERMINATED, FIBER_TRYING.

---

3.7 Execution Flow Copy Section

#### gravity_vm_exec — Main Bytecode Loop

bool gravity_vm_exec(gravity_vm *vm) {
    DECLARE_DISPATCH_TABLE;
    // Load fiber, frame, function, stackstart, ip, bytecode ...
    while (1) {
        INTERPRET_LOOP {
            CASE_CODE(ADD): {
                // 1. Decode operands
                // 2. Check fast path (inline int/float arithmetic)
                // 3. Fallback: look up "+" method on r2's class
                // 4. Call method, store result
                DISPATCH();
            }
            CASE_CODE(CALL): {
                // 1. Decode: r1=dest, r2=callable, r3=nargs
                // 2. Compute register window: rwin = r2 + 1
                // 3. Resolve closure (directly or via "exec" method)
                // 4. Push frame, fill defaults for missing args
                // 5. Dispatch by type:
                //    - NATIVE: PUSH_FRAME, continue loop
                //    - INTERNAL: call C function directly
                //    - BRIDGED: call delegate->bridge_execute
                DISPATCH();
            }
            CASE_CODE(RET): {
                // 1. Pop frame
                // 2. Close open upvalues
                // 3. If outloop flag → return to gravity_vm_runclosure
                // 4. Else → continue with caller frame
                DISPATCH();
            }
            // ... 53 more opcodes
        }
    }
}

#### gravity_vm_runclosure — External Entry Point

Called from the embedding API or internally to invoke a specific closure:

1. Validate VM is not aborted.
2. Set up stack window and parameters.
3. Dispatch by function type:
- Native: Increment nccalls, call gravity_vm_exec(), decrement.
- Internal: Call C function pointer directly.
- Bridged: Call delegate bridge_execute callback.
4. Restore frame pointers and adjust stack top.

---

3.8 Fast-Path Optimizations Copy Section

- Inline arithmetic: When both operands are Int or Float, arithmetic is computed directly without method lookup.
- Jump fusion: Compare instructions (e.g., EQ, LT) peek ahead for a following JUMPF. If found, the compare and jump are fused into a single operation.
- Register window: The sliding register window avoids copying arguments between caller and callee.
- Computed goto: O(1) instruction dispatch with no branch prediction overhead.
- Pre-allocated frames: Call frames and stack space are pre-allocated and reused.

---

4. Value System and Type Hierarchy Copy Chapter

4.1 Value Representation Copy Section

Files: src/shared/gravity_value.h, src/shared/gravity_value.c

Gravity uses a 16-byte tagged union for all values (not NaN-boxing):

typedef struct {
    gravity_class_t *isa;       // 8 bytes: type tag (pointer to class)
    union {                     // 8 bytes: payload
        gravity_int_t    n;     //   integer value
        gravity_float_t  f;     //   float/double value
        gravity_object_t *p;    //   pointer to heap object
    };
} gravity_value_t;

The isa pointer serves double duty: it identifies the type and provides the method lookup table. Special sentinel values:
- Null: isa = NULL, n = 0
- Undefined: isa = NULL, n = 1

Unboxed types (value stored directly in the union): Bool, Int, Float, Null, Undefined.

Boxed types (pointer to heap-allocated object): String, List, Map, Class, Instance, Closure, Function, Range, Fiber, Upvalue.

---

4.2 Object Header and GC Metadata Copy Section

All heap-allocated objects share a common header:

typedef struct gravity_object_s {
    gravity_class_t *isa;       // class pointer (method dispatch)
    gravity_gc_t     gc;        // GC metadata
} gravity_object_t;
typedef struct {
    bool                isdark;   // marked during GC
    bool                visited;  // prevents double-counting in size calc
    gravity_object_t   *next;     // intrusive linked list (GC object chain)
    gravity_gc_callback free;     // destructor callback
    gravity_gc_callback size;     // size reporting callback
    gravity_gc_callback blacken;  // mark-children callback
} gravity_gc_t;

Every heap object is linked into the VM's GC chain via gc.next. The three callbacks (free, size, blacken) implement type-specific GC behavior without virtual dispatch overhead.

---

4.3 Built-in Types Copy Section

The runtime registers these built-in classes (in gravity_core.c):

| Class | Behavior |
|-------|----------|
| gravity_class_int | 64-bit integer, arithmetic operators, bitwise ops |
| gravity_class_float | IEEE 754 double, arithmetic operators |
| gravity_class_bool | Boolean, logical operators |
| gravity_class_null | Null singleton |
| gravity_class_string | Immutable UTF-8 string, concatenation, methods |
| gravity_class_object | Base class (all types inherit from this) |
| gravity_class_function | Function prototype |
| gravity_class_closure | Closure (function + captured environment) |
| gravity_class_fiber | Fiber (coroutine) |
| gravity_class_class | Metaclass |
| gravity_class_instance | User-defined class instance |
| gravity_class_list | Dynamic array |
| gravity_class_map | Hash map |
| gravity_class_range | Integer range (inclusive or exclusive) |
| gravity_class_upvalue | Captured variable reference |

Each class binds operator methods and instance methods. For example, gravity_class_int binds "+", "-", "*", etc. as well as methods like loop(), random(), and conversion operators.

---

4.4 Functions and Closures Copy Section

#### Function Prototype

typedef struct {
    gravity_class_t  *isa;
    gravity_gc_t      gc;
    const char       *identifier;     // function name
    uint16_t          nparams;        // formal parameters (including self)
    uint16_t          nlocals;        // local variables
    uint16_t          ntemps;         // temporary registers
    uint16_t          nupvalues;      // captured variables
    gravity_exec_type tag;            // execution type
    union {
        // EXEC_TYPE_NATIVE (compiled Gravity code):
        struct {
            gravity_value_r  cpool;     // constant pool
            gravity_value_r  pvalue;    // default parameter values
            gravity_value_r  pname;     // parameter names
            uint32_t         ninsts;    // instruction count
            uint32_t        *bytecode;  // packed 32-bit instructions
            uint32_t        *lineno;    // line number mapping (debug)
            bool             useargs;   // needs implicit _args array
        };
        // EXEC_TYPE_INTERNAL (C callback):
        gravity_c_internal   internal;  // bool (*)(vm, args, nargs, rindex)
        // EXEC_TYPE_SPECIAL (computed property):
        struct {
            uint16_t  index;           // property index
            void     *special[2];      // [0]=getter, [1]=setter
        };
    };
} gravity_function_t;

Execution types:
- EXEC_TYPE_NATIVE — compiled Gravity bytecode.
- EXEC_TYPE_INTERNAL — C function callback with signature bool ()(gravity_vm, gravity_value_t*, uint16_t, uint32_t).
- EXEC_TYPE_BRIDGED — external bridge, executed via delegate callback.
- EXEC_TYPE_SPECIAL — getter/setter computed property.

#### Closure

typedef struct {
    gravity_class_t    *isa;
    gravity_gc_t        gc;
    gravity_vm         *vm;           // owning VM
    gravity_function_t *f;            // function prototype (shared)
    gravity_object_t   *context;      // captured self reference
    gravity_upvalue_t upvalue;      // captured upvalue array
    uint32_t            refcount;     // bridge reference counting
} gravity_closure_t;

Multiple closures can share the same function prototype while having different captured environments.

---

4.5 Upvalues Copy Section

Upvalues implement Lua-style open/closed variable capture:

typedef struct upvalue_s {
    gravity_class_t  *isa;
    gravity_gc_t      gc;
    gravity_value_t  *value;     // points to stack slot (open) or self->closed (closed)
    gravity_value_t   closed;    // storage when variable leaves scope
    struct upvalue_s *next;      // linked list (ordered by stack position)
} gravity_upvalue_t;

- Open upvalue: value points to a live stack slot. The fiber maintains a linked list of open upvalues ordered by descending stack address.
- Closed upvalue: When the enclosing function returns, the captured value is copied from the stack into closed, and value is repointed to &self->closed.

The CLOSE instruction walks the open upvalue list and closes any upvalues at or above a given register level.

---

4.6 Classes and Instances Copy Section

#### Class

typedef struct {
    gravity_class_t  *isa;           // metaclass
    gravity_gc_t      gc;
    gravity_class_t  *objclass;      // metaclass reference
    const char       *identifier;    // class name
    bool              has_outer;     // has outer class ivar
    bool              is_struct;     // value semantics (copy on assignment)
    bool              is_inited;     // metaclass initialized
    void             *xdata;         // bridge extension data
    gravity_class_t  *superclass;    // parent class
    const char       *superlook;     // extern superclass name (lazy binding)
    gravity_hash_t   *htable;        // method/property hash table
    uint32_t          nivars;        // instance variable count
    gravity_value_r   inames;        // ivar names (debug)
    gravity_value_t  *ivars;         // static (class) variables
} gravity_class_t;

Method resolution traverses the superclass chain. Methods and computed properties are stored in the class hash table.

#### Instance

typedef struct {
    gravity_class_t  *isa;
    gravity_gc_t      gc;
    gravity_class_t  *objclass;      // actual class
    void             *xdata;         // bridge extension data
    gravity_value_t  *ivars;         // instance variable array (indexed by position)
} gravity_instance_t;

Instance variables are stored in a flat array indexed by position (set during semacheck1), providing O(1) access.

---

5. Garbage Collector Copy Chapter

Location: src/runtime/gravity_vm.c

Gravity uses a tri-color mark-and-sweep garbage collector.

Mark Phase Copy Section

1. Mark temporary protected objects (in vm->gctemp).
2. Mark the current fiber as a root.
3. Mark all globals in the context hash table.
4. Process the gray list: for each gray object, call its blacken callback to mark all referenced objects.
5. Repeat until the gray list is empty.

Sweep Phase Copy Section

1. Walk the vm->gchead linked list.
2. For each object not marked (!isdark): call its free callback and remove it from the chain.
3. For each marked object: clear the isdark flag for the next cycle.

GC Triggers Copy Section

- Automatic: When memallocated >= gcthreshold during gravity_gc_transfer (object allocation).
- Manual: gravity_gc_start(vm).
- Stress test: Every allocation (when compiled with GRAVITY_GC_STRESSTEST).

Dynamic Threshold Adjustment Copy Section

After each collection:

new_threshold = memallocated + (memallocated * gcratio / 100)
if (new_threshold < minthreshold) new_threshold = minthreshold
if (new_threshold < original)     new_threshold = original

Default values: gcthreshold = 5MB, gcminthreshold = 1MB, gcratio = 0.5 (50%).

GC-Safe Coding Pattern Copy Section

The enable flag is reference-counted, allowing nested disable/enable calls:

gravity_gc_setenabled(vm, false);  // disable GC (increments counter)
// ... allocate objects safely ...
gravity_gc_setenabled(vm, true);   // re-enable (decrements counter)

Temporary objects can be protected from collection:

gravity_gc_temppush(vm, object);   // protect
// ... use object ...
gravity_gc_temppop(vm);            // unprotect

---

6. Core Data Structures Copy Chapter

6.1 Hash Table Copy Section

Files: src/shared/gravity_hash.c, src/shared/gravity_hash.h

A chained hash table used for symbol tables, class method lookup, global variables, and the Map type.

typedef struct hash_node_s {
    uint32_t             hash;    // cached hash value
    gravity_value_t      key;
    gravity_value_t      value;
    struct hash_node_s  *next;    // collision chain
} hash_node_t;
struct gravity_hash_t {
    uint32_t              size;        // bucket count
    uint32_t              count;       // entry count
    hash_node_t         nodes;       // bucket array
    gravity_hash_compute_fn  compute_fn;  // hash function
    gravity_hash_isequal_fn  isequal_fn;  // equality function
    gravity_hash_iterate_fn  free_fn;     // entry cleanup callback
    void                    *data;        // callback context
};

| Property | Value |
|----------|-------|
| Hash function | Murmur3-32 (seed 5381) |
| Collision resolution | Chaining (linked list per bucket) |
| Load factor | 0.75 |
| Growth strategy | Double bucket count on resize |
| Initial size | 32 buckets |
| Max entries | 2^30 |

Hash function variants: gravity_hash_compute_buffer() for strings, gravity_hash_compute_int() for integers, gravity_hash_compute_float() for floats.

---

6.2 Dynamic Array Copy Section

File: src/shared/gravity_array.h

A macro-based generic dynamic array:

#define marray_t(type)  struct { size_t n, m; type *p; }
//                               count  capacity  data

| Macro | Purpose |
|-------|---------|
| marray_init(v) | Initialize to zero |
| marray_push(T, v, x) | Append (doubles capacity if needed) |
| marray_pop(v) | Remove and return last element |
| marray_get(v, i) | Access element by index |
| marray_size(v) | Current element count |
| marray_max(v) | Current capacity |
| marray_resize(T, v, n) | Extend capacity to at least n |
| marray_destroy(v) | Free backing memory |

Growth strategy: double capacity on each reallocation.

---

6.3 Memory Management Copy Section

Files: src/shared/gravity_memory.h, src/shared/gravity_memory.c

Production mode provides thin wrappers around malloc/realloc/free with max block size enforcement (MAX_MEMORY_BLOCK = 150MB).

Debug mode (GRAVITY_MEMORY_DEBUG) adds:
- Tracking of every allocation with call stack.
- Detection of double-free and use-after-free.
- Leak reporting on shutdown.

All allocations go through mem_alloc(), which integrates with the VM's memallocated counter for GC threshold tracking.

---

7. Optional Modules Copy Chapter

7.1 Registration Pattern Copy Section

File: src/optionals/gravity_optionals.h

Each optional module follows the same pattern:

1. Compile-time guard (#ifndef GRAVITY_INCLUDE_MATH / #define GRAVITY_INCLUDE_MATH).
2. Macro wrappers that become no-ops when disabled.
3. Singleton class with reference counting.
4. Static methods bound to the metaclass.
5. Registration: gravity_vm_setvalue(vm, name, class).

// Typical module lifecycle:
static gravity_class_t *gravity_class_math = NULL;
static uint32_t refcount = 0;
void gravity_math_register(gravity_vm *vm) {
    if (!gravity_class_math) create_optional_class();
    ++refcount;
    gravity_vm_setvalue(vm, "Math", VALUE_FROM_OBJECT(gravity_class_math));
}
void gravity_math_free(void) {
    if (--refcount) return;   // wait for all VMs to unregister
    // destroy class ...
}

Computed properties (read-only constants) use a getter-only closure:

gravity_closure_t *closure = computed_property_create(NULL, NEW_FUNCTION(getter), NULL);
gravity_class_bind(meta, "PI", VALUE_FROM_OBJECT(closure));

---

7.2 Math Module Copy Section

File: src/optionals/gravity_opt_math.c — Class name: "Math"

Methods (23):

| Category | Functions |
|----------|-----------|
| Trigonometric | sin, cos, tan, asin, acos, atan, atan2 |
| Rounding | ceil, floor, round (with optional precision) |
| Logarithmic | log, log10, logx (custom base) |
| Algebraic | abs, sqrt, cbrt, xrt (nth root), pow, exp |
| Combinatorial | gcf, lcm |
| Interpolation | lerp |
| Comparison | min, max (variadic) |
| Random | random(), random(max), random(min, max) |

Constants (8): PI, E, LN2, LN10, LOG2E, LOG10E, SQRT2, SQRT1_2.

Random number generator: LFSR258 (64-bit) or LFSR113 (32-bit), seeded with nanotime() on first call.

---

7.3 File Module Copy Section

File: src/optionals/gravity_opt_file.c — Class name: "File"

Uses a custom gravity_file_t struct wrapping a FILE* pointer, with GC integration for automatic cleanup.

Class (static) methods: size, exists, delete, read, write, buildpath, is_directory, directory_create, directory_scan.

Instance methods: open (factory), read, write, seek, eof, error, flush, close.

The directory_scan method accepts a closure callback invoked for each entry with (filename, fullpath, isdir).

---

7.4 JSON Module Copy Section

File: src/optionals/gravity_opt_json.c — Class name: "JSON"

Two static methods:
- stringify(value) — Serialize any Gravity value to a JSON string. Handles nested structures, escapes special characters, uses heap allocation for strings >4KB.
- parse(jsonString) — Deserialize a JSON string into nested Gravity lists and maps. Returns null for invalid JSON.

---

7.5 ENV Module Copy Section

File: src/optionals/gravity_opt_env.c — Class name: "ENV"

Methods: get(key), set(key, value), keys().

Properties: argc (read-only), argv (read-only list).

Supports map-access syntax: ENV["PATH"] via overloaded load/store-at handlers. Cross-platform: uses _putenv_s on Windows, setenv on Unix.

---

8. Embedding API Copy Chapter

8.1 Compiler API Copy Section

File: src/compiler/gravity_compiler.h

gravity_compiler_t  gravity_compiler_create(gravity_delegate_t delegate);
gravity_closure_t   *gravity_compiler_run(compiler, source, len, fileid, is_static, add_debug);
gnode_t             *gravity_compiler_ast(compiler);
void                 gravity_compiler_transfer(compiler, vm);  // move objects to VM's GC
void                 gravity_compiler_free(compiler);

Serialization for ahead-of-time compilation:

json_t *gravity_compiler_serialize(compiler, closure);
bool    gravity_compiler_serialize_infile(compiler, closure, path);

---

8.2 VM API Copy Section

File: src/runtime/gravity_vm.h

// Lifecycle
gravity_vm          gravity_vm_new(gravity_delegate_t delegate);
gravity_vm          *gravity_vm_newmini(void);        // lightweight (no optionals)
void                 gravity_vm_free(vm);
void                 gravity_vm_reset(vm);
// Execution
bool                 gravity_vm_runmain(vm, closure);
bool                 gravity_vm_runclosure(vm, closure, sender, params, nparams);
gravity_value_t      gravity_vm_result(vm);
// Globals
void                 gravity_vm_setvalue(vm, key, value);
gravity_value_t      gravity_vm_getvalue(vm, key, keylen);
gravity_value_t      gravity_vm_lookup(vm, key);
// Memory & GC
void                 gravity_vm_transfer(vm, object);
void                 gravity_gc_start(vm);
void                 gravity_gc_setenabled(vm, enabled);
void                 gravity_gc_setvalues(vm, threshold, minthreshold, ratio);
// Bytecode loading
gravity_closure_t   *gravity_vm_loadfile(vm, path);
gravity_closure_t   *gravity_vm_loadbuffer(vm, buffer, len);
// Optional modules
void                 gravity_opt_register(vm);
void                 gravity_opt_free(void);

---

8.3 Delegate Pattern Copy Section

File: src/shared/gravity_delegate.h

The delegate is a struct of function pointers used for all communication between the compiler/VM and the host application:

typedef struct {
    // Error handling
    gravity_error_callback      error_callback;       // syntax, semantic, runtime errors
    // Compiler hooks
    gravity_loadfile_callback   loadfile_callback;    // resolve import paths
    gravity_filename_callback   filename_callback;    // map fileid → filename
    gravity_precode_callback    precode_callback;     // inject code at parse time
    gravity_parser_callback     parser_callback;      // syntax highlighting hook
    gravity_type_callback       type_callback;        // bind type annotations
    // Logging
    gravity_log_callback        log_callback;
    gravity_log_clear           log_clear;
    // Bridge (C interop)
    gravity_bridge_initinstance bridge_initinstance;
    gravity_bridge_execute      bridge_execute;
    gravity_bridge_blacken      bridge_blacken;
    gravity_bridge_equals       bridge_equals;
    gravity_bridge_clone        bridge_clone;
    gravity_bridge_size         bridge_size;
    gravity_bridge_free         bridge_free;
    gravity_bridge_getvalue     bridge_getvalue;
    gravity_bridge_setvalue     bridge_setvalue;
    // Testing
    gravity_unittest_callback   unittest_callback;
} gravity_delegate_t;

Error types: GRAVITY_ERROR_SYNTAX, GRAVITY_ERROR_SEMANTIC, GRAVITY_ERROR_RUNTIME, GRAVITY_ERROR_IO, GRAVITY_WARNING.

---

8.4 Bridging Copy Section

Gravity supports binding external (C, Objective-C, Swift) objects through the bridge delegate callbacks:

- EXEC_TYPE_BRIDGED functions are dispatched via delegate->bridge_execute.
- Instance creation goes through delegate->bridge_initinstance.
- Property access uses bridge_getvalue / bridge_setvalue.
- Objects store host-side data in the xdata pointer present on classes, instances, and functions.

#### Typical Embedding Usage

// 1. Create compiler
gravity_delegate_t delegate = {.error_callback = report_error};
gravity_compiler_t *compiler = gravity_compiler_create(&delegate);
// 2. Compile
gravity_closure_t *closure = gravity_compiler_run(
    compiler, source, strlen(source), 0, true, true);
// 3. Create VM and transfer ownership
gravity_vm *vm = gravity_vm_new(&delegate);
gravity_compiler_transfer(compiler, vm);
gravity_compiler_free(compiler);
// 4. Execute
if (gravity_vm_runmain(vm, closure)) {
    gravity_value_t result = gravity_vm_result(vm);
    // ... use result ...
}
// 5. Cleanup
gravity_vm_free(vm);
gravity_core_free();

---

9. Utilities Copy Chapter

Debug / Disassembler Copy Section

Files: src/utils/gravity_debug.c, src/utils/gravity_debug.h

- opcode_name(opcode_t) — maps opcode enum to mnemonic string.
- opcode_constname(int) — maps constant pool indices to names (SUPER, NULL, UNDEFINED, TRUE, FALSE, etc.).
- gravity_disassemble() — full bytecode disassembler; outputs human-readable assembly with line numbers and decoded operands.

JSON Serialization Copy Section

Files: src/utils/gravity_json.c, src/utils/gravity_json.h

Two components:
- Serializer: json_t object with hierarchical json_add_*(), json_begin/end_array(), json_begin/end_object() functions. Used by the compiler to serialize bytecode to JSON.
- Parser: Third-party JSON parser (json_parse()) that produces a json_value tree. Used by gravity_vm_loadfile to deserialize compiled bytecode.

File I/O and Platform Utilities Copy Section

Files: src/utils/gravity_utils.c, src/utils/gravity_utils.h

- High-resolution timer: nanotime() (platform-specific: mach_absolute_time on macOS, clock_gettime on Linux, QueryPerformanceCounter on Windows).
- File operations: file_read, file_write, file_exists, file_delete, file_size, file_buildpath.
- Directory operations: directory_create, directory_init, directory_read, is_directory.
- String utilities: string_dup, string_replace, string_reverse.
- UTF-8: utf8_charbytes, utf8_encode, utf8_len, utf8_nbytes, utf8_reverse.
- Number parsing: number_from_bin, number_from_hex, number_from_oct.

---

10. CLI Copy Chapter

File: src/cli/gravity.c

Operation Modes Copy Section

| Flag | Mode | Description |
|------|------|-------------|
| (filename) | OP_COMPILE_RUN | Compile and execute in one pass |
| -c file | OP_COMPILE | Compile to bytecode file (default: gravity.json) |
| -x file | OP_RUN | Execute precompiled JSON bytecode |
| -i 'code' | OP_INLINE_RUN | Compile and execute inline string (wrapped in func main() { ... }) |
| -t folder | OP_UNITTEST | Run unit tests recursively |
| -o file | — | Specify output filename |
| -q | — | Quiet mode (suppress result and timing) |

The CLI sets up a gravity_delegate_t with error_callback and loadfile_callback (for import resolution), then drives the compiler and VM through the standard embedding API.

---

11. Build System Copy Chapter

File: Makefile

Targets Copy Section

| Target | Output |
|--------|--------|
| make | gravity CLI executable |
| make mode=debug | Debug build (-g -O0 -DDEBUG) |
| make lib | Shared library (libgravity.dylib / .so / .dll) |
| make example | C embedding API example |
| make clean | Remove all build artifacts |

Compiler Flags Copy Section

-std=gnu99 -fgnu89-inline -fPIC -DBUILD_GRAVITY_API
-O2                     (release)
-g -O0 -DDEBUG          (debug)

Platform Detection Copy Section

- macOS: libgravity.dylib
- Linux/BSD: libgravity.so, links -lm
- Windows: gravity.dll, links Shlwapi

Dependencies Copy Section

- C99-compatible compiler
- Standard C library (including math.h)
- Platform headers (dirent.h, sys/time.h, or Windows equivalents)
- No external library dependencies

---

12. Test Infrastructure Copy Chapter

Test Format Copy Section

Unit tests are individual .gravity files in test/unittest/. Each test declares expected results in a metadata block:

#unittest {
    name: "Test description";
    result: expected_value;
};
func main() {
    // test logic
    return actual_value;
}

The test runner compiles and executes each file, then compares the return value of main() against the declared result.

Test Metadata Fields Copy Section

| Field | Purpose |
|-------|---------|
| name | Human-readable test description |
| result | Expected return value (compared with ==) |
| expected_error | Expected error type (for negative tests) |
| expected_row | Expected error line number |
| expected_col | Expected error column number |

Running Tests Copy Section

./gravity -t test/unittest/              # run all tests
./test/unittest/run_all.sh               # run with timeouts (used by CI)
./gravity test/unittest/test_file.gravity # run a single test

Test Organization Copy Section

Tests are organized by category in subdirectories: compiler phases, language features, built-in types, optional modules, edge cases, and bug regressions. The runner recursively scans the target directory, skips any /disabled/ subdirectories, and applies fuzzy comparison for tests under /fuzzy/.

CI runs: make && test/unittest/run_all.sh

---

CHANGELOG Copy Section

Changelog

All notable changes to Gravity are documented in this file.

[Unreleased] Copy Chapter

Fixed Copy Section

Removed Copy Section

Changed Copy Section

---

[0.9.8] - 2026-08-05 Copy Chapter

Security and memory-safety release. Every issue below was found by external
reporters fuzzing the compiler and the bytecode loader, and each fix ships with
a regression test.

Fixed Copy Section

Added Copy Section

Changed Copy Section

---

[0.9.7] - 2026-04-14 Copy Chapter

Fixed Copy Section

Changed Copy Section

---

[0.9.6] - 2026-04-14 Copy Chapter

Fixed Copy Section

Added Copy Section

Changed Copy Section

---

[0.9.5] - 2024 Copy Chapter

Fixed Copy Section

Changed Copy Section

---

[0.9.0] - 2023 Copy Chapter

Fixed Copy Section

Added Copy Section

---

[0.8.5] - 2022 Copy Chapter

Fixed Copy Section

Added Copy Section

---

[0.8.4] - 2022 Copy Chapter

Fixed Copy Section

---

[0.8.3] - 2021 Copy Chapter

Fixed Copy Section

---

[0.8.2] - 2021 Copy Chapter

Added Copy Section

Fixed Copy Section

Changed Copy Section

---

[0.7.9] - 2020 Copy Chapter

Fixed Copy Section

Added Copy Section

---

[0.7.8] - 2020 Copy Chapter

Added Copy Section

Fixed Copy Section

---

[0.7.7] - 2020 Copy Chapter

Fixed Copy Section

---

[0.7.6] - 2020 Copy Chapter

Changed Copy Section

Fixed Copy Section

---

[0.7.5] - 2020 Copy Chapter

Improved Copy Section

---

[0.7.4] - 2020 Copy Chapter

Fixed Copy Section

Added Copy Section

---

[0.7.0] - 2019 Copy Chapter

Added Copy Section

Fixed Copy Section

---

[0.6.x] - 2018–2019 Copy Chapter

Series of incremental releases adding language features (closures, ranges, maps, lists, optional modules) and fixing compiler and runtime issues. See git history for per-commit details.

---

[0.5.x] - 2017–2018 Copy Chapter

Initial public release series establishing the core language, VM, and compiler pipeline.

---

CONTRIBUTING Copy Section

#### Contributing to Gravity
Everyone is welcome to contribute to Gravity. Contributing doesn’t just mean submitting pull requests,
there are many different ways for you to get involved, including reporting bugs, add new functionalities
or just participating in the project.

#### Where to make changes
Core libraries and documentation is probably the areas that need major contribution.
Any change to the core VM or other parts of the compiler are welcomed.

#### Code style and syntax rules
Looking at the Gravity source code I think you can easily follow the same coding style and syntax rule.
Private functions usually don't begin with a gravity_ prefix and are marked as static.
Feel free to expand this section with a more formal description of the syntax rules.

#### Testing rules
If you fix a bug or if you add a new functionality then a unit-test is required.
A unit-test is a single source code file that is able to run under the unittest executable file.
You are free to test your functionalities/fixes into a single unit-test file or split the test in more files.

#### Add Docs
If you add new functionality, or edit the way that current functionality works,
add or edit the docs to reflect this so that there is documentation of the new
changes for new users.

#### Contributors File
Don't forget to add your name and your email address to the official CONTRIBUTORS file!

---

README Copy Section

<p align="center" >
<img src="https://raw.githubusercontent.com/marcobambini/gravity/master/docs/assets/images/logo-gravity.png" height="74px" alt="Gravity Programming Language" title="Gravity Programming Language">
</p>

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 <a href="https://github.com/apple/swift">Swift</a>-like syntax.

Gravity supports procedural programming, object-oriented programming, functional programming, and data-driven programming. Thanks to special built-in methods, it can also be used as a prototype-based programming language.

Gravity has been developed from scratch for the <a href="http://creolabs.com" target="_blank">Creo</a> project in order to offer an easy way to write portable code for the iOS and Android platforms. It is written in portable C code that can be compiled on any platform using a C99 compiler. The VM code is about 6.5K lines long, the multipass compiler code is about 10K lines and the shared code is about 4.7K lines long. The compiler and virtual machine combined add less than 200KB to the executable on a 64-bit system.

What Gravity code looks like Copy Chapter

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 Copy Chapter

Building Copy Chapter

Make (Linux / macOS / BSD)

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)

cmake -B build
cmake --build build
Optionally disable the CLI and build the library only:

cmake -B build -DBUILD_CLI=OFF
cmake --build build

Requires a C99 compiler. No external dependencies.

Usage Copy Chapter

./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 Copy Chapter

./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 Copy Chapter

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.

Embedding API Copy Chapter

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:

#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 and the embedding documentation for the full bridging API.

Special thanks Copy Chapter

Documentation Copy Chapter

Where Gravity is used Copy Chapter

Changelog Copy Chapter

See CHANGELOG.md for a summary of changes across versions.

Community Copy Chapter

[](https://github.com/marcobambini/gravity/discussions)

Questions, ideas, and general discussion are welcome in GitHub Discussions.

Contributing Copy Chapter

License Copy Chapter

---