GS9 Programming Language

12.EMBEDDING APPLICATIONS
A Programming Language Manual

12.1 Scripting languages

I told you before that GS9 is a programming language.
That is true, but to be more specific, it is a scripting language.

Don't worry! The scripts we are talking about are programs too. And you are still a programmer. The only difference is that script programs are not executed directly by your computer's processor (CPU). They are interpreted by a special program, usually written in an advanced programming language (like C/C++). This special program is acting as the processor of our script programs and it is called interpreter.

Script programs have their advantages but also their disadvantages. They are much simpler to use and they are much portable to other platforms. On the other hand they are slower than real executable and they need an interpreter application to run.

The GS9 interpreter is written in C++ and it can be used in any C++ application. Such an application that includes an interpreter to run scripts is called embedding aplication. And that's what our GS9 console is: a very simple application that feeds a GS9 interpreter with the script file given as parameter.

The embedding application can export (or register) advanced C functions that can be called from the script. All GS9 libraries are such exported functions. You can see their C source code in the library annexes. And of course, the embedding application can access the script variables and call the script functions, like the GS9 console does when it runs the main() script function.

Now, if you don't have C/C++ knowledge, or if you are not interested in including the GS9 interpreter in one of your own applications, then your road with this book has ended here. You can call yourself a programmer or a script programmer or any sort of programmer you like! You can start learning a more complicated programing language, or you can create some script tools to run with the GS9 console and do whatever you need them to do. For a fact, most of this book was created and formatted with a few such scripts.

Good luck!

Odd way to end a book, eh?
Well, for those interested in the GS9 interpreter, I will continue with a small presentation. I assume you have good C/C++ knowledge and you can understand the interpreter source code. So I will only point a few things.

12.2 The GS9 interpreter

For those familiar with script languages, GS9 is very similar in implementation to LUA.
Let's now have a look at the main components of the GS9 interpreter:

The compiler

The compiler is responsable for compiling the scripts and generating the GS9 machine code.

At it's base stay a lexer and a parser, that can understand the GS9 context-free grammar. Their source code, from gsparser.cpp and gslexer.cpp files, is generated using Flex and Bison (similar to Yacc) tools. So, don't bother to understand those C files. Instead, you can have a look at the grammar files that generated them: gslexer.l, gsparser.y. You can find information about how to compile the lexer and the parser, in the GS9 kit.

The exporter

The exporter is used to save scripts in a binary format, for fast loading. Usually the process is like this:

First the needed libraries or any other c functions are registered.
Remember now the registered globals count (gs_globalscount).
Compile all your scripts with their includes and everything.
Export the globals starting with the index stored before.

This will save only the globals registered from script. When loading, register c functions and use import. You can even exclude the compiler code if you want.

The enviroment

The compiled script is stored as GS9 machine code in a so called GS9 enviroment.

The enviroment is formed by all the functions and global variables form the compiled scripts. It's code is implemented in the gsEnv class from the gsenv.cpp and gsenv.h files. You usually have one such enviroment per application at a time.

The virtual state machine

The main component of the interpreter is the virtual state machine.

The state machine is a processor that executes machine code instructions, very similar to a real CPU.
It uses a functions call stack, and a data stack for sending and receiving parameters to and from functions. It is linked to an enviroment from where it runs instructions. It's code is implemented in the gsVM class from the gsvm.cpp and gsvm.h files. Since execution can be stopped in a latent mode, more instances of such virtual machines can run on the same enviroment, creating a multi-processor interpreter.

The user interface

This keeps the most common functions, as an user interface implemented in the gs.cpp and gs.h files.
There are functions to create a virtual state machine and an enviroment, to load and to run script files, to register functions and global variables from code and so one.

Exported functions and libraries

To export a C function and make it accessible from script, it must have a special format and it must be register it in the GS9 enviroment you use. The GS9 exportable function format is:

void gsFunctioName( gsVM* vm )

It receives the current state machine that called it and it can access the call parameters. It can return a value to the script by pushing it on the data stack. You can learn more about these functions, by inspecting the GS9 libraries source code.

User configuration

Developers can configure some basic functions and defines used by GS9 source code, to accomodate their applications. This includes memory allocation defines, files functions and others.
Check the gscfg.cpp and gscfg.h files.

12.3 A simple implementation

To add support for GS9 interpreter in your application, you have to follow a few very simple steps:

Include GS9 sources files in your project and add them to the include paths.
Include gs.h and eventual libraries, where you need GS9 support.
Initialize a virtual machine and an GS9 eviroment, like with gs_init function.
Register needed GS9 libraries and other particular functions.
Compile a script files with gs_compilefile function.
Run one or more script functions with gs_runfn function.
When you are done, destroy the virtual machine and the GS9 enviroment using gs_done.

Here is a C code example:

// example of application supporting GS9 scripts
#include "gs.h"
#include "gslib_default.h"
#include "gslib_math.h"

// an exportable function that will print the string parameter it receive
void gsMyFunction( gsVM* vm )
{
	if( !gs_cktype(vm,0,GS_STR) ) return; // error
	char* sz = gs_tostr(vm,0);
	gslog(sz);
}

// C staring point
int main(int argc, char* argv[])
{
	gsVM* vm = gs_init();                          // initialize and register the default library
	gslib_default(vm);                             // register default library
	gslib_math(vm);                                // register math library
	gs_regfnc(vm,"MyFunction", gsMyFunction );     // register the sample function

	int ret = gs_compilefile(vm,"program.txt");    // compiles the program.txt script file, where you can call MyFunction("test")
	if(ret!=GS_OK) { gs_done(vm); return -1; }
	int gid = gs_findglobal(vm,"main");            // finds the internal id of the main function
	if(gid==-1) { gs_done(vm); gslog("main() function not found.\n"); return -1; }
	
	                                               // push eventual parameters on the stack - none in this case
	gs_getglobal( vm, gid );                       // pushes on the stack the value of the global variable, in this case, the function
	gs_runfn( vm, 0 );                             // runs the function
	gs_pop( vm );                                  // always pop a returned value from the stack
	
	gs_done(vm);                                   // destroy virtual machine and enviroment
	return 0;
}

Well, for the target of this book, that should be enough.
For more examples you can check the GS9 libraries sources code, or you can contact me.

12.4 C++ objects access

GS9 has a special type for access to C++ class instances. To use it, you must derivate the C++ classes from the GS9 gsObj class and overwrite the Get, Set, and Call virtual methodes. An instance of such class can be exposed to script for use and access in a C++ style.

class MyObj : public gsObj
{
public:
	int i;
	
	virtual	void Set( gsVM* vm, gsStr* key )
	{ 
		int idx = gs_top(vm)-1;
		if( strcmp( key->m_text, "i" )==0 )
		{
			if( !gs_cktype( vm, idx, GS_INT ) ) 
				return;
			i = gs_toint( vm, idx );
		}
		else
			gs_error( vm, GSE_UNKNOWNMBR, key->m_text );
	}

	virtual	void Get( gsVM* vm, gsStr* key )			
	{
		if( strcmp( key->m_text, "i" )==0 )
			gs_pushint( vm, i );
		else
			gs_error( vm, GSE_UNKNOWNMBR, key->m_text );
	}

	virtual	void Call( gsVM* vm, gsStr* key )
	{
		if( strcmp( key->m_text, "Do" )==0 )
		{
			if( !gs_ckparams(vm,2) ||
				!gs_cktype(vm,0,GS_INT) ||
				!gs_cktype(vm,1,GS_INT) )
				return;
			int a = gs_toint(vm,0);
			int b = gs_toint(vm,1);
			gs_pushint( vm, a+b );
		}
		else
			gs_error( vm, GSE_UNKNOWNMBR, key->m_text );
	}
};

Later in code you can reate and register an instance of this class:

MyObj* obj = new MyObj();
obj->i = 0;
gs_regobj( vm, "myobj", obj );

And in script you can access it like this:

myobj.i = 1;
println( myobj.i ); // will print 1
println( myobj.Do( 10, 20 ) ); // will print 30