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.