2. The Input/Output library

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

2.1. Quirrel API

2.1.1. Global Symbols

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.