1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
.. _stdlib_stdiolib:
========================
The Input/Output library
========================
the i/o library implements basic input/output routines.
--------------
Squirrel API
--------------
++++++++++++++
Global Symbols
++++++++++++++
.. js:function:: 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 ivoked.
When squirrel is compiled in unicode mode the function can handle different character ecodings,
UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian).
If the source stream is not prefixed UTF8 ecoding is used as default.
.. js:function:: 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 ivoked.
When squirrel is compiled in unicode mode the function can handle different character ecodings,
UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian).
If the source stream is not prefixed UTF8 ecoding is used as default.
.. js:function:: writeclosuretofile(destpath, closure)
serializes a closure to a bytecode file (destpath). The serialized file can be loaded
using loadfile() and dofile().
.. js:data:: stderr
File object bound on the os *standard error* stream
.. js:data:: stdin
File object bound on the os *standard input* stream
.. js:data:: stdout
File object bound on the os *standard output* stream
++++++++++++++
The file class
++++++++++++++
The file object implements a stream on a operating system file.
.. js:class:: file(path, patten)
It's contructor 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.
.. js:function:: file.close()
closes the file.
.. js:function:: file.eos()
returns a non null value if the read/write pointer is at the end of the stream.
.. js:function:: file.flush()
flushes the stream.return a value != null if succeded, otherwise returns null
.. js:function:: file.len()
returns the lenght of the stream
.. js:function:: file.readblob(size)
:param int size: number of bytes to read
read n bytes from the stream and retuns them as blob
.. js:function:: file.readn(type)
:param int type: type of the number to read
reads a number from the stream according to the type pameter.
`type` can have the following values:
+--------------+--------------------------------------------------------------------------------+----------------------+
| parameter | return description | return type |
+==============+================================================================================+======================+
| 'l' | processor dependent, 32bits on 32bits processors, 64bits on 64bits prcessors | 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 |
+--------------+--------------------------------------------------------------------------------+----------------------+
.. js:function:: file.resize(size)
:param int size: the new size of the blobl in bytes
resizes the blob to the specified `size`
.. js:function:: file.seek(offset [,origin])
:param int offset: indicates the number of bytes from `origin`.
:param int origin: 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).
.. js:function:: file.tell()
returns the read/write pointer absolute position
.. js:function:: file.writeblob(src)
:param blob src: the source blob containing the data to be written
writes a blob in the stream
.. js:function:: file.writen(n, type)
:param number n: the value to be written
:param int type: type of the number to write
writes a number in the stream formatted according to the `type` pameter
`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 |
+--------------+--------------------------------------------------------------------------------+
--------------
C API
--------------
.. _sqstd_register_iolib:
.. c:function:: SQRESULT sqstd_register_iolib(HSQUIRRELVM v)
:param HSQUIRRELVM v: 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.
++++++++++++++
File Object
++++++++++++++
.. c:function:: SQRESULT sqstd_createfile(HSQUIRRELVM v, SQFILE file, SQBool owns)
:param HSQUIRRELVM v: the target VM
:param SQFILE file: the stream that will be rapresented by the file object
:param SQBool owns: 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
.. c:function:: SQRESULT sqstd_getfile(HSQUIRRELVM v, SQInteger idx, SQFILE* file)
:param HSQUIRRELVM v: the target VM
:param SQInteger idx: and index in the stack
:param SQFILE* file: 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.
++++++++++++++++++++++++++++++++
Script loading and serialization
++++++++++++++++++++++++++++++++
.. c:function:: SQRESULT sqstd_loadfile(HSQUIRRELVM v, const SQChar* filename, SQBool printerror)
:param HSQUIRRELVM v: the target VM
:param SQChar* filename: path of the script that has to be loaded
:param SQBool printerror: 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 ecodings,
UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian).
If the source stream is not prefixed UTF8 ecoding is used as default.
.. c:function:: SQRESULT sqstd_dofile(HSQUIRRELVM v, const SQChar* filename, SQBool retval, SQBool printerror)
:param HSQUIRRELVM v: the target VM
:param SQChar* filename: path of the script that has to be loaded
:param SQBool retval: if true the function will push the return value of the executed script in the stack.
:param SQBool printerror: if true the compiler error handler will be called if a error occurs
:returns: an SQRESULT
:remarks: the function aspects 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 ecodings,
UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian).
If the source stream is not prefixed UTF8 ecoding 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
.. c:function:: SQRESULT sqstd_writeclosuretofile(HSQUIRRELVM v, const SQChar* filename)
:param HSQUIRRELVM v: the target VM
:param SQChar* filename: 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 paremeter filename. If a file with the
same name already exists, it will be overwritten.
|
