The Sol Programming Language!
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

sol.h 52KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206
  1. #ifndef SOL_H
  2. #define SOL_H
  3. #ifndef NULL
  4. #define NULL ((void *) 0)
  5. #endif
  6. #include <stdio.h>
  7. #include <stdarg.h>
  8. #include "dsl/dsl.h"
  9. /** The version of the project, as made available through `debug.version`. */
  10. #define SOL_VERSION "0.5a0"
  11. /** The hexadecimal version of the project, formatted 0xAAIIRPP where:
  12. *
  13. * - AA is the two-digit major version
  14. * - II is the two-digit minor version
  15. * - R is 'A' for alpha, 'B' for beta, 'C' for candidate, and 'F' for final
  16. * - PP is the two-digit patch
  17. *
  18. * This value is guaranteed to only monotonically increase by revision, within
  19. * the same line of development. In particular, features introduced in some
  20. * version shall be available in all versions numerically greater than it
  21. * (unless they are later deprecated or removed).
  22. */
  23. #define SOL_HEXVER 0x0004A00
  24. #ifndef SOL_BUILD_HOST
  25. #define SOL_BUILD_HOST "(unknown host)"
  26. #endif
  27. #ifndef SOL_BUILD_KERNEL
  28. #define SOL_BUILD_KERNEL "(unknown kernel)"
  29. #endif
  30. #ifndef SOL_BUILD_ARCH
  31. #define SOL_BUILD_ARCH "(unknown arch)"
  32. #endif
  33. #ifndef SOL_BUILD_REV
  34. #define SOL_BUILD_REV "(unknown rev)"
  35. #endif
  36. #define SOL_BUILD_ID "sol-" SOL_BUILD_REV " " __DATE__ " " __TIME__ " on " SOL_BUILD_HOST " " SOL_BUILD_KERNEL " " SOL_BUILD_ARCH
  37. #ifndef SOL_ICACHE_MIN
  38. /** The smallest integer to cache. */
  39. #define SOL_ICACHE_MIN -128
  40. #endif
  41. #ifndef SOL_ICACHE_MAX
  42. /** The largest integer to cache. */
  43. #define SOL_ICACHE_MAX 256
  44. #endif
  45. #if !defined(SOL_ICACHE) && (SOL_ICACHE_MIN < SOL_ICACHE_MAX)
  46. #define SOL_ICACHE
  47. #endif
  48. // Forward declarations:
  49. struct sol_tag_object_t;
  50. typedef struct sol_tag_object_t sol_object_t;
  51. struct sol_tag_state_t;
  52. typedef struct sol_tag_state_t sol_state_t;
  53. /** CFunction type.
  54. *
  55. * This is the essential type for most C interface routines. It receives two
  56. * parameters:
  57. *
  58. * - The state under which the function is invoked, and
  59. * - A list object containing a set of parameters, which are generally
  60. * well-defined per location or operation.
  61. *
  62. * The function should return a new reference to an object. If the value is
  63. * unimportant or otherwise ignored, the canonical return value is
  64. * `sol_incref`(state->None).
  65. */
  66. typedef sol_object_t *(*sol_cfunc_t)(sol_state_t *, sol_object_t *);
  67. /** Print function type.
  68. *
  69. * \rst
  70. * .. admonition:: Deprecated
  71. *
  72. * This is not used anywhere and is likely to be removed in the
  73. * near future.
  74. * \endrst
  75. */
  76. typedef void (*sol_printfunc_t)(sol_object_t *);
  77. /** Type methods structure.
  78. *
  79. * Sol bases most of its object behavior on methods defined on so-called "ops
  80. * structures" of this type pointed to by the objects themselves. In general,
  81. * these contain the address of one such structure stored directly in the state
  82. * (each state has its own set of these structures for all the builtin types,
  83. * initialized in `sol_state_init`), but they can conceivably be allocated and
  84. * initialized elsewhere, e.g., in extension modules.
  85. *
  86. * Nearly all of the fields in this structure are function pointers to
  87. * `sol_cfunc_t` that are called when an operator is invoked on an object. In
  88. * the case of binary operators, only the left operand is considered.
  89. *
  90. * In member documentation of these functions, the list [in brackets]
  91. * represents, visually, the list that the function can expect to receive as
  92. * the second argument (where "rhs" is right-hand-side of a binary operator,
  93. * and "this" is the object whose ops structure was indexed). Note that the
  94. * runtime does not use nor take advantage of the returns of all of these
  95. * methods.
  96. */
  97. typedef struct {
  98. /** A C-string naming the type, for use by the built-in `type` function. */
  99. char *tname;
  100. /** Some type-specific flags for this type. */
  101. unsigned short tflags;
  102. /** Called with [this, rhs] to perform binary addition ("+"). */
  103. sol_cfunc_t add;
  104. /** Called with [this, rhs] to perform binary subtraction ("-"). */
  105. sol_cfunc_t sub;
  106. /** Called with [this, rhs] to perform binary multiplication ("*"). */
  107. sol_cfunc_t mul;
  108. /** Called with [this, rhs] to perform binary division ("/"). */
  109. sol_cfunc_t div;
  110. /** Called with [this, rhs] to perform binary modulus ("%"). */
  111. sol_cfunc_t mod;
  112. /** Called with [this, rhs] to perform binary exponentiation ("**"). */
  113. sol_cfunc_t pow;
  114. /** Called with [this, rhs] to perform the triple-bang operation ("!!!"), defaults to identity-swapping two objects. */
  115. sol_cfunc_t tbang;
  116. /** Called with [this, rhs] to perform binary bitwise AND ("&") */
  117. sol_cfunc_t band;
  118. /** Called with [this, rhs] to perform binary bitwise OR ("|") */
  119. sol_cfunc_t bor;
  120. /** Called with [this, rhs] to perform binary bitwise XOR ("^") */
  121. sol_cfunc_t bxor;
  122. /** Called with [this, rhs] to perform binary bitwise left shift ("<<") */
  123. sol_cfunc_t blsh;
  124. /** Called with [this, rhs] to perform binary bitwise right shift (">>") */
  125. sol_cfunc_t brsh;
  126. /** Called with [this] to perform bitwise not ("~") */
  127. sol_cfunc_t bnot;
  128. /** 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) */
  129. sol_cfunc_t cmp;
  130. /** Called with [this, arg1, arg2, ...] to perform a call (as "this(arg1, arg2, ...)") */
  131. sol_cfunc_t call;
  132. /** Called with [this, index] to perform an index like "this[index]" or "this.index" (in the latter, index will be a string object) */
  133. sol_cfunc_t index;
  134. /** Called with [this, index, value] to perform a setindex (like "this[index] = value" or "this.index = value" for index being a string object) */
  135. sol_cfunc_t setindex;
  136. /** Called with [this] to perform a length predicate (like "#this") */
  137. sol_cfunc_t len;
  138. /** Called with [this] to return a function object (or cfunction object) that will iterate over "this" (see the iterator protocol for more details) */
  139. sol_cfunc_t iter;
  140. /** Called with [this] to cast "this" to an integer object. This may raise an error, which should be checked. */
  141. sol_cfunc_t toint;
  142. /** Called with [this] to cast "this" to a float object. This may raise an error, which should be checked. */
  143. sol_cfunc_t tofloat;
  144. /** 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. */
  145. sol_cfunc_t tostring;
  146. /** Called with [this] to cast "this" to a buffer object. This generally shouldn't raise an error, and usually falls back to converting the tostring to a buffer (which might be lossy if the string has embedded NULs). */
  147. sol_cfunc_t tobuffer;
  148. /** 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. */
  149. sol_cfunc_t repr;
  150. /** 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. */
  151. sol_cfunc_t init;
  152. /** 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. */
  153. sol_cfunc_t free;
  154. } sol_ops_t;
  155. /** Don't eval arguments passed to ops->call; you will get AST expr_nodes
  156. * instead (wrapped up in SOL_EXPR objects). Call sol_eval to evaluate them when
  157. * desired. */
  158. #define SOL_TF_NO_EVAL_CALL_ARGS 1
  159. /** Object types known to Sol.
  160. *
  161. * This is rarely checked and generally only used where necessary, as there is
  162. * no way to extend this list naturally for an extension developer.
  163. *
  164. * For each of these types, there is almost certainly a test macro for it.
  165. */
  166. typedef enum {
  167. /** The singlet type--the type of None, as well as OutOfMemory. It is also the "default" type. */
  168. SOL_SINGLET,
  169. /** The integer type, implemented as a long. */
  170. SOL_INTEGER,
  171. /** The floating point type, implemented as a double. */
  172. SOL_FLOAT,
  173. /** The string type, implemented as a C string. */
  174. SOL_STRING,
  175. /** The list type, implemented as a DSL sequence of object pointers. */
  176. SOL_LIST,
  177. /** The map type, implemented as a DSL sequence of MCELL object pointers arranged as an associative array.. */
  178. SOL_MAP,
  179. /** The mcell type, a simple key-value pair only to be found in a map. */
  180. SOL_MCELL,
  181. /** The function type, the type of all user-defined functions in Sol. */
  182. SOL_FUNCTION,
  183. /** The macro type, the type of all user-defined macros in Sol. */
  184. SOL_MACRO,
  185. /** The cfunction type, the type of objects wrapping a `sol_cfunc_t`. */
  186. SOL_CFUNCTION,
  187. /** The cfunction type, the type of objects wrapping a `sol_cfunc_t` without evaluating their arguments. */
  188. SOL_CMACRO,
  189. /** The statement type, the type of objects wrapping a `stmt_node`. */
  190. SOL_STMT,
  191. /** The expression type, the type of objects wrapping an `expr_node`. */
  192. SOL_EXPR,
  193. /** The buffer type, a type designed to access arbitrary memory. */
  194. SOL_BUFFER,
  195. /** The dylib type, the type of dynamically-loaded shared libraries. */
  196. SOL_DYLIB,
  197. /** The dysym type, the type of symbols resolved in dylib objects. */
  198. SOL_DYSYM,
  199. /** The stream type, the type wrapping FILE *. */
  200. SOL_STREAM,
  201. /** The cdata type, the type used for extension by various modules. */
  202. SOL_CDATA
  203. } sol_objtype_t;
  204. /** Buffer types.
  205. *
  206. * These types indicate what a buffer or subsection of a buffer may refer to.
  207. */
  208. typedef enum {
  209. /** The region is typeless. This is the default, and prohibits access unless it is retyped. */
  210. BUF_NONE,
  211. /** The region contains an 8-bit signed integer. */
  212. BUF_INT8,
  213. /** The region contains a 16-bit signed integer. */
  214. BUF_INT16,
  215. /** The region contains a 32-bit signed integer. */
  216. BUF_INT32,
  217. /** The region contains a 64-bit signed integer. */
  218. BUF_INT64,
  219. /** The region contains an 8-bit unsigned integer. */
  220. BUF_UINT8,
  221. /** The region contains a 16-bit unsigned integer. */
  222. BUF_UINT16,
  223. /** The region contains a 32-bit unsigned integer. */
  224. BUF_UINT32,
  225. /** The region contains a 64-bit unsigned integer. */
  226. BUF_UINT64,
  227. /** The region contains an ASCII character. */
  228. BUF_CHAR,
  229. /** The region contains exactly one addressable unit. */
  230. BUF_BYTE,
  231. /** The region contains a platform-sized signed integer. */
  232. BUF_INT,
  233. /** The region contains a platform-sized unsigned integer. */
  234. BUF_UINT,
  235. /** The region contains a platform-sized signed long integer. */
  236. BUF_LONG,
  237. /** The region contains a platform-sized unsigned long integer. */
  238. BUF_ULONG,
  239. /** The region contains a platform single-precision floating point. */
  240. BUF_FLOAT,
  241. /** The region contains a platform double-precision floating point. */
  242. BUF_DOUBLE,
  243. /** The region contains a pointer to a NUL-terminated C string. */
  244. BUF_CSTR,
  245. /** The region contains a generic pointer (which will instantiate another buffer). */
  246. BUF_PTR
  247. } sol_buftype_t;
  248. /** Ownership types.
  249. *
  250. * These functions determine what happens to the memory region aliased by a
  251. * buffer when that object is freed or copied.
  252. */
  253. typedef enum {
  254. /** Nothing happens; the object is freed or copied normally. */
  255. OWN_NONE,
  256. /** The libc `free` function is called on the buffer. Nothing happens when a new buffer is made to alias it. */
  257. OWN_FREE,
  258. /** The movefunc and freefunc are respectively consulted. */
  259. OWN_CALLF
  260. } sol_owntype_t;
  261. /**
  262. * Transput modes.
  263. *
  264. * These constants are defined (by the same name) on the `io` module as valid bits for the second argument to `io.open`.
  265. */
  266. typedef enum {
  267. /** Permit reading. If this is not set, any attempt to read will raise an error. */
  268. MODE_READ = 1,
  269. /** Permit writing. If this is not set, any attempt to write will raise an error. */
  270. MODE_WRITE = 2,
  271. /** 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. */
  272. MODE_APPEND = 4,
  273. /** When opened for writing, truncate the file to zero size. Previous contents are lost. */
  274. MODE_TRUNCATE = 8,
  275. /** Prepare the file for reading or writing binary data as opposed to text. */
  276. MODE_BINARY = 16
  277. } sol_modes_t;
  278. /** Buffer freeing function.
  279. *
  280. * This is called with the buffer region and given size when a buffer object is
  281. * freed (from state.BufferOps.free) when the `sol_owntype_t` is set to
  282. * `OWN_CALLF`. It should do whatever is needed to release this one alias of
  283. * memory. Note that care should be taken if multiple buffer objects alias the
  284. * same region.
  285. */
  286. typedef void (*sol_freefunc_t)(void *, size_t);
  287. /** Buffer moving function.
  288. *
  289. * This is called with the buffer region and given size when a buffer object is
  290. * somehow copied (usually by dereferencing a `BUF_PTR`). It should return the
  291. * region that the new buffer object should refer to. The size is assumed to
  292. * not change.
  293. */
  294. typedef void *(*sol_movefunc_t)(void *, size_t);
  295. /** Object structure.
  296. *
  297. * This structure defines the interface of every Sol object. Just as well (and
  298. * as an implementation detail), it contains the operative members of every
  299. * built-in type.
  300. */
  301. typedef struct sol_tag_object_t {
  302. /** The type of this object. */
  303. sol_objtype_t type;
  304. /** The number of living references to this object, increased by `sol_incref` and decreased by `sol_obj_free`. */
  305. int refcnt;
  306. /** The ops structure defining the behavior of this object under certain operations (more or less, its behavioral "type"). */
  307. sol_ops_t *ops;
  308. union {
  309. /** For `SOL_INTEGER`, the value of the integer. */
  310. long ival;
  311. /** For `SOL_FLOAT`, the value of the floating point number. */
  312. double fval;
  313. /** For `SOL_STRING`, the C string pointer. For `SOL_SINGLET`, the name of this singlet. */
  314. char *str;
  315. /** For `SOL_LIST` and `SOL_MAP`, the DSL sequence that contains the items or pairs. */
  316. dsl_seq *seq;
  317. struct {
  318. /** For `SOL_MCELL`, the key of the pair. */
  319. struct sol_tag_object_t *key;
  320. /** For `SOL_MCELL`, the value of the pair. */
  321. struct sol_tag_object_t *val;
  322. };
  323. struct {
  324. /** For `SOL_FUNCTION`, the `stmt_node` pointer representing the function's body. */
  325. void *func; // Actually a stmt_node *
  326. /** For `SOL_FUNCTION`, the `identlist_node` pointer representing the list of the functions argument names. */
  327. void *args; // Actually an identlist_node *
  328. /** For `SOL_FUNCTION`, a map representing the closure (initial scope, updated on exit) of the function. */
  329. struct sol_tag_object_t *closure;
  330. /** For `SOL_FUNCTION`, a map of data defined by the user on this function object. */
  331. struct sol_tag_object_t *udata;
  332. /** For `SOL_FUNCTION`, the name of the function if it was not declared anonymously (otherwise NULL). */
  333. char *fname;
  334. /** For `SOL_FUNCTION`, the name of an argument that receives extra parameters as a list (otherwise NULL). */
  335. char *rest;
  336. /** For `SOL_FUNCTION`, the map of annotations, with arguments by name, and the function itself by object. */
  337. struct sol_tag_object_t *annos;
  338. };
  339. struct {
  340. /** For `SOL_CFUNCTION`, the C function pointer. */
  341. sol_cfunc_t cfunc;
  342. /** For `SOL_CFUNCTION`, the name of this function, or NULL. */
  343. char *cfname;
  344. };
  345. /** For `SOL_STMT` and `SOL_EXPR`, the `stmt_node` or `expr_node` pointer, respectively. */
  346. void *node;
  347. struct {
  348. /** For `SOL_BUFFER`, the memory region referred to by this buffer. */
  349. void *buffer;
  350. /** For `SOL_BUFFER`, the size of this memory region. Negative values indicate no or unknown size. */
  351. ssize_t sz;
  352. /** For `SOL_BUFFER`, the ownership type of this buffer's region. */
  353. sol_owntype_t own;
  354. /** For `SOL_BUFFER`, the freeing function if own == `OWN_CALLF` */
  355. sol_freefunc_t freef;
  356. /** For `SOL_BUFFER`, the moving function if own == `OWN_CALLF` */
  357. sol_movefunc_t movef;
  358. };
  359. /** For `SOL_DYLIB`, the handle as returned by `dlopen`. */
  360. void *dlhandle;
  361. struct {
  362. /** For `SOL_DYSYM`, the symbol as resolved by `dlsym`. */
  363. void *dlsym;
  364. /** 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. */
  365. dsl_seq *argtp;
  366. /** 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. */
  367. sol_buftype_t rettp;
  368. };
  369. struct {
  370. /** For `SOL_STREAM`, the actual file object. */
  371. FILE *stream;
  372. /** For `SOL_STREAM`, the modes for which this stream is open. */
  373. sol_modes_t modes;
  374. };
  375. /** For `SOL_CDATA`, an arbitrary, user-defined pointer. */
  376. void *cdata;
  377. };
  378. } sol_object_t;
  379. /** State flags.
  380. *
  381. * These flags get set during execution and indicate an altered state of
  382. * interpretation (other than the altered state of interpretation that comes
  383. * about due to an error propagation).
  384. */
  385. typedef enum {SF_NORMAL, SF_BREAKING, SF_CONTINUING} sol_state_flag_t;
  386. typedef struct sol_tag_state_t {
  387. sol_object_t *scopes; ///< A list of scope maps, innermost out, ending at the global scope
  388. sol_object_t *ret; ///< Return value of this function, for early return
  389. sol_object_t *traceback; ///< The last stack of statement (nodes) in the last error, or NULL
  390. sol_object_t *fnstack; ///< The stack of function objects (`SOL_FUNCTION`, `SOL_CFUNCTION`) in the current call stack
  391. sol_state_flag_t sflag; ///< Used to implement break/continue
  392. sol_object_t *error; ///< Some arbitrary error descriptor, `None` if no error
  393. sol_object_t *_stdout; ///< Standard output stream object (for print(), type `SOL_STREAM`)
  394. sol_object_t *_stdin; ///< Standard input stream object (type `SOL_STREAM`)
  395. sol_object_t *_stderr; ///< Standard error stream object (type `SOL_STREAM`)
  396. sol_object_t *None; ///< The all-important `None` object
  397. sol_object_t *OutOfMemory; ///< The semi-important `OutOfMemory` object
  398. sol_ops_t NullOps; ///< Basic, initialized operations. Not used by any extant object type.
  399. sol_ops_t SingletOps; ///< Operations on singlets (`None`, `OutOfMemory`, etc.)
  400. sol_ops_t IntOps; ///< Operations on integers
  401. sol_ops_t FloatOps; ///< Operations on floats
  402. sol_ops_t StringOps; ///< Operations on strings
  403. sol_ops_t ListOps; ///< Operations on lists
  404. sol_ops_t MapOps; ///< Operations on maps
  405. sol_ops_t MCellOps; ///< Operations on map cells (rarely used)
  406. sol_ops_t FuncOps; ///< Operations on functions
  407. sol_ops_t MacroOps; ///< Operations on macros
  408. sol_ops_t CFuncOps; ///< Operations on C functions
  409. sol_ops_t CMacroOps; ///< Operations on C macros
  410. sol_ops_t ASTNodeOps; ///< Operations on AST nodes
  411. sol_ops_t BufferOps; ///< Operations on buffers
  412. sol_ops_t DyLibOps; ///< Operations on dynamic library objects
  413. sol_ops_t DySymOps; ///< Operations on dynamic symbol objects
  414. sol_ops_t StreamOps; ///< Operations on streams
  415. sol_object_t *modules; ///< A map of modules, string name to contents, resolved at "super-global" scope (and thus overrideable)
  416. sol_object_t *methods; ///< A map of string names to methods (like "list" -> {insert=<CFunction>, remove=<CFunction>, ...}) free for private use by extension developers
  417. dsl_object_funcs obfuncs; ///< The set of object functions that allows DSL to integrate with Sol's reference counting
  418. const char *calling_type; ///< Set (during `CALL_METHOD`) to determine the type (ops structure) being invoked for this method (mostly for sol_f_not_impl)
  419. const char *calling_meth; ///< Set (during `CALL_METHOD`) to determine the method name being invoked (mostly for sol_f_not_impl)
  420. #ifdef SOL_ICACHE
  421. sol_object_t *icache[SOL_ICACHE_MAX - SOL_ICACHE_MIN + 1]; ///< The integer cache (holds integers from `SOL_ICACHE_MIN` to `SOL_ICACHE_MAX` indexed by `[i - SOL_ICACHE_MIN]`)
  422. char icache_bypass; ///< Set to true to bypass caching--needed to avoid infinite recursion when initially populating the cache
  423. #endif
  424. sol_object_t *lastvalue; ///< Holds the value of the last expression evaluated, returned by an `if` expression
  425. sol_object_t *loopvalue; ///< Holds an initially-empty list appended to by `continue <expr>` or set to another object by `break <expr>`
  426. unsigned short features; ///< A flag field used to control the Sol initialization processs
  427. } sol_state_t;
  428. /** Don't run user initialization files. */
  429. #define SOL_FT_NO_USR_INIT 0x0001
  430. /** Be noisy in the language runtime. */
  431. #define SOL_FT_DEBUG 0x0002
  432. // state.c
  433. /** Initializes the state.
  434. *
  435. * This should be called once (and only once!) for every state; it does the important
  436. * work of ensuring that the state is ready to execute code, including:
  437. *
  438. * - Creating the initial singlet values `None` and `OutOfMemory`,
  439. * - Creating and populating the operations on all internally-defined object types.
  440. * - Initializing all built-in modules and methods.
  441. * - Running any "init.sol" files.
  442. * - Recognizing early-init errors and aborting.
  443. *
  444. * It is the singular, monolithic place where most pre-execution occurs, and language
  445. * developers may thus use it at their discretion. Extension developers should provide
  446. * their own documented initializers, and embedders should do their own initialization
  447. * immediately after calling this function.
  448. */
  449. int sol_state_init(sol_state_t *);
  450. /** Cleans up the state.
  451. *
  452. * In theory, after calling this, the state should be ready to be released (e.g., freed
  453. * if it was allocated on the heap). Importantly, it should NOT be used for any code
  454. * execution after this call (it WILL segfault).
  455. */
  456. void sol_state_cleanup(sol_state_t *);
  457. /** Resolve a name.
  458. *
  459. * Technically, a "name" can be anything (any key in a map, more precisely), but the
  460. * runtime (and most sane code) generally depends on names being strings. It is, however,
  461. * emphatically possible to populate the scopes with non-string names--for potential use
  462. * cases, see `programs/monty.sol`
  463. */
  464. sol_object_t *sol_state_resolve(sol_state_t *, sol_object_t *);
  465. /** Resolve a string name, given as a C string.
  466. *
  467. * This handles the popular case where a C program would like to resolve the value of a
  468. * variable by (string) name. In particular, it handles the memory of doing so properly.
  469. */
  470. sol_object_t *sol_state_resolve_name(sol_state_t *, const char *);
  471. /** Assign to a global name.
  472. *
  473. * This is rarely used, except in `sol_state_init`. It sets the value of the given name
  474. * (as an object) in the global (outermost) scope. Code execution generally uses the
  475. * local scope instead.
  476. */
  477. void sol_state_assign(sol_state_t *, sol_object_t *, sol_object_t *);
  478. /** Assign to a global string name, given as a C string.
  479. *
  480. * This is a convenience for `sol_state_assign`, which handles the creation and destruction
  481. * of the Sol string.
  482. */
  483. void sol_state_assign_name(sol_state_t *, const char *, sol_object_t *);
  484. /** Assign to a local name.
  485. *
  486. * Sets the name to the value in the local (innermost) scope. It has the functional equivalent
  487. * of the Sol code `<name> = <value>` in whatever context the state is in.
  488. */
  489. void sol_state_assign_l(sol_state_t *, sol_object_t *, sol_object_t *);
  490. /** Assign to a local string name, given as a C string.
  491. *
  492. * Another convenience for `sol_state_assign_l`.
  493. */
  494. void sol_state_assign_l_name(sol_state_t *, const char *, sol_object_t *);
  495. /** Push a scope.
  496. *
  497. * This adds a new (more-local) scope to the scope stack (`state->scopes`). This permits values
  498. * in such a scope to be manipulated independently of those in enclosing scopes, and their references
  499. * are discarded during the next `sol_state_pop_scope`. (The values may, of course, be present via
  500. * other references.)
  501. *
  502. * Scope stack manipulation MUST be balanced; egregious errors will occur otherwise.
  503. *
  504. * Scope stack manipulation is generally only necessary where another environment is expected for the
  505. * code running in that context; e.g., the body of a function, or an AST node from an imported file. In
  506. * particular, most control structures do NOT introduce scopes, due to the deleterious effects of having
  507. * no direct influence on enclosing scopes.
  508. */
  509. void sol_state_push_scope(sol_state_t *, sol_object_t *);
  510. /** Pops a scope.
  511. *
  512. * Removes and discards the local scope. All names and associated value references are lost.
  513. *
  514. * This MUST be balanced with `sol_state_push_scope`.
  515. */
  516. sol_object_t *sol_state_pop_scope(sol_state_t *);
  517. /** Returns the current error.
  518. *
  519. * This object is `None` if there is no error. See `sol_has_error`.
  520. */
  521. sol_object_t *sol_get_error(sol_state_t *);
  522. /** Set the current error.
  523. *
  524. * Sets the current error object. Clears the error if the object is `None`.
  525. *
  526. * Returns a new reference to `None`, suitable for returning elsewhere.
  527. */
  528. sol_object_t *sol_set_error(sol_state_t *, sol_object_t *);
  529. /** Set the current error to a string, given a C string.
  530. *
  531. * Conveniently sets the error to a string object created from the given C string.
  532. */
  533. sol_object_t *sol_set_error_string(sol_state_t *, const char *);
  534. /** Clear the current error.
  535. *
  536. * Equivalent to `sol_set_error(state, state->None)`.
  537. */
  538. void sol_clear_error(sol_state_t *);
  539. /** Prepares a traceback.
  540. *
  541. * Initializes the traceback stack to an empty list in preparation of `sol_add_traceback`.
  542. * Typically used by the runtime while recovering from an error; the value is ultimately
  543. * returned as the third element of the return list from `try`.
  544. */
  545. void sol_init_traceback(sol_state_t *);
  546. /** Adds an object to a traceback.
  547. *
  548. * This object is usually an ASTNode; typically, it is a statement which was being executed
  549. * when the relevant error occurred. This object is made the first item of the traceback pair
  550. * (the second element is the current local scope).
  551. */
  552. void sol_add_traceback(sol_state_t *, sol_object_t *);
  553. /** Gets the traceback.
  554. *
  555. * This will be a list of traceback pairs; each such pair will be [<value given to `sol_add_traceback`>,
  556. * <local scope>].
  557. */
  558. sol_object_t *sol_traceback(sol_state_t *);
  559. /** Registers a module.
  560. *
  561. * Creates a module entry by name, referring to its value. Modules resolve after globals, and
  562. * therefore form a sort of untouchable "super-global" scope. Most built-in modules reside in
  563. * this namespace.
  564. */
  565. void sol_register_module(sol_state_t *, sol_object_t *, sol_object_t *);
  566. /** Registers a module by string name, given a C string.
  567. *
  568. * A convenience for `sol_register_module`.
  569. */
  570. void sol_register_module_name(sol_state_t *, char *, sol_object_t *);
  571. /** Gets a module.
  572. *
  573. * Retrieves a module by its given name. Its value will be as it was registered.
  574. */
  575. sol_object_t *sol_get_module(sol_state_t *, sol_object_t *);
  576. /** Gets a module by string name, given a C string.
  577. *
  578. * A convenience for `sol_get_module`.
  579. */
  580. sol_object_t *sol_get_module_name(sol_state_t *, char *);
  581. /** Registers methods.
  582. *
  583. * Creates a methods entry by name, referring to its value. Methods are never resolved directly
  584. * by (non-debug) code, but are used liberally throughout the C interface for implementing named
  585. * methods on objects (such as lists, buffers, etc.) that wouldn't normally resolve names--thus
  586. * the name. Thus, the mapping forms a sort of private namespace that may freely be used by
  587. * developers as they see fit.
  588. */
  589. void sol_register_methods(sol_state_t *, sol_object_t *, sol_object_t *);
  590. /** Registers a method by string name, given a C string.
  591. *
  592. * A convenience for `sol_register_methods`.
  593. */
  594. void sol_register_methods_name(sol_state_t *, char *, sol_object_t *);
  595. /** Gets methods.
  596. *
  597. * Retrieves the methods by its name, returning the value that was registered.
  598. */
  599. sol_object_t *sol_get_methods(sol_state_t *, sol_object_t *);
  600. /** Gets methods by string name, given a C string.
  601. *
  602. * A convenience for `sol_get_methods`.
  603. */
  604. sol_object_t *sol_get_methods_name(sol_state_t *, char *);
  605. /** Index operation override for the `io` module.
  606. *
  607. * This hook virtually provides `stdin`, `stdout`, and `stderr` by returning the relevant
  608. * values on the states.
  609. */
  610. sol_object_t *sol_f_io_index(sol_state_t *, sol_object_t *);
  611. /** Setindex operation override for the `io` module.
  612. *
  613. * This hook intercepts and specially handles attempts to set `stdin`, `stdout`, and `stderr`
  614. * by setting the relevant values on the state.
  615. */
  616. sol_object_t *sol_f_io_setindex(sol_state_t *, sol_object_t *);
  617. /** Retrieves the stdin stream.
  618. *
  619. * Returns the stream object used to read program input.
  620. */
  621. sol_object_t *sol_get_stdin(sol_state_t *);
  622. /** Retrieves the stdout stream.
  623. *
  624. * Returns the stream object used to write program output.
  625. */
  626. sol_object_t *sol_get_stdout(sol_state_t *);
  627. /** Retrieves the stderr stream.
  628. *
  629. * Returns the stream object used to write program errors or out-of-band data.
  630. */
  631. sol_object_t *sol_get_stderr(sol_state_t *);
  632. /** Initializes an ops structure.
  633. *
  634. * This sets all the fields of a `sol_ops_t` to their sensible defaults. Such an initialized
  635. * structure is available on the state as `state->NullOps`.
  636. */
  637. void sol_ops_init(sol_ops_t *);
  638. // builtins.c
  639. /** Not implemented handler.
  640. *
  641. * This raises the "Undefined method" error.
  642. */
  643. sol_object_t *sol_f_not_impl(sol_state_t *, sol_object_t *);
  644. /** !!! handler.
  645. *
  646. * Swaps objects by value.
  647. */
  648. sol_object_t *sol_f_tbang(sol_state_t *, sol_object_t *);
  649. /** No operation handler.
  650. *
  651. * Does nothing.
  652. */
  653. sol_object_t *sol_f_no_op(sol_state_t *, sol_object_t *);
  654. /** Default comparison handler.
  655. *
  656. * Returns 0 (equal) if the references refer to exactly the same object, or
  657. * 1 (greater) otherwise.
  658. *
  659. * Note that this is not a partial order.
  660. */
  661. sol_object_t *sol_f_default_cmp(sol_state_t *, sol_object_t *);
  662. /** Default tostring handler.
  663. *
  664. * Returns a string formatted as "<<typename> object at <address>>".
  665. */
  666. sol_object_t *sol_f_default_tostring(sol_state_t *, sol_object_t *);
  667. /** Default torepr handler.
  668. *
  669. * Returns tostring(object).
  670. */
  671. sol_object_t *sol_f_default_repr(sol_state_t *, sol_object_t *);
  672. /** Default tobuffer handler.
  673. *
  674. * Returns buffer.fromstring(tostring(object)).
  675. */
  676. sol_object_t *sol_f_default_tobuffer(sol_state_t *, sol_object_t *);
  677. /// Built-in function toint
  678. sol_object_t *sol_f_toint(sol_state_t *, sol_object_t *);
  679. /// Built-in function tofloat
  680. sol_object_t *sol_f_tofloat(sol_state_t *, sol_object_t *);
  681. /// Built-in function tostring
  682. sol_object_t *sol_f_tostring(sol_state_t *, sol_object_t *);
  683. /// Built-in function tobuffer
  684. sol_object_t *sol_f_tobuffer(sol_state_t *, sol_object_t *);
  685. /// Built-in function try
  686. sol_object_t *sol_f_try(sol_state_t *, sol_object_t *);
  687. /// Built-in function apply
  688. sol_object_t *sol_f_apply(sol_state_t *, sol_object_t *);
  689. /// Built-in function error
  690. sol_object_t *sol_f_error(sol_state_t *, sol_object_t *);
  691. /// Built-in function type
  692. sol_object_t *sol_f_type(sol_state_t *, sol_object_t *);
  693. /// Built-in function prepr
  694. sol_object_t *sol_f_prepr(sol_state_t *, sol_object_t *);
  695. /// Built-in function print
  696. sol_object_t *sol_f_print(sol_state_t *, sol_object_t *);
  697. /// Built-in function rawget
  698. sol_object_t *sol_f_rawget(sol_state_t *, sol_object_t *);
  699. /// Built-in function rawset
  700. sol_object_t *sol_f_rawset(sol_state_t *, sol_object_t *);
  701. /// Built-in function range
  702. sol_object_t *sol_f_range(sol_state_t *, sol_object_t *);
  703. /// Built-in function exec
  704. //sol_object_t *sol_f_exec(sol_state_t *, sol_object_t *);
  705. /// Built-in function eval
  706. //sol_object_t *sol_f_eval(sol_state_t *, sol_object_t *);
  707. /// Built-in function execfile
  708. sol_object_t *sol_f_execfile(sol_state_t *, sol_object_t *);
  709. /// Built-in function parse
  710. sol_object_t *sol_f_parse(sol_state_t *, sol_object_t *);
  711. /// Built-in function ord
  712. sol_object_t *sol_f_ord(sol_state_t *, sol_object_t *);
  713. /// Built-in function chr
  714. sol_object_t *sol_f_chr(sol_state_t *, sol_object_t *);
  715. sol_object_t *sol_f_debug_getref(sol_state_t *, sol_object_t *);
  716. sol_object_t *sol_f_debug_setref(sol_state_t *, sol_object_t *);
  717. sol_object_t *sol_f_debug_closure(sol_state_t *, sol_object_t *);
  718. sol_object_t *sol_f_debug_globals(sol_state_t *, sol_object_t *);
  719. sol_object_t *sol_f_debug_locals(sol_state_t *, sol_object_t *);
  720. sol_object_t *sol_f_debug_scopes(sol_state_t *, sol_object_t *);
  721. sol_object_t *sol_f_debug_getops(sol_state_t *, sol_object_t *);
  722. sol_object_t *sol_f_iter_str(sol_state_t *, sol_object_t *);
  723. sol_object_t *sol_f_iter_buffer(sol_state_t *, sol_object_t *);
  724. sol_object_t *sol_f_iter_list(sol_state_t *, sol_object_t *);
  725. sol_object_t *sol_f_iter_map(sol_state_t *, sol_object_t *);
  726. sol_object_t *sol_f_readline_readline(sol_state_t *, sol_object_t *);
  727. sol_object_t *sol_f_readline_add_history(sol_state_t *, sol_object_t *);
  728. sol_object_t *sol_f_ast_print(sol_state_t *, sol_object_t *);
  729. sol_object_t *sol_f_singlet_tostring(sol_state_t *, sol_object_t *);
  730. sol_object_t *sol_f_singlet_tobuffer(sol_state_t *, sol_object_t *);
  731. sol_object_t *sol_f_int_add(sol_state_t *, sol_object_t *);
  732. sol_object_t *sol_f_int_sub(sol_state_t *, sol_object_t *);
  733. sol_object_t *sol_f_int_mul(sol_state_t *, sol_object_t *);
  734. sol_object_t *sol_f_int_div(sol_state_t *, sol_object_t *);
  735. sol_object_t *sol_f_int_mod(sol_state_t *, sol_object_t *);
  736. sol_object_t *sol_f_int_pow(sol_state_t *, sol_object_t *);
  737. sol_object_t *sol_f_int_band(sol_state_t *, sol_object_t *);
  738. sol_object_t *sol_f_int_bor(sol_state_t *, sol_object_t *);
  739. sol_object_t *sol_f_int_bxor(sol_state_t *, sol_object_t *);
  740. sol_object_t *sol_f_int_blsh(sol_state_t *, sol_object_t *);
  741. sol_object_t *sol_f_int_brsh(sol_state_t *, sol_object_t *);
  742. sol_object_t *sol_f_int_bnot(sol_state_t *, sol_object_t *);
  743. sol_object_t *sol_f_int_cmp(sol_state_t *, sol_object_t *);
  744. sol_object_t *sol_f_int_toint(sol_state_t *, sol_object_t *);
  745. sol_object_t *sol_f_int_tofloat(sol_state_t *, sol_object_t *);
  746. sol_object_t *sol_f_int_tostring(sol_state_t *, sol_object_t *);
  747. sol_object_t *sol_f_float_add(sol_state_t *, sol_object_t *);
  748. sol_object_t *sol_f_float_sub(sol_state_t *, sol_object_t *);
  749. sol_object_t *sol_f_float_mul(sol_state_t *, sol_object_t *);
  750. sol_object_t *sol_f_float_div(sol_state_t *, sol_object_t *);
  751. sol_object_t *sol_f_float_pow(sol_state_t *, sol_object_t *);
  752. sol_object_t *sol_f_float_cmp(sol_state_t *, sol_object_t *);
  753. sol_object_t *sol_f_float_toint(sol_state_t *, sol_object_t *);
  754. sol_object_t *sol_f_float_tofloat(sol_state_t *, sol_object_t *);
  755. sol_object_t *sol_f_float_tostring(sol_state_t *, sol_object_t *);
  756. sol_object_t *sol_f_str_add(sol_state_t *, sol_object_t *);
  757. sol_object_t *sol_f_str_mul(sol_state_t *, sol_object_t *);
  758. sol_object_t *sol_f_str_len(sol_state_t *, sol_object_t *);
  759. sol_object_t *sol_f_str_iter(sol_state_t *, sol_object_t *);
  760. sol_object_t *sol_f_str_cmp(sol_state_t *, sol_object_t *);
  761. sol_object_t *sol_f_str_index(sol_state_t *, sol_object_t *);
  762. sol_object_t *sol_f_str_toint(sol_state_t *, sol_object_t *);
  763. sol_object_t *sol_f_str_tofloat(sol_state_t *, sol_object_t *);
  764. sol_object_t *sol_f_str_tostring(sol_state_t *, sol_object_t *);
  765. sol_object_t *sol_f_str_tobuffer(sol_state_t *, sol_object_t *);
  766. sol_object_t *sol_f_str_repr(sol_state_t *, sol_object_t *);
  767. sol_object_t *sol_f_str_sub(sol_state_t *, sol_object_t *);
  768. sol_object_t *sol_f_str_split(sol_state_t *, sol_object_t *);
  769. sol_object_t *sol_f_str_find(sol_state_t *, sol_object_t *);
  770. sol_object_t *sol_f_list_add(sol_state_t *, sol_object_t *);
  771. sol_object_t *sol_f_list_mul(sol_state_t *, sol_object_t *);
  772. sol_object_t *sol_f_list_cmp(sol_state_t *, sol_object_t *);
  773. sol_object_t *sol_f_list_index(sol_state_t *, sol_object_t *);
  774. sol_object_t *sol_f_list_setindex(sol_state_t *, sol_object_t *);
  775. sol_object_t *sol_f_list_len(sol_state_t *, sol_object_t *);
  776. sol_object_t *sol_f_list_iter(sol_state_t *, sol_object_t *);
  777. sol_object_t *sol_f_list_tostring(sol_state_t *, sol_object_t *);
  778. sol_object_t *sol_f_list_copy(sol_state_t *, sol_object_t *);
  779. sol_object_t *sol_f_list_insert(sol_state_t *, sol_object_t *);
  780. sol_object_t *sol_f_list_remove(sol_state_t *, sol_object_t *);
  781. sol_object_t *sol_f_list_truncate(sol_state_t *, sol_object_t *);
  782. sol_object_t *sol_f_list_map(sol_state_t *, sol_object_t *);
  783. sol_object_t *sol_f_list_filter(sol_state_t *, sol_object_t *);
  784. sol_object_t *sol_f_list_reduce(sol_state_t *, sol_object_t *);
  785. sol_object_t *sol_f_map_add(sol_state_t *, sol_object_t *);
  786. sol_object_t *sol_f_map_index(sol_state_t *, sol_object_t *);
  787. sol_object_t *sol_f_map_setindex(sol_state_t *, sol_object_t *);
  788. sol_object_t *sol_f_map_call(sol_state_t *, sol_object_t *);
  789. sol_object_t *sol_f_map_len(sol_state_t *, sol_object_t *);
  790. sol_object_t *sol_f_map_iter(sol_state_t *, sol_object_t *);
  791. sol_object_t *sol_f_map_tostring(sol_state_t *, sol_object_t *);
  792. sol_object_t *sol_f_map_repr(sol_state_t *, sol_object_t *);
  793. sol_object_t *sol_f_mcell_tostring(sol_state_t *, sol_object_t *);
  794. sol_object_t *sol_f_func_call(sol_state_t *, sol_object_t *); // Defined in ast.c
  795. sol_object_t *sol_f_func_index(sol_state_t *, sol_object_t *);
  796. sol_object_t *sol_f_func_setindex(sol_state_t *, sol_object_t *);
  797. sol_object_t *sol_f_func_tostring(sol_state_t *, sol_object_t *);
  798. sol_object_t *sol_f_cfunc_call(sol_state_t *, sol_object_t *);
  799. sol_object_t *sol_f_cfunc_tostring(sol_state_t *, sol_object_t *);
  800. sol_object_t *sol_f_astnode_call(sol_state_t *, sol_object_t *);
  801. sol_object_t *sol_f_astnode_index(sol_state_t *, sol_object_t *);
  802. sol_object_t *sol_f_astnode_setindex(sol_state_t *, sol_object_t *);
  803. sol_object_t *sol_f_astnode_tostring(sol_state_t *, sol_object_t *);
  804. sol_object_t *sol_f_buffer_index(sol_state_t *, sol_object_t *);
  805. sol_object_t *sol_f_buffer_add(sol_state_t *, sol_object_t *);
  806. sol_object_t *sol_f_buffer_mul(sol_state_t *, sol_object_t *);
  807. sol_object_t *sol_f_buffer_cmp(sol_state_t *, sol_object_t *);
  808. sol_object_t *sol_f_buffer_len(sol_state_t *, sol_object_t *);
  809. sol_object_t *sol_f_buffer_iter(sol_state_t *, sol_object_t *);
  810. sol_object_t *sol_f_buffer_tostring(sol_state_t *, sol_object_t *);
  811. sol_object_t *sol_f_buffer_repr(sol_state_t *, sol_object_t *);
  812. sol_object_t *sol_f_buffer_toint(sol_state_t *, sol_object_t *);
  813. sol_object_t *sol_f_buffer_tofloat(sol_state_t *, sol_object_t *);
  814. sol_object_t *sol_f_buffer_tobuffer(sol_state_t *, sol_object_t *);
  815. sol_object_t *sol_f_buffer_get(sol_state_t *, sol_object_t *);
  816. sol_object_t *sol_f_buffer_set(sol_state_t *, sol_object_t *);
  817. sol_object_t *sol_f_buffer_address(sol_state_t *, sol_object_t *);
  818. sol_object_t *sol_f_buffer_size(sol_state_t *, sol_object_t *);
  819. sol_object_t *sol_f_buffer_sub(sol_state_t *, sol_object_t *);
  820. sol_object_t *sol_f_buffer_split(sol_state_t *, sol_object_t *);
  821. sol_object_t *sol_f_buffer_find(sol_state_t *, sol_object_t *);
  822. sol_object_t *sol_f_buffer_new(sol_state_t *, sol_object_t *);
  823. sol_object_t *sol_f_buffer_fromstring(sol_state_t *, sol_object_t *);
  824. sol_object_t *sol_f_buffer_fromobject(sol_state_t *, sol_object_t *);
  825. sol_object_t *sol_f_buffer_fromaddress(sol_state_t *, sol_object_t *);
  826. sol_object_t *sol_f_dylib_index(sol_state_t *, sol_object_t *);
  827. sol_object_t *sol_f_dylib_tostring(sol_state_t *, sol_object_t *);
  828. sol_object_t *sol_f_dylib_open(sol_state_t *, sol_object_t *);
  829. sol_object_t *sol_f_dysym_call(sol_state_t *, sol_object_t *);
  830. sol_object_t *sol_f_dysym_index(sol_state_t *, sol_object_t *);
  831. sol_object_t *sol_f_dysym_setindex(sol_state_t *, sol_object_t *);
  832. sol_object_t *sol_f_dysym_tostring(sol_state_t *, sol_object_t *);
  833. sol_object_t *sol_f_dysym_get(sol_state_t *, sol_object_t *);
  834. sol_object_t *sol_f_dysym_set(sol_state_t *, sol_object_t *);
  835. sol_object_t *sol_f_stream_blsh(sol_state_t *, sol_object_t *);
  836. sol_object_t *sol_f_stream_brsh(sol_state_t *, sol_object_t *);
  837. sol_object_t *sol_f_stream_index(sol_state_t *, sol_object_t *);
  838. sol_object_t *sol_f_stream_tostring(sol_state_t *, sol_object_t *);
  839. sol_object_t *sol_f_stream_write(sol_state_t *, sol_object_t *);
  840. /*sol_object_t *sol_f_stream_read(sol_state_t *, sol_object_t *);*/
  841. sol_object_t *sol_f_stream_read_buffer(sol_state_t *, sol_object_t *);
  842. sol_object_t *sol_f_stream_seek(sol_state_t *, sol_object_t *);
  843. sol_object_t *sol_f_stream_tell(sol_state_t *, sol_object_t *);
  844. sol_object_t *sol_f_stream_flush(sol_state_t *, sol_object_t *);
  845. sol_object_t *sol_f_stream_eof(sol_state_t *, sol_object_t *);
  846. sol_object_t *sol_f_stream_ioctl(sol_state_t *, sol_object_t *);
  847. sol_object_t *sol_f_stream_open(sol_state_t *, sol_object_t *);
  848. // object.c
  849. #define sol_is_singlet(obj) ((obj)->type == SOL_SINGLET)
  850. #define sol_is_none(state, obj) ((obj) == state->None)
  851. #define sol_is_oom(state, obj) ((obj) == state->OutOfMemory)
  852. #define sol_is_int(obj) ((obj)-> type == SOL_INTEGER)
  853. #define sol_is_float(obj) ((obj)->type == SOL_FLOAT)
  854. #define sol_is_string(obj) ((obj)->type == SOL_STRING)
  855. #define sol_is_list(obj) ((obj)->type == SOL_LIST)
  856. #define sol_is_map(obj) ((obj)->type == SOL_MAP || (obj)->type == SOL_MCELL)
  857. #define sol_is_func(obj) ((obj)->type == SOL_FUNCTION)
  858. #define sol_is_macro(obj) ((obj)->type == SOL_MACRO)
  859. #define sol_is_cfunc(obj) ((obj)->type == SOL_CFUNCTION)
  860. #define sol_is_aststmt(obj) ((obj)->type == SOL_STMT)
  861. #define sol_is_astexpr(obj) ((obj)->type == SOL_EXPR)
  862. #define sol_is_astnode(obj) (sol_is_aststmt(obj) || sol_is_astexpr(obj))
  863. #define sol_is_buffer(obj) ((obj)->type == SOL_BUFFER)
  864. #define sol_is_cdata(obj) ((obj)->type == SOL_CDATA)
  865. #define sol_is_name(obj) (sol_is_string(obj) || sol_is_buffer(obj))
  866. #define sol_name_eq(state, obj, cstr) (sol_is_string(obj) ? sol_string_eq((state), (obj), (cstr)) : (sol_is_buffer(obj) ? sol_buffer_eq((state), (obj), (cstr)) : 0))
  867. #define sol_has_error(state) (!sol_is_none((state), (state)->error))
  868. /** Creates a new singlet object with the specified name (or NULL).
  869. *
  870. * Singlets are special objects that are equal only by identity. They are used
  871. * wherever a particular value has special meaning (e.g. None). Other than
  872. * that, their lack of function makes them difficult to manipulate, and many
  873. * internal routines are special-cased for certain singlets.
  874. */
  875. sol_object_t *sol_new_singlet(sol_state_t *, const char *);
  876. /** Creates a new integer object with the specified value.
  877. *
  878. * If `icache_bypass` is off and this value is within [`SOL_ICACHE_MIN`,
  879. * `SOL_ICACHE_MAX`] (as set at compile time), a new reference to a cached
  880. * integer in the state is returned instead.
  881. */
  882. sol_object_t *sol_new_int(sol_state_t *, long);
  883. /** Creates a new float object with the specified value. */
  884. sol_object_t *sol_new_float(sol_state_t *, double);
  885. /** Creates a new string object with the specified value. */
  886. sol_object_t *sol_new_string(sol_state_t *, const char *);
  887. /** Utility function to compare a Sol string and a C string, used often in
  888. * builtin and extension code. */
  889. int sol_string_cmp(sol_state_t *, sol_object_t *, const char *);
  890. /** Utility macro wrapping `sol_string_cmp`. */
  891. #define sol_string_eq(state, string, cstr) (sol_string_cmp((state), (string), (cstr))==0)
  892. /** Internal routine that returns a new Sol string that results from the
  893. * concatenation of two Sol strings (in the order given). */
  894. sol_object_t *sol_string_concat(sol_state_t *, sol_object_t *, sol_object_t *);
  895. /** Utility function for conveniently concatenating a Sol string and a C string
  896. * (and returning a Sol string). */
  897. sol_object_t *sol_string_concat_cstr(sol_state_t *, sol_object_t *, char *);
  898. /** Creates a new empty Sol list. */
  899. sol_object_t *sol_new_list(sol_state_t *);
  900. /** Creates a new Sol list populated with objects obtained by iterating over a
  901. * DSL sequence. */
  902. sol_object_t *sol_list_from_seq(sol_state_t *, dsl_seq *);
  903. /** Internal routine to get the length of a Sol list */
  904. int sol_list_len(sol_state_t *, sol_object_t *);
  905. /** Internal routine to return a new Sol list equivalent to its input with the
  906. * first n elements skipped. */
  907. sol_object_t *sol_list_sublist(sol_state_t *, sol_object_t *, int);
  908. /** Internal routine to get the object at the specified index in a Sol list. */
  909. sol_object_t *sol_list_get_index(sol_state_t *, sol_object_t *, int);
  910. /** Internal routine to set the object at the specified index in a Sol list. */
  911. void sol_list_set_index(sol_state_t *, sol_object_t *, int, sol_object_t *);
  912. /** Internal routine to insert an object at the specified index in a Sol list.
  913. *
  914. * Unlike setting, insertion may happen at the lists length, inclusive (in
  915. * which case it appends an element). When this routine returns successfully
  916. * (without an error on the state), the index specified should hold a reference
  917. * to the object given as a parameter.
  918. */
  919. void sol_list_insert(sol_state_t *, sol_object_t *, int, sol_object_t *);
  920. /** Internal routine to remove an object at the specified index in a Sol list,
  921. * returning a reference to that object. */
  922. sol_object_t *sol_list_remove(sol_state_t *, sol_object_t *, int);
  923. /** Internal routine to return a copy of a Sol list.
  924. *
  925. * Note that this performs a "shallow" copy, in that while the new list is a
  926. * different reference, the references inside the list are the same.
  927. */
  928. sol_object_t *sol_list_copy(sol_state_t *, sol_object_t *);
  929. /** Internal routine to return a new Sol list equivalent to its input up to the
  930. * first n elements. */
  931. sol_object_t *sol_list_truncate(sol_state_t *, sol_object_t *, int);
  932. /** Utility routine to concatenate Sol lists. */
  933. void sol_list_append(sol_state_t *, sol_object_t *, sol_object_t *);
  934. /** Utility macro to insert an object at the beginning of a Sol list. */
  935. #define sol_list_push(st, ls, obj) sol_list_insert(st, ls, 0, obj);
  936. /** Utility macro to remove and return the object at the beginning of a Sol
  937. * list. */
  938. #define sol_list_pop(st, ls) sol_list_remove(st, ls, 0);
  939. /** Creates a new empty Sol map. */
  940. sol_object_t *sol_new_map(sol_state_t *);
  941. /** Internal routine to get the length (number of associations) in a Sol map. */
  942. int sol_map_len(sol_state_t *, sol_object_t *);
  943. /** Internal routine to get an MCELL by index.
  944. *
  945. * This is most typically used to iterate over the associations in a map in an
  946. * arbitrary order.
  947. */
  948. sol_object_t *sol_map_mcell_index(sol_state_t *, sol_object_t *, int);
  949. /** Internal routine to get an MCELL with key equal to `key`, or `None`.
  950. *
  951. * This does most of the work of association lookup; many other functions in
  952. * the map internal API are built upon this one.
  953. */
  954. sol_object_t *sol_map_mcell(sol_state_t *, sol_object_t *, sol_object_t *);
  955. /** Internal routine to determine if a key is in a map. */
  956. int sol_map_has(sol_state_t *, sol_object_t *, sol_object_t *);
  957. /** Internal routine to get the value associated with a key in a map, or `None`
  958. * if there is no association.. */
  959. sol_object_t *sol_map_get(sol_state_t *, sol_object_t *, sol_object_t *);
  960. /** Internal routine to get the value associated with a string key (specified
  961. * as a C string) in a map, or `None` if there is no association. */
  962. sol_object_t *sol_map_get_name(sol_state_t *, sol_object_t *, char *);
  963. /** Internal routine to set an association in a map.
  964. *
  965. * If the key had a previous association, it is lost. If the value is `None`,
  966. * any existing association is deleted; this is consistent with a return of
  967. * `None` for any map get for which no association exists.
  968. */
  969. void sol_map_set(sol_state_t *, sol_object_t *, sol_object_t *, sol_object_t *);
  970. /** Internal routine to set an association, borrowing a reference to the value
  971. * instead of owning a reference.
  972. *
  973. * This is mostly used in `sol_state_init`, where it avoids having to
  974. * `sol_obj_free` after creating a new object just to associate it.
  975. *
  976. * Note that this actually decrements the reference count on your pointer--the
  977. * map still increments the reference count, but this effect is nullified, so
  978. * it works out the same way.
  979. */
  980. #define sol_map_borrow(state, map, key, object) do {\
  981. sol_object_t *__obj = (object);\
  982. sol_map_set((state), (map), (key), __obj);\
  983. sol_obj_free(__obj);\
  984. } while(0)
  985. /** Internal routine to set a map association with a C-string key. */
  986. void sol_map_set_name(sol_state_t *, sol_object_t *, char *, sol_object_t *);
  987. /** Internal routine to set a map association with a C-string key, and
  988. * borrowing a reference to the value. */
  989. #define sol_map_borrow_name(state, map, str, object) do {\
  990. sol_object_t *__obj = (object);\
  991. sol_map_set_name((state), (map), (str), __obj);\
  992. sol_obj_free(__obj);\
  993. } while(0)
  994. /** Internal routine to set a map associaiton to a new value only if the key
  995. * was associated with a value (other than `None`) previously.
  996. *
  997. * This is mostly used in the end of `sol_f_func_call` to update the closure.
  998. */
  999. void sol_map_set_existing(sol_state_t *, sol_object_t *, sol_object_t *, sol_object_t *);
  1000. /** Creates a new copy of an existing Sol map. */
  1001. sol_object_t *sol_map_copy(sol_state_t *, sol_object_t *);
  1002. /** Merges the associations of the source map into the destination map.
  1003. *
  1004. * Associations in the source map take precedence if the same key exists in
  1005. * both.
  1006. */
  1007. void sol_map_merge(sol_state_t *, sol_object_t *, sol_object_t *);
  1008. /** Merges the associations of the source map into the destination map, but
  1009. * only for keys already in the destination map. */
  1010. void sol_map_merge_existing(sol_state_t *, sol_object_t *, sol_object_t *);
  1011. /** Updates a map to contain an association from value to key for every key and
  1012. * value already within. */
  1013. void sol_map_invert(sol_state_t *, sol_object_t *);
  1014. // Defined in ast.h
  1015. // sol_object_t *sol_new_func(sol_state_t *, identlist_node *, stmt_node *, char *);
  1016. // sol_object_t *sol_new_stmtnode(sol_state_t *, stmt_node *);
  1017. // sol_object_t *sol_new_exprnode(sol_state_t *, expr_node *);
  1018. sol_object_t *sol_new_cfunc(sol_state_t *, sol_cfunc_t, char *);
  1019. sol_object_t *sol_new_cmacro(sol_state_t *, sol_cfunc_t, char *);
  1020. sol_object_t *sol_new_cdata(sol_state_t *, void *, sol_ops_t *);
  1021. sol_object_t *sol_new_buffer(sol_state_t *, void *, ssize_t, sol_owntype_t, sol_freefunc_t, sol_movefunc_t);
  1022. int sol_buffer_cmp(sol_state_t *, sol_object_t *, const char *);
  1023. #define sol_buffer_eq(state, buffer, cstr) (sol_buffer_cmp((state), (buffer), (cstr)) == 0)
  1024. sol_object_t *sol_buffer_concat(sol_state_t *, sol_object_t *, sol_object_t *);
  1025. sol_object_t *sol_buffer_concat_cstr(sol_state_t *, sol_object_t *, char *);
  1026. char *sol_buffer_strdup(sol_object_t *);
  1027. sol_object_t *sol_new_dylib(sol_state_t *, void *);
  1028. sol_object_t *sol_new_dysym(sol_state_t *, void *, dsl_seq *, sol_buftype_t);
  1029. sol_object_t *sol_new_stream(sol_state_t *, FILE *, sol_modes_t);
  1030. size_t sol_stream_printf(sol_state_t *, sol_object_t *, const char *, ...);
  1031. size_t sol_stream_vprintf(sol_state_t *, sol_object_t *, const char *, va_list);
  1032. size_t sol_stream_scanf(sol_state_t *, sol_object_t *, const char *, ...);
  1033. size_t sol_stream_fread(sol_state_t *, sol_object_t *, char *, size_t, size_t);
  1034. size_t sol_stream_fwrite(sol_state_t *, sol_object_t *, char *, size_t, size_t);
  1035. char *sol_stream_fgets(sol_state_t *, sol_object_t *, char *, size_t);
  1036. int sol_stream_fputc(sol_state_t *, sol_object_t *, int);
  1037. #define _sol_io_on(state, op, strname, ...) do {\
  1038. sol_object_t *__str = sol_get_##strname(state);\
  1039. sol_stream_##op((state), __str, __VA_ARGS__);\
  1040. sol_obj_free(__str);\
  1041. } while(0)
  1042. #define sol_printf(state, ...) _sol_io_on(state, printf, stdout, __VA_ARGS__)
  1043. #define sol_vprintf(state, ...) _sol_io_on(state, vprintf, stdout, __VA_ARGS__)
  1044. #define sol_scanf(state, ...) _sol_io_on(state, scanf, stdin, __VA_ARGS__)
  1045. #define sol_fread(state, ...) _sol_io_on(state, fread, stdin, __VA_ARGS__)
  1046. #define sol_fwrite(state, ...) _sol_io_on(state, fwrite, stdout, __VA_ARGS__)
  1047. #define sol_putchar(state, ...) _sol_io_on(state, fputc, stdout, __VA_ARGS__)
  1048. int sol_stream_feof(sol_state_t *, sol_object_t *);
  1049. int sol_stream_ferror(sol_state_t *, sol_object_t *);
  1050. #define sol_stream_ready(state, stream) (!(sol_stream_feof((state), (stream)) || sol_stream_ferror((state), (stream))))
  1051. int sol_stream_fseek(sol_state_t *, sol_object_t *, long, int);
  1052. long sol_stream_ftell(sol_state_t *, sol_object_t *);
  1053. int sol_stream_fflush(sol_state_t *, sol_object_t *);
  1054. sol_object_t *sol_cast_int(sol_state_t *, sol_object_t *);
  1055. sol_object_t *sol_cast_float(sol_state_t *, sol_object_t *);
  1056. sol_object_t *sol_cast_string(sol_state_t *, sol_object_t *);
  1057. sol_object_t *sol_cast_repr(sol_state_t *, sol_object_t *);
  1058. sol_object_t *sol_cast_buffer(sol_state_t *, sol_object_t *);
  1059. sol_object_t *sol_f_singlet_free(sol_state_t *, sol_object_t *);
  1060. sol_object_t *sol_f_str_free(sol_state_t *, sol_object_t *);
  1061. sol_object_t *sol_f_list_free(sol_state_t *, sol_object_t *);
  1062. sol_object_t *sol_f_map_free(sol_state_t *, sol_object_t *);
  1063. sol_object_t *sol_f_mcell_free(sol_state_t *, sol_object_t *);
  1064. sol_object_t *sol_f_func_free(sol_state_t *, sol_object_t *);
  1065. sol_object_t *sol_f_cfunc_free(sol_state_t *, sol_object_t *);
  1066. sol_object_t *sol_f_astnode_free(sol_state_t *, sol_object_t *);
  1067. sol_object_t *sol_f_buffer_free(sol_state_t *, sol_object_t *);
  1068. sol_object_t *sol_f_dylib_free(sol_state_t *, sol_object_t *);
  1069. sol_object_t *sol_f_stream_free(sol_state_t *, sol_object_t *);
  1070. int sol_validate_list(sol_state_t *, sol_object_t *);
  1071. int sol_validate_map(sol_state_t *, sol_object_t *);
  1072. // util.c
  1073. sol_object_t *sol_util_call(sol_state_t *, sol_object_t *, int *, int, ...);
  1074. // gc.c
  1075. #ifdef DEBUG_GC
  1076. sol_object_t *_int_sol_incref(const char *, sol_object_t *);
  1077. void _int_sol_obj_free(const char *, sol_object_t *);
  1078. sol_object_t *_sol_gc_dsl_copier(sol_object_t *);
  1079. void _sol_gc_dsl_destructor(sol_object_t *);
  1080. sol_object_t *_int_sol_alloc_object(const char *, sol_state_t *);
  1081. #define sol_incref(obj) (_int_sol_incref(__func__, (obj)))
  1082. #define sol_obj_free(obj) (_int_sol_obj_free(__func__, (obj)))
  1083. #define sol_alloc_object(state) (_int_sol_alloc_object(__func__, (state)))
  1084. #else
  1085. #define sol_incref(obj) (++((obj)->refcnt), obj)
  1086. void sol_obj_free(sol_object_t *);
  1087. sol_object_t *sol_alloc_object(sol_state_t *);
  1088. #endif
  1089. #define sol_decref(obj) (--((obj)->refcnt))
  1090. sol_object_t *sol_obj_acquire(sol_object_t *);
  1091. void sol_obj_release(sol_object_t *);
  1092. void sol_mm_initialize(sol_state_t *);
  1093. void sol_mm_finalize(sol_state_t *);
  1094. #define AS_OBJ(x) ((sol_object_t *) (x))
  1095. #endif