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.

1191 lines
52 KiB

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