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.

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