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.

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