Starting up and running code

SGS_CTX = sgs_CreateEngine(); // SGS_CTX is alias to `sgs_Context* C`
sgs_Include( C, "something" );
sgs_ExecFile( C, "myscript.sgs" );
sgs_DestroyEngine( C );

• To do any kinds of operations with the scripting engine, it is first required to create it with sgs_CreateEngine or sgs_CreateEngineExt.
• When it's no longer necessary, it should be destroyed with sgs_DestroyEngine to free all used resources.
• Scripts can be loaded in many different ways. In this case, lookup differs:
  • sgs_Include tries to find the right file using the search path, and it supports loading of native libraries.
    • The search path is a special string on SGS_PATH that contains a combination of possible locations and extensions.
  • sgs_ExecFile expects a specific file and supports only script files (both compiled and source).

sgs_GlobalCall( C, "main", 0, 0 ); // may fail but it's not important in this case

• There are many ways to call functions. The easiest way is to call a global function.
• The arguments for sgs_GlobalCall are:
  • context pointer
  • global variable name
  • number of arguments to be passed (taken from the stack)
  • number of expected return values (to be pushed on stack if successfully called the function)

sgs_PushBool( C, 1 );
sgs_PushInt( C, 42 );
sgs_PushReal( C, 3.14159 );
sgs_PushString( C, "some C string" );
sgs_PushStringBuf( C, "not\0really\0C\0string", 19 );
sgs_PushPtr( C, C );
sgs_PushGlobalByName( C, "main" ); // assuming this does not fail
sgs_Call( C, SGS_FSTKTOP, 6, 1 ); // calls function from global 'main' with 6 arguments and expects 1 value in return
// again, it's assumed that sgs_Call does not fail
// ...but it may, so checking return value is a very good idea

• Function arguments can be passed by pushing data on the stack.
• There are many kinds of pushing functions, some of these push exact data.
  • Others push data from internal sources - therefore they can fail..
  • ..for example, PushGlobal may not find a variable with that name - in that case, nothing is pushed and SGS_ENOTFND is returned.
• There are also function-calling functions. They have certain expectations:
  • 1. Function must be the last (topmost) item on stack.
  • 2. There must be at least N more items on stack - where N is total argument count.
  • 3. Function argument must be callable (function type / object with 'call' interface function)
• If a call fails...
  • stack size issues - stack is left unchanged
  • execution errors - stack has the expected number of return values, all set to null

if( SGS_CALL_FAILED( sgs_GlobalCall( C, "func", 0, 3 ) ) )
    /* handle the error */; // it is important this time since stack state matters
sgs_Int i = sgs_GetInt( C, -3 ); // first return value
const char* string_ptr = NULL;
sgs_SizeVal string_size = 0;
if( sgs_ParseString( C, -2, &string_ptr, &string_length ) )
    /* successfully parsed a string, deal with it */;
sgs_Bool b = sgs_GetBool( C, -1 );
sgs_Pop( C, 3 ); // remove all 3 returned values from top of the stack

• There are various ways to validate and read back data from the engine:
  • Get*** functions: return converted data without doing in-place conversions
  • To*** functions: convert data in-place, then return it
  • Parse*** functions: check if it's possible to convert, then return converted data
• Items are removed from top of the stack with sgs_Pop.

sgs_PushBool( C, 1 );
sgs_PushInt( C, 42 );
sgs_PushReal( C, 3.14159 );
sgs_PushArray( C, 3 ); // pushes an array with 3 items, made from 3 topmost stack items

sgs_PushString( C, "some C string" );
sgs_PushStringBuf( C, "not\0really\0C\0string", 19 );
sgs_CreateDict( C, NULL, 2 ); // pushes a dictionary with one entry, made from 2 topmost stack items

• Basic objects (array, dict, map) can be easily pushed on the stack too.
• sgs_CreateArray takes the specified number of topmost stack items, puts them into the array and removes them from the stack
• sgs_CreateDict and sgs_CreateMap take the specified number of topmost stack items, map values to keys and remove them from the stack
  • The number of items must be a multiple of 2. First item of each pair is a key, second - value for that key.
  • Keys can be repeated, only the last value is used.