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 53KB

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