Identifiers start with a alphabetic character or '_' followed by any number of alphabetic characters, '_' or digits ([0-9]). Squirrel is a case sensitive language, this means that the lowercase and uppercase representation of the same alphabetic character are considered different characters. For instance "foo", "Foo" and "fOo" will be treated as 3 distinct identifiers.

id:= [a-zA-Z_]+[a-zA-Z_0-9]*

The following words are reserved words by the language and cannot be used as identifiers:

Keywords are covered in detail later in this document.

Squirrel recognizes the following operators:

Other used tokens are:

Squirrel accepts integer numbers, floating point numbers and strings literals.

IntegerLiteral := [1-9][0-9]* | '0x' [0-9A-Fa-f]+ | ''' [.]+ ''' | 0[0-7]+
FloatLiteral := [0-9]+ '.' [0-9]+
FloatLiteral := [0-9]+ '.' 'e'|'E' '+'|'-' [0-9]+
StringLiteral:= '"'[.]* '"'
VerbatimStringLiteral:= '@''"'[.]* '"'
      

The /* (slash, asterisk) characters, followed by any sequence of characters (including new lines), followed by the */ characters. This syntax is the same as ANSI C.

/* 
this is
a multiline comment.
this lines will be ignored by the compiler
*/				
				

The // (two slashes) characters, followed by any sequence of characters. A new line not immediately preceded by a backslash terminates this form of comment. It is commonly called a “single-line comment.”

//this is a single line comment. this line will be ignored by the compiler 
				

The character # is an alternative syntax for single line comment.

          
#this is also a single line comment.
        

This to facilitate the use of squirrel in UNIX-style shell scripts.

An Integer represents a 32 bits (or better) signed number.

local a = 123 //decimal
local b = 0x0012 //hexadecimal
local c = 075 //octal
local d = 'w' //char code
      

A float represents a 32 bits (or better) floating point number.

local a=1.0
local b=0.234
			

Strings are an immutable sequence of characters to modify a string is necessary create a new one.

Squirrel's strings, behave like C or C++, are delimited by quotation marks(") and can contain escape sequences(\t,\a,\b,\n,\r,\v,\f,\\,\",\',\0,\xhhhh).

Verbatim string literals begin with @" and end with the matching quote. Verbatim string literals also can extend over a line break. If they do, they include any white space characters between the quotes:

local a = "I'm a wonderful string\n"
// has a newline at the end of the string
local x = @"I'm a verbatim string\n"
// the \n is copied in the string same as \\n in a regular string "I'm a verbatim string\n"

The only exception to the "no escape sequence" rule for verbatim string literals is that you can put a double quotation mark inside a verbatim string by doubling it:

local multiline = @"
	this is a multiline string
	it will ""embed"" all the new line 
	characters
"
			

The null value is a primitive value that represents the null, empty, or non-existent reference. The type Null has exactly one value, called null.

local a=null
			

the bool data type can have only two. They are the literals true and false. A bool value expresses the validity of a condition (tells whether the condition is true or false).

local a = true;
			

Tables are associative containers implemented as pairs of key/value (called a slot).

local t={}
local test=
{
    a=10
    b=function(a) { return a+1; }
}
			

Arrays are simple sequence of objects, their size is dynamic and their index starts always from 0.

local a=["I'm","an","array"]
local b=[null]
b[0]=a[2];
			

Functions are similar to those in other C-like languages and to most programming languages in general, however there are a few key differences (see below).

Classes are associative containers implemented as pairs of key/value. Classes are created through a 'class expression' or a 'class statement'. class members can be inherited from another class object at creation time. After creation members can be added until a instance of the class is created.

Class instances are created by calling a class object. Instances, as tables, are implemented as pair of key/value. Instances members cannot be dyncamically added or removed however the value of the members can be changed.

Generators are functions that can be suspended with the statement 'yield' and resumed later (see Generators).

Userdata objects are blobs of memory(or pointers) defined by the host application but stored into Squirrel variables (See Userdata and UserPointers).

Threads are objects that represents a cooperative thread of execution, also known as coroutines.

Weak References are objects that point to another(non scalar) object but do not own a strong reference to it. (See Weak References).

There are two types of variables in Squirrel, local variables and tables/arrays slots. Because global variables are stored in a table, they are table slots.

A single identifier refers to a local variable or a slot in the environment object.

derefexp := id;

_table["foo"]
_array[10]

with tables we can also use the '.' syntax

derefexp := exp '.' id

_table.foo

Squirrel first checks if an identifier is a local variable (function arguments are local variables) if not it checks if it is a member of the environment object (this).

For instance:

function testy(arg)
{
    local a=10;
    print(a);
    return arg;
}			
			

will access to local variable 'a' and prints 10.

function testy(arg)
{
    local a=10;
    return arg+foo;
}
			

in this case 'foo' will be equivalent to 'this.foo' or this["foo"].

Global variables are stored in a table called the root table. Usually in the global scope the environment object is the root table, but to explicitly access the global table from another scope, the slot name must be prefixed with '::' (::foo).

exp:= '::' id

For instance:

function testy(arg)
{
    local a=10;
    return arg+::foo;
}
			

accesses the global variable 'foo'.

However (since squirrel 2.0) if a variable is not local and is not found in the 'this' object Squirrel will search it in the root table.

function test() {
	foo = 10;
}

is equivalent to write

function test() {
	if("foo" in this) {
		this.foo = 10;
	}else {
		::foo = 10;
	}
}

stat := '{' stats '}'

A sequence of statements delimited by curly brackets ({ }) is called block; a block is a statement itself.

squirrel implements the most common control flow statements: if, while, do-while, switch-case, for, foreach.

stat:= 'if' '(' exp ')' stat ['else' stat]

if(a>b)
    a=b;
else
    b=a;
////
if(a==10)
{
    b=a+b;
    return a;
}
				

stat:= 'while' '(' exp ')' stat

				
function testy(n)
{
    local a=0;
    while(a<n) a+=1;
	
	while(1)
	{
        if(a<0) break;
        a-=1;
    }
}					
				

stat:= 'do' stat 'while' '(' expression ')'

				
local a=0;
do
{
    print(a+"\n");
    a+=1;
} while(a>100)			
				

stat := 'switch' ''( exp ')' '{'
	'case' case_exp ':'
		stats
	['default' ':'
		stats]
'}'
				

stat := 'break'

The break statement terminates the execution of a loop (for, foreach, while or do/while) or jumps out of switch statement;

stat := 'continue'

The continue operator jumps to the next iteration of the loop skipping the execution of the following statements.

stat:= return [exp]

The return statement terminates the execution of the current function/generator and optionally returns the result of an expression. If the expression is omitted the function will return null. If the return statement is used inside a generator, the generator will not be resumable anymore.

stat := yield [exp]

(see Generators).

initz := id [= exp][',' initz]
stat := 'local' initz
			

Local variables can be declared at any point in the program; they exist between their declaration to the end of the block where they have been declared. EXCEPTION: a local declaration statement is allowed as first expression in a for loop.

for(local a=0;a<10;a+=1)
    print(a); 
			

funcname := id ['::' id]
stat:= 'function' id ['::' id]+ '(' args ')'[':' '(' args ')'] stat
			

creates a new function.

memberdecl := id '=' exp [';'] |	'[' exp ']' '=' exp [';'] |	functionstat | 'constructor' functionexp
stat:= 'class' derefexp ['extends' derefexp] '{'
			[memberdecl]
		'}'
			

creates a new class.

stat:= 'try' stat 'catch' '(' id ')' stat

The try statement encloses a block of code in which an exceptional condition can occur, such as a runtime error or a throw statement. The catch clause provides the exceptionhandling code. When a catch clause catches an exception, its id is bound to that exception.

stat:= 'throw' exp

Throws an exception. Any value can be thrown.

stat:= 'const' id '=' 'Integer | Float | StringLiteral
      

Declares a constant (see Constants & Enumerations).

        
          enumerations := ( ‘id’ '=' Integer | Float | StringLiteral ) [‘,’]
          stat:= 'enum' id '{' enumerations '}'
        
      

Declares an enumeration (see Constants & Enumerations).

stat := exp

In Squirrel every expression is also allowed as statement, if so, the result of the expression is thrown away.

exp := derefexp '=' exp
exp:= derefexp '<-' exp
			

squirrel implements 2 kind of assignment: the normal assignment(=)

a=10;

and the "new slot" assignment.

a <- 10;

The new slot expression allows to add a new slot into a table(see Tables). If the slot already exists in the table it behaves like a normal assignment.

tslots := ( ‘id’ ‘=’ exp | ‘[‘ exp ‘]’ ‘=’ exp ) [‘,’]
exp := ‘{’ [tslots] ‘}’
			

Creates a new table.

local a={} //create an empty table				
			

A table constructor can also contain slots declaration; With the syntax:

id = exp [',']

a new slot with id as key and exp as value is created

local a=
{
    slot1="I'm the slot value"
}
			

An alternative syntax can be

'[' exp1 ']' = exp2 [',']

A new slot with exp1 as key and exp2 as value is created

local a=
{
    [1]="I'm the value"
}
			

both syntaxes can be mixed

local table=
{
    a=10,
    b="string",
    [10]={},
    function bau(a,b)
    {
        return a+b;
    }
}
			

The comma between slots is optional.

local x = {
  "id": 1,
  "name": "Foo",
  "price": 123,
  "tags": ["Bar","Eek"]
}
        

local x = {
  id = 1,
  name = "Foo",
  price = 123,
  tags = ["Bar","Eek"]
}
       

exp:= ‘clone’ exp

Clone performs shallow copy of a table, array or class instance (copies all slots in the new object without recursion). If the source table has a delegate, the same delegate will be assigned as delegate (not copied) to the new table (see Delegation).

After the new object is ready the “_cloned” meta method is called (see Metamethods).

When a class instance is cloned the constructor is not invoked(initializations must rely on _cloned instead

exp := ‘[’ [explist] ‘]’

Creates a new array.

a <- [] //creates an empty array
			

arrays can be initialized with values during the construction

a <- [1,"string!",[],{}] //creates an array with 4 elements
			

Tables are created through the table constructor (see Table constructor)

Adding a new slot in a existing table is done through the "new slot" operator '<-'; this operator behaves like a normal assignment except that if the slot does not exists it will be created.

local a={}
			

The following line will cause an exception because the slot named 'newslot' does not exist in the table ‘a’

a.newslot = 1234
			

this will succeed:

a.newslot <- 1234;
			

or

a[1] <- "I'm the value of the new slot";
			

exp:= delete derefexp

Deletion of a slot is done through the keyword delete; the result of this expression will be the value of the deleted slot.

a <- {
    test1=1234
    deleteme="now"
}

delete a.test1
print(delete a.deleteme); //this will print the string "now"
			

Functions are declared through the function expression

local a= function(a,b,c) {return a+b-c;}		
			

or with the syntactic sugar

function ciao(a,b,c)
{
    return a+b-c;
}		
			

that is equivalent to

this.ciao <- function(a,b,c)
{
    return a+b-c;
}
			

a local function can be declared with this syntactic sugar

        
local function tuna(a,b,c)
{
    return a+b-c;
}
			
      

that is equivalent to

        
local tuna = function(a,b,c)
{
    return a+b-c;
}
			
      

is also possible to declare something like

T <- {}
function T::ciao(a,b,c)
{
    return a+b-c;
}

//that is equivalent to write

T.ciao <- function(a,b,c)
{
    return a+b-c;
}

//or

T <- {
	function ciao(a,b,c)
	{
		return a+b-c;
	}
}
			

        
function test(a,b,c = 10, d = 20)
{
	....
}
        
        

      
function test(a,b,...)
{
	for(local i = 0; i< vargv.len(); i++)
	{
		::print("varparam "+i+" = "+vargv[i]+"\n");
	}
  foreach(i,val in vargv)
	{
		::print("varparam "+i+" = "+val+"\n");
	}
}

test("goes in a","goes in b",0,1,2,3,4,5,6,7,8);
			  

exp:= derefexp ‘(‘ explist ‘)’

The expression is evaluated in this order: derefexp after the explist (arguments) and at the end the call.

Every function call in Squirrel passes the environment object ‘this’ as hidden parameter to the called function. The ‘this’ parameter is the object where the function was indexed from.

If we call a function with this syntax

table.foo(a)
			

the environment object passed to foo will be ‘table’

foo(x,y) // equivalent to this.foo(x,y)
			

The environment object will be ‘this’ (the same of the caller function).

while by default a squirrel function call passes as environment object 'this', the object where the function was indexed from. However, is also possible to statically bind an evironment to a closure using the built-in method closure.bindenv(env_obj). The method bindenv() returns a new instance of a closure with the environment bound to it. When an environment object is bound to a function, every time the function is invoked, its 'this' parameter will always be the previously bound environent. This mechanism is useful to implement callbacks systems similar to C# delegates.

exp := '@' '(' paramlist ')' exp

Lambda expressions are a synctactic sugar to quickly define a function that consists of a single expression. This feature comes handy when functional programming patterns are applied, like map/reduce or passing a compare method to array.sort().

here a lambda expression

        local myexp = @(a,b) a + b

that is equivalent to

        local myexp = function(a,b) { return a + b; }

a more useful usage could be

        local arr = [2,3,5,8,3,5,1,2,6];
        arr.sort(@(a,b) a <=> b);
        arr.sort(@(a,b) -(a <=> b));

that could have been written as

        local arr = [2,3,5,8,3,5,1,2,6];
        arr.sort(function(a,b) { return a <=> b; } );
        arr.sort(function(a,b) { return -(a <=> b); } );

other than being limited to a single expression lambdas support all features of regular functions. in fact are implemented as a compile time feature.

A free variable is a variable external from the function scope as is not a local variable or parameter of the function. Free variables reference a local variable from a outer scope. In the following example the variables 'testy', 'x' and 'y' are bound to the function 'foo'.

local x=10,y=20
local testy=“I’m testy”

function foo(a,b)
{
    ::print(testy);
    return a+b+x+y;
}
			

A program can read or write a free variable.

Tail recursion is a method for partially transforming a recursion in a program into an iteration: it applies when the recursive calls in a function are the last executed statements in that function (just before the return). If this happenes the squirrel interpreter collapses the caller stack frame before the recursive call; because of that very deep recursions are possible without risk of a stack overflow.

function loopy(n)
{
    if(n>0){
        ::print(“n=”+n+”\n”);
        return loopy(n-1);
    }
}

loopy(1000);
			

A class object is created through the keyword 'class' . The class object follows the same declaration syntax of a table(see tables) with the only difference of using ';' as optional separator rather than ','.

For instance:

class Foo {
	//constructor
	constructor(a)
	{
		testy = ["stuff",1,2,3,a];
	}
	//member function
	function PrintTesty()
	{
		foreach(i,val in testy)
		{
			::print("idx = "+i+" = "+val+" \n");
		}
	}
	//property
	testy = null;
	
}

the previous code examples is a syntactic sugar for:

Foo <- class {
	//constructor
	constructor(a)
	{
		testy = ["stuff",1,2,3,a];
	}
	//member function
	function PrintTesty()
	{
		foreach(i,val in testy)
		{
			::print("idx = "+i+" = "+val+" \n");
		}
	}
	//property
	testy = null;
	
}

in order to emulate namespaces, is also possible to declare something like this

//just 2 regular nested tables
FakeNamespace <- {
	Utils = {}
}

class FakeNamespace.Utils.SuperClass {
	constructor()
	{
		::print("FakeNamespace.Utils.SuperClass")
	}
	function DoSomething()
	{
		::print("DoSomething()")
	}
}

function FakeNamespace::Utils::SuperClass::DoSomethingElse()
{
	::print("FakeNamespace::Utils::SuperClass::DoSomethingElse()")
}

local testy = FakeNamespace.Utils.SuperClass();
testy.DoSomething();
testy.DoSomethingElse();

After its declaration, methods or properties can be added or modified by following the same rules that apply to a table(operator <- and =).

//adds a new property
Foo.stuff <- 10;

//modifies the default value of an existing property
Foo.testy = "I'm a string";

//adds a new method
function Foo::DoSomething(a,b)
{
	return a+b;
}

After a class is instantiated is no longer possible to add new properties however is possible to add or replace methods.

class Foo {
	constructor()
	{
		//..stuff
	}
	name = "normal variable";
	//static variable
	static classname = "The class name is foo";
};

class Foo </ test = "I'm a class level attribute" />{
	</ test = "freakin attribute" /> //attributes of PrintTesty
	function PrintTesty()
	{
		foreach(i,val in testy)
		{
			::print("idx = "+i+" = "+val+" \n");
		}
	}
	</ flippy = 10 , second = [1,2,3] /> //attributes of testy
	testy = null;
	
}

foreach(member,val in Foo)
{
	::print(member+"\n");
	local attr;
	if((attr = Foo.getattributes(member)) != null) {
		foreach(i,v in attr)
		{
			::print("\t"+i+" = "+(typeof v)+"\n");
		}
	}
	else {
		::print("\t<no attributes>\n")
	}
}

The class objects inherits several of the table's feature with the difference that multiple instances of the same class can be created. A class instance is an object that share the same structure of the table that created it but holds is own values. Class instantiation uses function notation. A class instance is created by calling a class object. Can be useful to imagine a class like a function that returns a class instance.

//creates a new instance of Foo
local inst = Foo(); 

When a class instance is created its member are initialized with the same value specified in the class declaration. The values are copied verbatim, no cloning is performed even if the value is a container or a class instances.

class Foo {
  myarray = [1,2,3]
  mytable = {}
}

local a = Foo();
local b = Foo();

class Foo {
  myarray = null
  mytable = null
  constructor()
  {
    myarray = [1,2,3]
    mytable = {}
  }
}

local a = Foo();
local b = Foo();

When a class defines a method called 'constructor', the class instantiation operation will automatically invoke it for the newly created instance. The constructor method can have parameters, this will impact on the number of parameters that the instantiation operation will require. Constructors, as normal functions, can have variable number of parameters (using the parameter ...).

class Rect {
	constructor(w,h)
	{
		width = w;
		height = h;		
	}
	x = 0;
	y = 0;
	width = null;
	height = null;
}

//Rect's constructor has 2 parameters so the class has to be 'called'
//with 2 parameters
local rc = Rect(100,100);
 

After an instance is created, its properties can be set or fetched following the same rules that apply to tables. Methods cannot be set.

Instance members cannot be removed.

The class object that created a certain instance can be retrieved through the built-in function instance.getclass()(see built-in functions)

The operator instanceof tests if a class instance is an instance of a certain class.

local rc = Rect(100,100);
if(rc instanceof ::Rect) {
	::print("It's a rect");
}
else {
	::print("It isn't a rect");
}
			

Squirrel's classes support single inheritance by adding the keyword extends, followed by an expression, in the class declaration. The syntax for a derived class is the following:

class SuperFoo extends Foo {
	function DoSomething() {
		::print("I'm doing something");
	}
}
			

When a derived class is declared, Squirrel first copies all base's members in the new class then proceeds with evaluating the rest of the declaration.

A derived class inherit all members and properties of it's base, if the derived class overrides a base function the base implementation is shadowed. It's possible to access a overridden method of the base class by fetching the method from through the 'base' keyword.

Here an example:

class Foo {
	function DoSomething() {
		::print("I'm the base");
	}
};

class SuperFoo extends Foo {
	//overridden method
	function DoSomething() {
		//calls the base method
		base.DoSomething();
		::print("I'm doing something");
	}
}
			

Same rule apply to the constructor. The constructor is a regular function (apart from being automatically invoked on contruction).

  
class BaseClass {
	constructor()
	{
		::print("Base constructor\n");
	}
}

class ChildClass extends BaseClass {
	constructor()
	{
		base.constructor();
		::print("Child constructor\n");
	}
}

local test = ChildClass();

The base class of a derived class can be retrieved through the built-in method getbase().

local thebaseclass = SuperFoo.getbase();
			

A method of a base class can be explicitly invoked by a method of a derived class though the keyword base(as in base.MyMethod() ).

Class instances allow the customization of certain aspects of the their semantics through metamethods(see Metamethods). For C++ programmers: "metamethods behave roughly like overloaded operators". The metamethods supported by classes are _add, _sub, _mul, _div, _unm, _modulo, _set, _get, _typeof, _nexti, _cmp, _call, _delslot,_tostring

Class objects instead support only 2 metamethods : _newmember and _inherited

the following example show how to create a class that implements the metamethod _add.

class Vector3 {
	constructor(...)
	{
		if(vargv.len() >= 3) {
			x = vargv[0];
			y = vargv[1];
			z = vargv[2];
		}
	}
	function _add(other)
	{
		return ::Vector3(x+other.x,y+other.y,z+other.z);
	}
	
	x = 0;
	y = 0;
	z = 0;
}

local v0 = Vector3(1,2,3)
local v1 = Vector3(11,12,13)
local v2 = v0 + v1;
::print(v2.x+","+v2.y+","+v2.z+"\n");

Since version 2.1, classes support 2 metamethods _inherited and _newmember. _inherited is invoked when a class inherits from the one that implements _inherited. _newmember is invoked for each member that is added to the class(at declaration time).

Constants bind a specific value to an indentifier. Constants are similar to global values, except that they are evaluated compile time and their value cannot be changed.

constants values can only be integers, floats or string literals. No expression are allowed. are declared with the following syntax.

          
const foobar = 100;
const floatbar = 1.2;
const stringbar = "I'm a contant string";
          
        

constants are always globally scoped, from the moment they are declared, any following code can reference them. Constants will shadow any global slot with the same name( the global slot will remain visible by using the :: syntax).

         
local x = foobar * 2;
        
        

As Constants, Enumerations bind a specific value to a name. Enumerations are also evaluated compile time and their value cannot be changed.

An enum declaration introduces a new enumeration into the program. Enumerations values can only be integers, floats or string literals. No expression are allowed.

        
enum Stuff {
  first, //this will be 0
  second, //this will be 1
  third //this will be 2
}
        
        

or

enum Stuff {
  first = 10
  second = "string"
  third = 1.2
}

 

An enum value is accessed in a manner that's similar to accessing a static class member. The name of the member must be qualified with the name of the enumeration, for example Stuff.second. Enumerations will shadow any global slot with the same name( the global slot will remain visible by using the :: syntax).

          
local x = Stuff.first * 2;

        

Enumerations and Contants are a compile-time feature. Only integers, string and floats can be declared as const/enum; No expressions are allowed(because they would have to be evaluated compile time). When a const or an enum is declared, it is added compile time to the consttable. This table is stored in the VM shared state and is shared by the VM and all its threads. The consttable is a regular squirrel table; In the same way as the roottable it can be modified runtime. You can access the consttable through the built-in function getconsttable() and also change it through the built-in function setconsttable()

here some example:

          
//create a constant
getconsttable()["something"] <- 10"
//create an enumeration
getconsttable()["somethingelse"] <- { a = "10", c = "20", d = "200"};
//deletes the constant
delete getconsttable()["something"]
//deletes the enumeration
delete getconsttable()["somethingelse"]
        
        

This system allows to procedurally declare constants and enumerations, it is also possible to assign any squirrel type to a constant/enumeration(function,classes etc...). However this will make serialization of a code chunk impossible.

Threads are created through the built-in function 'newthread(func)'; this function gets as parameter a squirrel function and bind it to the new thread objecs(will be the thread body). The returned thread object is initially in 'idle' state. the thread can be started with the function 'threadobj.call()'; the parameters passed to 'call' are passed to the thread function.

A thread can be be suspended calling the function suspend(), when this happens the function that wokeup(or started) the thread returns (If a parametrer is passed to suspend() it will be the return value of the wakeup function , if no parameter is passed the return value will be null). A suspended thread can be resumed calling the funtion 'threadobj.wakeup', when this happens the function that suspended the thread will return(if a parameter is passed to wakeup it will be the return value of the suspend function, if no parameter is passed the return value will be null).

A thread terminates when its main function returns or when an unhandled exception occurs during its execution.

function coroutine_test(a,b)
{
	::print(a+" "+b+"\n");
	local ret = ::suspend("suspend 1");
	::print("the coroutine says "+ret+"\n");
	ret = ::suspend("suspend 2");
	::print("the coroutine says "+ret+"\n");
	ret = ::suspend("suspend 3");
	::print("the coroutine says "+ret+"\n");
	return "I'm done"
}

local coro = ::newthread(coroutine_test);

local susparam = coro.call("test","coroutine"); //starts the coroutine

local i = 1;
do
{
	::print("suspend passed ("+susparam+")\n")
	susparam = coro.wakeup("ciao "+i);
	++i;
}while(coro.getstatus()=="suspended")

::print("return passed ("+susparam+")\n")
		

the result of this program will be

test coroutine
suspend passed (suspend 1)
the coroutine says ciao 1
suspend passed (suspend 2)
the coroutine says ciao 2
suspend passed (suspend 3)
the coroutine says ciao 3
return passed (I'm done).
		

the following is an interesting example of how threads and tail recursion can be combined.

		
function state1()
{
	::suspend("state1");
	return state2(); //tail call
}

function state2()
{
	::suspend("state2");
	return state3(); //tail call
}

function state3()
{
	::suspend("state3");
	return state1(); //tail call
}

local statethread = ::newthread(state1)

::print(statethread.call()+"\n");

for(local i = 0; i < 10000; i++)
	::print(statethread.wakeup()+"\n");

If a weak reference is assigned to a local variable, then is treated as any other value.

local t = {}
local weakobj = t.weakref();
			

the following line prints "weakref".

::print(typeof(weakobj))
			

the object pointed by the weakref can be obtained through the built-in method weakref.ref().

The following line prints "table".

::print(typeof(weakobj.ref()))
			

invoked when the index idx is not present in the object or in its delegate chain. _set must 'throw null' to notify that a key wasn't found but the there were not runtime errors(clean failure). This allows the program to defferentieate between a runtime error and a 'index not found'.

function _set(idx,val) //returns val

invoked when the index idx is not present in the object or in its delegate chain. _get must 'throw null' to notify that a key wasn't found but the there were not runtime errors(clean failure). This allows the program to defferentieate between a runtime error and a 'index not found'.

function _get(idx) //return the fetched values

invoked when a script tries to add a new slot in a table.

function _newslot(key,value) //returns val

if the slot already exists in the target table the method will not be invoked also if the “new slot” operator is used.

invoked when a script deletes a slot from a table.

if the method is invoked squirrel will not try to delete the slot himself

function _delslot(key)

the + operator

function _add(op) //returns this+op

the – operator (like _add)

the * operator (like _add)

the / operator (like _add)

the % operator (like _add)

the unary minus operator

function _unm()

invoked by the typeof operator on tables ,userdata and class instances

function _typeof() //returns the type of this as string

invoked to emulate the < > <= >= operators

function _cmp(other)

returns an integer:

invoked when a table, userdata or class instance is called

function _call(original_this,params…)

invoked when a table or class instance is cloned(in the cloned table)

function _cloned(original)

invoked when a userdata or class instance is iterated by a foreach loop

function _nexti(previdx)

if previdx==null it means that it is the first iteration. The function has to return the index of the ‘next’ value.

invoked when during string conacatenation or when the print function prints a table, instance or userdata. The method is also invoked by the sq_tostring() api

function _tostring()

must return a string representation of the object.

invoked when a class object inherits from the class implementing _inherited the this contains the new class.

function _inherited(attributes)

return value is ignored.

invoked for each member declared in a class body(at declaration time).

function _newmember(index,value,attributes,isstatic)

if the function is implemented, members will not be added to the class.

array(size,[fill])

create and returns array of a specified size.if the optional parameter fill is specified its value will be used to fill the new array's slots. If the fill paramter is omitted null is used instead.

seterrorhandler(func)

sets the runtime error handler

callee()

returns the currently running closure

setdebughook(hook_func)

sets the debug hook

enabledebuginfo(enable)

enable/disable the debug line information generation at compile time. enable != null enables . enable == null disables.

getroottable()

returns the root table of the VM.

setroottable(table)

sets the root table of the VM. And returns the previous root table.

getconsttable()

returns the const table of the VM.

setconsttable(table)

sets the const table of the VM. And returns the previous const table.

assert(exp)

throws an exception if exp is null

print(x)

prints x in the standard output

error(x)

prints x in the standard error output

compilestring(string,[buffername])

compiles a string containing a squirrel script into a function and returns it

local compiledscript=compilestring("::print(\"ciao\")");
//run the script				
compiledscript();
				

collectgarbage()

runs the garbage collector and returns the number of reference cycles found(and deleted) This function only works on garbage collector builds.

resurrectunreachable()

runs the garbage collector and returns an array containing all unreachable object found. If no unreachable object is found, null is returned instead. This function is meant to help debugging reference cycles. This function only works on garbage collector builds.

type(obj)

return the 'raw' type of an object without invoking the metatmethod '_typeof'.

getstackinfos(level)

returns the stack informations of a given call stack level. returns a table formatted as follow:

{
	func="DoStuff",	//function name
	
	src="test.nut",	//source file
	
	line=10,		//line number
	
	locals = {		//a table containing the local variables
	
		a=10,
		
		testy="I'm a string"
	}
}
				

level = 0 is the current function, level = 1 is the caller and so on. If the stack level doesn't exist the function returns null.

newthread(threadfunc)

creates a new cooperative thread object(coroutine) and returns it

_versionnumber_

integer values describing the version of VM and compiler. eg. for Squirrel 3.0.1 this value will be 301

_version_

string values describing the version of VM and compiler.

_charsize_

size in bytes of the internal VM rapresentation for characters(1 for ASCII builds 2 for UNICODE builds).

_intsize_

size in bytes of the internal VM rapresentation for integers(4 for 32bits builds 8 for 64bits builds).

_floatsize_

size in bytes of the internal VM rapresentation for floats(4 for single precision builds 8 for double precision builds).

Except null and userdata every squirrel object has a default delegate containing a set of functions to manipulate and retrieve information from the object itself.

function custom_compare(a,b)
{
	if(a>b) return 1
	else if(a<b) return -1
	return 0;
}
					

arr.sort(@(a,b) a <=> b);
        

  
//the data is returned as a table is in form
//pure squirrel function
{
  native = false
  name = "zefuncname"
  src = "/somthing/something.nut"
  parameters = ["a","b","c"]
  defparams = [1,"def"]
  varargs = 2
}
//native C function
{
  native = true
  name = "zefuncname"
  paramscheck = 2
  typecheck = [83886082,83886384] //this is the typemask (see C defines OT_INTEGER,OT_FLOAT etc...)
}

  

Many API functions can arbitrarily refer to any element in the stack through an index. The stack indexes follow those conventions:

Here an example (let’s pretend that this table is the VM stack)

In this case, the function sq_gettop would return 4;

The API offers several functions to push and retrieve data from the Squirrel stack.

To push a value that is already present in the stack in the top position

void sq_push(HSQUIRRELVM v,SQInteger idx);

To pop an arbitrary number of elements

void sq_pop(HSQUIRRELVM v,SQInteger nelemstopop);

To remove an element from the stack

void sq_remove(HSQUIRRELVM v,SQInteger idx);

To retrieve the top index (and size) of the current virtual stack you must call sq_gettop

SQInteger sq_gettop(HSQUIRRELVM v);

To force the stack to a certain size you can call sq_settop

void sq_settop(HSQUIRRELVM v,SQInteger newtop);

If the newtop is bigger than the previous one, the new posistions in the stack will be filled with null values.

The following function pushes a C value into the stack

void sq_pushstring(HSQUIRRELVM v,const SQChar *s,SQInteger len);
void sq_pushfloat(HSQUIRRELVM v,SQFloat f);
void sq_pushinteger(HSQUIRRELVM v,SQInteger n);
void sq_pushuserpointer(HSQUIRRELVM v,SQUserPointer p);
void sq_pushbool(HSQUIRRELVM v,SQBool b);
			

this function pushes a null into the stack

void sq_pushnull(HSQUIRRELVM v);

returns the type of the value in a arbitrary position in the stack

SQObjectType sq_gettype(HSQUIRRELVM v,SQInteger idx);

the result can be one of the following values:

OT_NULL,OT_INTEGER,OT_FLOAT,OT_STRING,OT_TABLE,OT_ARRAY,OT_USERDATA,
OT_CLOSURE,OT_NATIVECLOSURE,OT_GENERATOR,OT_USERPOINTER,OT_BOOL,OT_INSTANCE,OT_CLASS,OT_WEAKREF
				

The following functions convert a squirrel value in the stack to a C value

SQRESULT sq_getstring(HSQUIRRELVM v,SQInteger idx,const SQChar **c);
SQRESULT sq_getinteger(HSQUIRRELVM v,SQInteger idx,SQInteger *i);
SQRESULT sq_getfloat(HSQUIRRELVM v,SQInteger idx,SQFloat *f);
SQRESULT sq_getuserpointer(HSQUIRRELVM v,SQInteger idx,SQUserPointer *p);
SQRESULT sq_getuserdata(HSQUIRRELVM v,SQInteger idx,SQUserPointer *p,SQUserPointer *typetag);
SQRESULT sq_getbool(HSQUIRRELVM v,SQInteger idx,SQBool *p);
			

The function sq_cmp compares 2 values from the stack and returns their relation (like strcmp() in ANSI C).

SQInteger sq_cmp(HSQUIRRELVM v);