|
@@ -61,141 +61,320 @@ typedef sol_object_t *(*sol_cfunc_t)(sol_state_t *, sol_object_t *);
|
61
|
61
|
|
62
|
62
|
/** Print function type.
|
63
|
63
|
*
|
64
|
|
- * \deprecated This is not used anywhere and is likely to be removed in the
|
65
|
|
- * near future.
|
|
64
|
+ * \rst
|
|
65
|
+ * .. admonition:: Deprecated
|
|
66
|
+ *
|
|
67
|
+ * This is not used anywhere and is likely to be removed in the
|
|
68
|
+ * near future.
|
|
69
|
+ * \endrst
|
66
|
70
|
*/
|
67
|
71
|
|
68
|
72
|
typedef void (*sol_printfunc_t)(sol_object_t *);
|
69
|
73
|
|
|
74
|
+/** Type methods structure.
|
|
75
|
+ *
|
|
76
|
+ * Sol bases most of its object behavior on methods defined on so-called "ops
|
|
77
|
+ * structures" of this type pointed to by the objects themselves. In general,
|
|
78
|
+ * these contain the address of one such structure stored directly in the state
|
|
79
|
+ * (each state has its own set of these structures for all the builtin types,
|
|
80
|
+ * initialized in `sol_state_init`), but they can conceivably be allocated and
|
|
81
|
+ * initialized elsewhere, e.g., in extension modules.
|
|
82
|
+ *
|
|
83
|
+ * Nearly all of the fields in this structure are function pointers to
|
|
84
|
+ * `sol_cfunc_t` that are called when an operator is invoked on an object. In
|
|
85
|
+ * the case of binary operators, only the left operand is considered.
|
|
86
|
+ *
|
|
87
|
+ * In member documentation of these functions, the list [in brackets]
|
|
88
|
+ * represents, visually, the list that the function can expect to receive as
|
|
89
|
+ * the second argument (where "rhs" is right-hand-side of a binary operator,
|
|
90
|
+ * and "this" is the object whose ops structure was indexed). Note that the
|
|
91
|
+ * runtime does not use nor take advantage of the returns of all of these
|
|
92
|
+ * methods.
|
|
93
|
+ */
|
|
94
|
+
|
70
|
95
|
typedef struct {
|
|
96
|
+ /** A C-string naming the type, for use by the built-in `type` function. */
|
71
|
97
|
char *tname;
|
|
98
|
+ /** Called with [this, rhs] to perform binary addition ("+"). */
|
72
|
99
|
sol_cfunc_t add;
|
|
100
|
+ /** Called with [this, rhs] to perform binary subtraction ("-"). */
|
73
|
101
|
sol_cfunc_t sub;
|
|
102
|
+ /** Called with [this, rhs] to perform binary multiplication ("*"). */
|
74
|
103
|
sol_cfunc_t mul;
|
|
104
|
+ /** Called with [this, rhs] to perform binary division ("/"). */
|
75
|
105
|
sol_cfunc_t div;
|
|
106
|
+ /** Called with [this, rhs] to perform binary modulus ("%"). */
|
76
|
107
|
sol_cfunc_t mod;
|
|
108
|
+ /** Called with [this, rhs] to perform binary exponentiation ("**"). */
|
77
|
109
|
sol_cfunc_t pow;
|
|
110
|
+ /** Called with [this, rhs] to perform binary bitwise AND ("&") */
|
78
|
111
|
sol_cfunc_t band;
|
|
112
|
+ /** Called with [this, rhs] to perform binary bitwise OR ("|") */
|
79
|
113
|
sol_cfunc_t bor;
|
|
114
|
+ /** Called with [this, rhs] to perform binary bitwise XOR ("^") */
|
80
|
115
|
sol_cfunc_t bxor;
|
|
116
|
+ /** Called with [this, rhs] to perform binary bitwise left shift ("<<") */
|
81
|
117
|
sol_cfunc_t blsh;
|
|
118
|
+ /** Called with [this, rhs] to perform binary bitwise right shift (">>") */
|
82
|
119
|
sol_cfunc_t brsh;
|
|
120
|
+ /** Called with [this] to perform bitwise not ("~") */
|
83
|
121
|
sol_cfunc_t bnot;
|
|
122
|
+ /** Called with [this, rhs] to perform comparison; the result should be an integer object of value -1 (this < rhs), 0 (this == rhs), or 1 (this > rhs) */
|
84
|
123
|
sol_cfunc_t cmp;
|
|
124
|
+ /** Called with [this, arg1, arg2, ...] to perform a call (as "this(arg1, arg2, ...)") */
|
85
|
125
|
sol_cfunc_t call;
|
|
126
|
+ /** Called with [this, index] to perform an index like "this[index]" or "this.index" (in the latter, index will be a string object) */
|
86
|
127
|
sol_cfunc_t index;
|
|
128
|
+ /** Called with [this, index, value] to perform a setindex (like "this[index] = value" or "this.index = value" for index being a string object) */
|
87
|
129
|
sol_cfunc_t setindex;
|
|
130
|
+ /** Called with [this] to perform a length predicate (like "#this") */
|
88
|
131
|
sol_cfunc_t len;
|
|
132
|
+ /** Called with [this] to return a function object (or cfunction object) that will iterate over "this" (see the iterator protocol for more details) */
|
89
|
133
|
sol_cfunc_t iter;
|
|
134
|
+ /** Called with [this] to cast "this" to an integer object. This may raise an error, which should be checked. */
|
90
|
135
|
sol_cfunc_t toint;
|
|
136
|
+ /** Called with [this] to cast "this" to a float object. This may raise an error, which should be checked. */
|
91
|
137
|
sol_cfunc_t tofloat;
|
|
138
|
+ /** Called with [this] to cast "this" to a string object. This generally shouldn't raise an error, and usually falls back to a simple representation. */
|
92
|
139
|
sol_cfunc_t tostring;
|
|
140
|
+ /** Called with [this] to provide a representation of "this", in the sense that it is human-readable and informative. This usually falls back to tostring. */
|
93
|
141
|
sol_cfunc_t repr;
|
|
142
|
+ /** Called with this (*not a list*) as a result of calling `sol_init_object`. Since this is usually called from a constructor anyway, it's usually fairly useless. It should return this. */
|
94
|
143
|
sol_cfunc_t init;
|
|
144
|
+ /** Called with this (*not a list*) and *with a NULL state* before an object is freed; it should free any resources this object exclusively holds, and return this. */
|
95
|
145
|
sol_cfunc_t free;
|
96
|
146
|
} sol_ops_t;
|
97
|
147
|
|
|
148
|
+/** Object types known to Sol.
|
|
149
|
+ *
|
|
150
|
+ * This is rarely checked and generally only used where necessary, as there is
|
|
151
|
+ * no way to extend this list naturally for an extension developer.
|
|
152
|
+ *
|
|
153
|
+ * For each of these types, there is almost certainly a test macro for it.
|
|
154
|
+ */
|
|
155
|
+
|
98
|
156
|
typedef enum {
|
|
157
|
+ /** The singlet type--the type of None, as well as StopIteration and OutOfMemory. It is also the "default" type. */
|
99
|
158
|
SOL_SINGLET,
|
|
159
|
+ /** The integer type, implemented as a long. */
|
100
|
160
|
SOL_INTEGER,
|
|
161
|
+ /** The floating point type, implemented as a double. */
|
101
|
162
|
SOL_FLOAT,
|
|
163
|
+ /** The string type, implemented as a C string. */
|
102
|
164
|
SOL_STRING,
|
|
165
|
+ /** The list type, implemented as a DSL sequence of object pointers. */
|
103
|
166
|
SOL_LIST,
|
|
167
|
+ /** The map type, implemented as a DSL sequence of MCELL object pointers arranged as an associative array.. */
|
104
|
168
|
SOL_MAP,
|
|
169
|
+ /** The mcell type, a simple key-value pair only to be found in a map. */
|
105
|
170
|
SOL_MCELL,
|
|
171
|
+ /** The function type, the type of all user-defined functions in Sol. */
|
106
|
172
|
SOL_FUNCTION,
|
|
173
|
+ /** The cfunction type, the type of objects wrapping a `sol_cfunc_t`. */
|
107
|
174
|
SOL_CFUNCTION,
|
|
175
|
+ /** The statement type, the type of objects wrapping a `stmt_node`. */
|
108
|
176
|
SOL_STMT,
|
|
177
|
+ /** The expression type, the type of objects wrapping an `expr_node`. */
|
109
|
178
|
SOL_EXPR,
|
|
179
|
+ /** The buffer type, a type designed to access arbitrary memory. */
|
110
|
180
|
SOL_BUFFER,
|
|
181
|
+ /** The dylib type, the type of dynamically-loaded shared libraries. */
|
111
|
182
|
SOL_DYLIB,
|
|
183
|
+ /** The dysym type, the type of symbols resolved in dylib objects. */
|
112
|
184
|
SOL_DYSYM,
|
|
185
|
+ /** The stream type, the type wrapping FILE *. */
|
113
|
186
|
SOL_STREAM,
|
|
187
|
+ /** The cdata type, the type used for extension by various modules. */
|
114
|
188
|
SOL_CDATA
|
115
|
189
|
} sol_objtype_t;
|
116
|
190
|
|
|
191
|
+
|
|
192
|
+/** Buffer types.
|
|
193
|
+ *
|
|
194
|
+ * These types indicate what a buffer or subsection of a buffer may refer to.
|
|
195
|
+ */
|
|
196
|
+
|
117
|
197
|
typedef enum {
|
|
198
|
+ /** The region is typeless. This is the default, and prohibits access unless it is retyped. */
|
118
|
199
|
BUF_NONE,
|
|
200
|
+ /** The region contains an 8-bit signed integer. */
|
119
|
201
|
BUF_INT8,
|
|
202
|
+ /** The region contains a 16-bit signed integer. */
|
120
|
203
|
BUF_INT16,
|
|
204
|
+ /** The region contains a 32-bit signed integer. */
|
121
|
205
|
BUF_INT32,
|
|
206
|
+ /** The region contains a 64-bit signed integer. */
|
122
|
207
|
BUF_INT64,
|
|
208
|
+ /** The region contains an 8-bit unsigned integer. */
|
123
|
209
|
BUF_UINT8,
|
|
210
|
+ /** The region contains a 16-bit unsigned integer. */
|
124
|
211
|
BUF_UINT16,
|
|
212
|
+ /** The region contains a 32-bit unsigned integer. */
|
125
|
213
|
BUF_UINT32,
|
|
214
|
+ /** The region contains a 64-bit unsigned integer. */
|
126
|
215
|
BUF_UINT64,
|
|
216
|
+ /** The region contains an ASCII character. */
|
127
|
217
|
BUF_CHAR,
|
|
218
|
+ /** The region contains exactly one addressable unit. */
|
128
|
219
|
BUF_BYTE,
|
|
220
|
+ /** The region contains a platform-sized signed integer. */
|
129
|
221
|
BUF_INT,
|
|
222
|
+ /** The region contains a platform-sized unsigned integer. */
|
130
|
223
|
BUF_UINT,
|
|
224
|
+ /** The region contains a platform-sized signed long integer. */
|
131
|
225
|
BUF_LONG,
|
|
226
|
+ /** The region contains a platform-sized unsigned long integer. */
|
132
|
227
|
BUF_ULONG,
|
|
228
|
+ /** The region contains a platform single-precision floating point. */
|
133
|
229
|
BUF_FLOAT,
|
|
230
|
+ /** The region contains a platform double-precision floating point. */
|
134
|
231
|
BUF_DOUBLE,
|
|
232
|
+ /** The region contains a pointer to a NUL-terminated C string. */
|
135
|
233
|
BUF_CSTR,
|
|
234
|
+ /** The region contains a generic pointer (which will instantiate another buffer). */
|
136
|
235
|
BUF_PTR
|
137
|
236
|
} sol_buftype_t;
|
138
|
237
|
|
|
238
|
+/** Ownership types.
|
|
239
|
+ *
|
|
240
|
+ * These functions determine what happens to the memory region aliased by a
|
|
241
|
+ * buffer when that object is freed or copied.
|
|
242
|
+ */
|
|
243
|
+
|
139
|
244
|
typedef enum {
|
|
245
|
+ /** Nothing happens; the object is freed or copied normally. */
|
140
|
246
|
OWN_NONE,
|
|
247
|
+ /** The libc `free` function is called on the buffer. Nothing happens when a new buffer is made to alias it. */
|
141
|
248
|
OWN_FREE,
|
|
249
|
+ /** The movefunc and freefunc are respectively consulted. */
|
142
|
250
|
OWN_CALLF
|
143
|
251
|
} sol_owntype_t;
|
144
|
252
|
|
|
253
|
+/**
|
|
254
|
+ * Transput modes.
|
|
255
|
+ *
|
|
256
|
+ * These constants are defined (by the same name) on the `io` module as valid bits for the second argument to `io.open`.
|
|
257
|
+ */
|
|
258
|
+
|
145
|
259
|
typedef enum {
|
|
260
|
+ /** Permit reading. If this is not set, any attempt to read will raise an error. */
|
146
|
261
|
MODE_READ = 1,
|
|
262
|
+ /** Permit writing. If this is not set, any attempt to write will raise an error. */
|
147
|
263
|
MODE_WRITE = 2,
|
|
264
|
+ /** When opening for writing, direct all writes to the end of the file. This has no effect on read positions, when opened in both modes. */
|
148
|
265
|
MODE_APPEND = 4,
|
|
266
|
+ /** When opened for writing, truncate the file to zero size. Previous contents are lost. */
|
149
|
267
|
MODE_TRUNCATE = 8,
|
|
268
|
+ /** Prepare the file for reading or writing binary data as opposed to text. */
|
150
|
269
|
MODE_BINARY = 16
|
151
|
270
|
} sol_modes_t;
|
152
|
271
|
|
|
272
|
+/** Buffer freeing function.
|
|
273
|
+ *
|
|
274
|
+ * This is called with the buffer region and given size when a buffer object is
|
|
275
|
+ * freed (from state.BufferOps.free) when the `sol_owntype_t` is set to
|
|
276
|
+ * `OWN_CALLF`. It should do whatever is needed to release this one alias of
|
|
277
|
+ * memory. Note that care should be taken if multiple buffer objects alias the
|
|
278
|
+ * same region.
|
|
279
|
+ */
|
|
280
|
+
|
153
|
281
|
typedef void (*sol_freefunc_t)(void *, size_t);
|
|
282
|
+
|
|
283
|
+/** Buffer moving function.
|
|
284
|
+ *
|
|
285
|
+ * This is called with the buffer region and given size when a buffer object is
|
|
286
|
+ * somehow copied (usually by dereferencing a `BUF_PTR`). It should return the
|
|
287
|
+ * region that the new buffer object should refer to. The size is assumed to
|
|
288
|
+ * not change.
|
|
289
|
+ */
|
|
290
|
+
|
154
|
291
|
typedef void *(*sol_movefunc_t)(void *, size_t);
|
155
|
292
|
|
|
293
|
+/** Object structure.
|
|
294
|
+ *
|
|
295
|
+ * This structure defines the interface of every Sol object. Just as well (and
|
|
296
|
+ * as an implementation detail), it contains the operative members of every
|
|
297
|
+ * built-in type.
|
|
298
|
+ */
|
|
299
|
+
|
156
|
300
|
typedef struct sol_tag_object_t {
|
|
301
|
+ /** The type of this object. */
|
157
|
302
|
sol_objtype_t type;
|
|
303
|
+ /** The number of living references to this object, increased by `sol_incref` and decreased by `sol_obj_free`. */
|
158
|
304
|
int refcnt;
|
|
305
|
+ /** The ops structure defining the behavior of this object under certain operations (more or less, its behavioral "type"). */
|
159
|
306
|
sol_ops_t *ops;
|
160
|
307
|
union {
|
|
308
|
+ /** For `SOL_INTEGER`, the value of the integer. */
|
161
|
309
|
long ival;
|
|
310
|
+ /** For `SOL_FLOAT`, the value of the floating point number. */
|
162
|
311
|
double fval;
|
|
312
|
+ /** For `SOL_STRING`, the C string pointer. For `SOL_SINGLET`, the name of this singlet. */
|
163
|
313
|
char *str;
|
|
314
|
+ /** For `SOL_LIST` and `SOL_MAP`, the DSL sequence that contains the items or pairs. */
|
164
|
315
|
dsl_seq *seq;
|
165
|
316
|
struct {
|
|
317
|
+ /** For `SOL_MCELL`, the key of the pair. */
|
166
|
318
|
struct sol_tag_object_t *key;
|
|
319
|
+ /** For `SOL_MCELL`, the value of the pair. */
|
167
|
320
|
struct sol_tag_object_t *val;
|
168
|
321
|
};
|
169
|
322
|
struct {
|
|
323
|
+ /** For `SOL_FUNCTION`, the `stmt_node` pointer representing the function's body. */
|
170
|
324
|
void *func; // Actually a stmt_node *
|
|
325
|
+ /** For `SOL_FUNCTION`, the `identlist_node` pointer representing the list of the functions argument names. */
|
171
|
326
|
void *args; // Actually an identlist_node *
|
|
327
|
+ /** For `SOL_FUNCTION`, a map representing the closure (initial scope, updated on exit) of the function. */
|
172
|
328
|
struct sol_tag_object_t *closure;
|
|
329
|
+ /** For `SOL_FUNCTION`, a map of data defined by the user on this function object. */
|
173
|
330
|
struct sol_tag_object_t *udata;
|
|
331
|
+ /** For `SOL_FUNCTION`, the name of the function if it was not declared anonymously (otherwise NULL). */
|
174
|
332
|
char *fname;
|
175
|
333
|
};
|
|
334
|
+ /** For `SOL_CFUNCTION`, the C function pointer. */
|
176
|
335
|
sol_cfunc_t cfunc;
|
|
336
|
+ /** For `SOL_STMT` and `SOL_EXPR`, the `stmt_node` or `expr_node` pointer, respectively. */
|
177
|
337
|
void *node;
|
178
|
338
|
struct {
|
|
339
|
+ /** For `SOL_BUFFER`, the memory region referred to by this buffer. */
|
179
|
340
|
void *buffer;
|
|
341
|
+ /** For `SOL_BUFFER`, the size of this memory region. Negative values indicate no or unknown size. */
|
180
|
342
|
ssize_t sz;
|
|
343
|
+ /** For `SOL_BUFFER`, the ownership type of this buffer's region. */
|
181
|
344
|
sol_owntype_t own;
|
|
345
|
+ /** For `SOL_BUFFER`, the freeing function if own == `OWN_CALLF` */
|
182
|
346
|
sol_freefunc_t freef;
|
|
347
|
+ /** For `SOL_BUFFER`, the moving function if own == `OWN_CALLF` */
|
183
|
348
|
sol_movefunc_t movef;
|
184
|
349
|
};
|
|
350
|
+ /** For `SOL_DYLIB`, the handle as returned by `dlopen`. */
|
185
|
351
|
void *dlhandle;
|
186
|
352
|
struct {
|
|
353
|
+ /** For `SOL_DYSYM`, the symbol as resolved by `dlsym`. */
|
187
|
354
|
void *dlsym;
|
|
355
|
+ /** For `SOL_DYSYM`, a sequence of the types of the arguments (a set of `sol_buftype_t` cast to void *, the native type of DSL), if the symbol is a function. */
|
188
|
356
|
dsl_seq *argtp;
|
|
357
|
+ /** For `SOL_DYSYM`, the return type of the symbol if it is a function; otherwise, the type of the symbol if it is a variable. */
|
189
|
358
|
sol_buftype_t rettp;
|
190
|
359
|
};
|
191
|
360
|
struct {
|
|
361
|
+ /** For `SOL_STREAM`, the actual file object. */
|
192
|
362
|
FILE *stream;
|
|
363
|
+ /** For `SOL_STREAM`, the modes for which this stream is open. */
|
193
|
364
|
sol_modes_t modes;
|
194
|
365
|
};
|
|
366
|
+ /** For `SOL_CDATA`, an arbitrary, user-defined pointer. */
|
195
|
367
|
void *cdata;
|
196
|
368
|
};
|
197
|
369
|
} sol_object_t;
|
198
|
370
|
|
|
371
|
+/** State flags.
|
|
372
|
+ *
|
|
373
|
+ * These flags get set during execution and indicate an altered state of
|
|
374
|
+ * interpretation (other than the altered state of interpretation that comes
|
|
375
|
+ * about due to an error propagation).
|
|
376
|
+ */
|
|
377
|
+
|
199
|
378
|
typedef enum {SF_NORMAL, SF_BREAKING, SF_CONTINUING} sol_state_flag_t;
|
200
|
379
|
|
201
|
380
|
typedef struct sol_tag_state_t {
|