Browse Source

Sol Part 44.1: MOM GET THE THESAURUS!

Graham Northup 5 years ago
parent
commit
9ba71b5a41
2 changed files with 187 additions and 6 deletions
  1. 6
    4
      Doxyfile
  2. 181
    2
      sol.h

+ 6
- 4
Doxyfile View File

@@ -38,7 +38,7 @@ PROJECT_NAME           = Sol
38 38
 # could be handy for archiving the generated documentation or if some version
39 39
 # control system is used.
40 40
 
41
-PROJECT_NUMBER         = 0.1a4
41
+PROJECT_NUMBER         = 0.2a0
42 42
 
43 43
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
44 44
 # for a project that appears at the top of each page and should give viewer a
@@ -238,7 +238,8 @@ TAB_SIZE               = 4
238 238
 # "Side Effects:". You can put \n's in the value part of an alias to insert
239 239
 # newlines.
240 240
 
241
-ALIASES                = 
241
+ALIASES                = "rst=\verbatim embed:rst:leading-asterisk" \
242
+                         endrst=\endverbatim
242 243
 
243 244
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
244 245
 # A mapping has the form "name=value". For example adding "class=itcl::class"
@@ -1199,8 +1200,9 @@ HTML_COLORSTYLE_GAMMA  = 80
1199 1200
 
1200 1201
 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
1201 1202
 # page will contain the date and time when the page was generated. Setting this
1202
-# to NO can help when comparing the output of multiple runs.
1203
-# The default value is: YES.
1203
+# to YES can help to show when doxygen was last run and thus if the
1204
+# documentation is up to date.
1205
+# The default value is: NO.
1204 1206
 # This tag requires that the tag GENERATE_HTML is set to YES.
1205 1207
 
1206 1208
 HTML_TIMESTAMP         = YES

+ 181
- 2
sol.h View File

@@ -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 {

Loading…
Cancel
Save