2. The Input/Output library

the i/o library implements basic input/output routines.

2.1. Squirrel API

2.1.1. Global Symbols

dofile(path[, raiseerror])

compiles a squirrel script or loads a precompiled one and executes it. returns the value returned by the script or null if no value is returned. if the optional parameter ‘raiseerror’ is true, the compiler error handler is invoked in case of a syntax error. If raiseerror is omitted or set to false, the compiler error handler is not invoked. When squirrel is compiled in Unicode mode the function can handle different character encodings, UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian). If the source stream is not prefixed UTF8 encoding is used as default.

loadfile(path[, raiseerror])

compiles a squirrel script or loads a precompiled one an returns it as as function. if the optional parameter ‘raiseerror’ is true, the compiler error handler is invoked in case of a syntax error. If raiseerror is omitted or set to false, the compiler error handler is not invoked. When squirrel is compiled in Unicode mode the function can handle different character encodings, UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian). If the source stream is not prefixed UTF8 encoding is used as default.

writeclosuretofile(destpath, closure)

serializes a closure to a bytecode file (destpath). The serialized file can be loaded using loadfile() and dofile().

stderr

File object bound on the os standard error stream

stdin

File object bound on the os standard input stream

stdout

File object bound on the os standard output stream

2.1.2. The file class

The file object implements a stream on a operating system file.

class file(path, patten)

It’s constructor imitates the behaviour of the C runtime function fopen for eg.

local myfile = file("test.xxx","wb+");

creates a file with read/write access in the current directory.

file.close()

closes the file.

file.eos()

returns a non null value if the read/write pointer is at the end of the stream.

file.flush()

flushes the stream.return a value != null if succeeded, otherwise returns null

file.len()

returns the length of the stream

file.readblob(size)
Arguments

  • size (int()) – number of bytes to read

read n bytes from the stream and returns them as blob

file.readn(type)
Arguments

  • type (int()) – type of the number to read

reads a number from the stream according to the type parameter.

type can have the following values:

parameter

return description

return type

‘l’

processor dependent, 32bits on 32bits processors, 64bits on 64bits processors

integer

‘i’

32bits number

integer

‘s’

16bits signed integer

integer

‘w’

16bits unsigned integer

integer

‘c’

8bits signed integer

integer

‘b’

8bits unsigned integer

integer

‘f’

32bits float

float

‘d’

64bits float

float
file.resize(size)
Arguments

  • size (int()) – the new size of the blob in bytes

resizes the blob to the specified size

file.seek(offset[, origin])
Arguments

  • offset (int()) – indicates the number of bytes from origin.

  • origin (int()) –

    origin of the seek

    ’b’

    beginning of the stream

    ’c’

    current location

    ’e’

    end of the stream

Moves the read/write pointer to a specified location.

Note

If origin is omitted the parameter is defaulted as ‘b’(beginning of the stream).

file.tell()

returns the read/write pointer absolute position

file.writeblob(src)
Arguments

  • src (blob()) – the source blob containing the data to be written

writes a blob in the stream

file.writen(n, type)
Arguments

  • n (number()) – the value to be written

  • type (int()) – type of the number to write

writes a number in the stream formatted according to the type pamraeter

type can have the following values:

parameter

return description

‘i’

32bits number

‘s’

16bits signed integer

‘w’

16bits unsigned integer

‘c’

8bits signed integer

‘b’

8bits unsigned integer

‘f’

32bits float

‘d’

64bits float

2.2. C API

SQRESULT sqstd_register_iolib(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

Returns

an SQRESULT

Remarks

The function aspects a table on top of the stack where to register the global library functions.

initialize and register the io library in the given VM.

2.2.1. File Object

SQRESULT sqstd_createfile(HSQUIRRELVM v, SQFILE file, SQBool owns)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • file (SQFILE) – the stream that will be rapresented by the file object

  • owns (SQBool) – if different true the stream will be automatically closed when the newly create file object is destroyed.

Returns

an SQRESULT

creates a file object bound to the SQFILE passed as parameter and pushes it in the stack

SQRESULT sqstd_getfile(HSQUIRRELVM v, SQInteger idx, SQFILE *file)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • idx (SQInteger) – and index in the stack

  • file (SQFILE*) – A pointer to a SQFILE handle that will store the result

Returns

an SQRESULT

retrieve the pointer of a stream handle from an arbitrary position in the stack.

2.2.2. Script loading and serialization

SQRESULT sqstd_loadfile(HSQUIRRELVM v, const SQChar *filename, SQBool printerror)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • filename (SQChar*) – path of the script that has to be loaded

  • printerror (SQBool) – if true the compiler error handler will be called if a error occurs

Returns

an SQRESULT

Compiles a squirrel script or loads a precompiled one an pushes it as closure in the stack. When squirrel is compiled in Unicode mode the function can handle different character encodings, UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian). If the source stream is not prefixed UTF8 encoding is used as default.

SQRESULT sqstd_dofile(HSQUIRRELVM v, const SQChar *filename, SQBool retval, SQBool printerror)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • filename (SQChar*) – path of the script that has to be loaded

  • retval (SQBool) – if true the function will push the return value of the executed script in the stack.

  • printerror (SQBool) – if true the compiler error handler will be called if a error occurs

Returns

an SQRESULT

Remarks

the function expects a table on top of the stack that will be used as ‘this’ for the execution of the script. The ‘this’ parameter is left untouched in the stack.

Compiles a squirrel script or loads a precompiled one and executes it. Optionally pushes the return value of the executed script in the stack. When squirrel is compiled in unicode mode the function can handle different character encodings, UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian). If the source stream is not prefixed, UTF8 encoding is used as default.

sq_pushroottable(v); //push the root table(were the globals of the script will are stored)
sqstd_dofile(v, _SC("test.nut"), SQFalse, SQTrue);// also prints syntax errors if any
SQRESULT sqstd_writeclosuretofile(HSQUIRRELVM v, const SQChar *filename)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • filename (SQChar*) – destination path of serialized closure

Returns

an SQRESULT

serializes the closure at the top position in the stack as bytecode in the file specified by the parameter filename. If a file with the same name already exists, it will be overwritten.