소스 검색

Sol Part 44.1: MOM GET THE THESAURUS!

master
Graham Northup 6 년 전
부모
커밋
9ba71b5a41
  1. 10
      Doxyfile
  2. 183
      sol.h

10
Doxyfile

@ -38,7 +38,7 @@ PROJECT_NAME = Sol
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER = 0.1a4
PROJECT_NUMBER = 0.2a0
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
@ -238,7 +238,8 @@ TAB_SIZE = 4
# "Side Effects:". You can put \n's in the value part of an alias to insert
# newlines.
ALIASES =
ALIASES = "rst=\verbatim embed:rst:leading-asterisk" \
endrst=\endverbatim
# This tag can be used to specify a number of word-keyword mappings (TCL only).
# A mapping has the form "name=value". For example adding "class=itcl::class"
@ -1199,8 +1200,9 @@ HTML_COLORSTYLE_GAMMA = 80
# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
# page will contain the date and time when the page was generated. Setting this
# to NO can help when comparing the output of multiple runs.
# The default value is: YES.
# to YES can help to show when doxygen was last run and thus if the
# documentation is up to date.
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_TIMESTAMP = YES

183
sol.h

@ -61,141 +61,320 @@ typedef sol_object_t *(*sol_cfunc_t)(sol_state_t *, sol_object_t *);
/** Print function type.
*
* \deprecated This is not used anywhere and is likely to be removed in the
* near future.
* \rst
* .. admonition:: Deprecated
*
* This is not used anywhere and is likely to be removed in the
* near future.
* \endrst
*/
typedef void (*sol_printfunc_t)(sol_object_t *);
/** Type methods structure.
*
* Sol bases most of its object behavior on methods defined on so-called "ops
* structures" of this type pointed to by the objects themselves. In general,
* these contain the address of one such structure stored directly in the state
* (each state has its own set of these structures for all the builtin types,
* initialized in `sol_state_init`), but they can conceivably be allocated and
* initialized elsewhere, e.g., in extension modules.
*
* Nearly all of the fields in this structure are function pointers to
* `sol_cfunc_t` that are called when an operator is invoked on an object. In
* the case of binary operators, only the left operand is considered.
*
* In member documentation of these functions, the list [in brackets]
* represents, visually, the list that the function can expect to receive as
* the second argument (where "rhs" is right-hand-side of a binary operator,
* and "this" is the object whose ops structure was indexed). Note that the
* runtime does not use nor take advantage of the returns of all of these
* methods.
*/
typedef struct {
/** A C-string naming the type, for use by the built-in `type` function. */
char *tname;
/** Called with [this, rhs] to perform binary addition ("+"). */
sol_cfunc_t add;
/** Called with [this, rhs] to perform binary subtraction ("-"). */
sol_cfunc_t sub;
/** Called with [this, rhs] to perform binary multiplication ("*"). */
sol_cfunc_t mul;
/** Called with [this, rhs] to perform binary division ("/"). */
sol_cfunc_t div;
/** Called with [this, rhs] to perform binary modulus ("%"). */
sol_cfunc_t mod;
/** Called with [this, rhs] to perform binary exponentiation ("**"). */
sol_cfunc_t pow;
/** Called with [this, rhs] to perform binary bitwise AND ("&") */
sol_cfunc_t band;
/** Called with [this, rhs] to perform binary bitwise OR ("|") */
sol_cfunc_t bor;
/** Called with [this, rhs] to perform binary bitwise XOR ("^") */
sol_cfunc_t bxor;
/** Called with [this, rhs] to perform binary bitwise left shift ("<<") */
sol_cfunc_t blsh;
/** Called with [this, rhs] to perform binary bitwise right shift (">>") */
sol_cfunc_t brsh;
/** Called with [this] to perform bitwise not ("~") */
sol_cfunc_t bnot;
/** 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) */
sol_cfunc_t cmp;
/** Called with [this, arg1, arg2, ...] to perform a call (as "this(arg1, arg2, ...)") */
sol_cfunc_t call;
/** Called with [this, index] to perform an index like "this[index]" or "this.index" (in the latter, index will be a string object) */
sol_cfunc_t index;
/** Called with [this, index, value] to perform a setindex (like "this[index] = value" or "this.index = value" for index being a string object) */
sol_cfunc_t setindex;
/** Called with [this] to perform a length predicate (like "#this") */
sol_cfunc_t len;
/** Called with [this] to return a function object (or cfunction object) that will iterate over "this" (see the iterator protocol for more details) */
sol_cfunc_t iter;
/** Called with [this] to cast "this" to an integer object. This may raise an error, which should be checked. */
sol_cfunc_t toint;
/** Called with [this] to cast "this" to a float object. This may raise an error, which should be checked. */
sol_cfunc_t tofloat;
/** 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. */
sol_cfunc_t tostring;
/** 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. */
sol_cfunc_t repr;
/** 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. */
sol_cfunc_t init;
/** 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. */
sol_cfunc_t free;
} sol_ops_t;
/** Object types known to Sol.
*
* This is rarely checked and generally only used where necessary, as there is
* no way to extend this list naturally for an extension developer.
*
* For each of these types, there is almost certainly a test macro for it.
*/
typedef enum {
/** The singlet type--the type of None, as well as StopIteration and OutOfMemory. It is also the "default" type. */
SOL_SINGLET,
/** The integer type, implemented as a long. */
SOL_INTEGER,
/** The floating point type, implemented as a double. */
SOL_FLOAT,
/** The string type, implemented as a C string. */
SOL_STRING,
/** The list type, implemented as a DSL sequence of object pointers. */
SOL_LIST,
/** The map type, implemented as a DSL sequence of MCELL object pointers arranged as an associative array.. */
SOL_MAP,
/** The mcell type, a simple key-value pair only to be found in a map. */
SOL_MCELL,
/** The function type, the type of all user-defined functions in Sol. */
SOL_FUNCTION,
/** The cfunction type, the type of objects wrapping a `sol_cfunc_t`. */
SOL_CFUNCTION,
/** The statement type, the type of objects wrapping a `stmt_node`. */
SOL_STMT,
/** The expression type, the type of objects wrapping an `expr_node`. */
SOL_EXPR,
/** The buffer type, a type designed to access arbitrary memory. */
SOL_BUFFER,
/** The dylib type, the type of dynamically-loaded shared libraries. */
SOL_DYLIB,
/** The dysym type, the type of symbols resolved in dylib objects. */
SOL_DYSYM,
/** The stream type, the type wrapping FILE *. */
SOL_STREAM,
/** The cdata type, the type used for extension by various modules. */
SOL_CDATA
} sol_objtype_t;
/** Buffer types.
*
* These types indicate what a buffer or subsection of a buffer may refer to.
*/
typedef enum {
/** The region is typeless. This is the default, and prohibits access unless it is retyped. */
BUF_NONE,
/** The region contains an 8-bit signed integer. */
BUF_INT8,
/** The region contains a 16-bit signed integer. */
BUF_INT16,
/** The region contains a 32-bit signed integer. */
BUF_INT32,
/** The region contains a 64-bit signed integer. */
BUF_INT64,
/** The region contains an 8-bit unsigned integer. */
BUF_UINT8,
/** The region contains a 16-bit unsigned integer. */
BUF_UINT16,
/** The region contains a 32-bit unsigned integer. */
BUF_UINT32,
/** The region contains a 64-bit unsigned integer. */
BUF_UINT64,
/** The region contains an ASCII character. */
BUF_CHAR,
/** The region contains exactly one addressable unit. */
BUF_BYTE,
/** The region contains a platform-sized signed integer. */
BUF_INT,
/** The region contains a platform-sized unsigned integer. */
BUF_UINT,
/** The region contains a platform-sized signed long integer. */
BUF_LONG,
/** The region contains a platform-sized unsigned long integer. */
BUF_ULONG,
/** The region contains a platform single-precision floating point. */
BUF_FLOAT,
/** The region contains a platform double-precision floating point. */
BUF_DOUBLE,
/** The region contains a pointer to a NUL-terminated C string. */
BUF_CSTR,
/** The region contains a generic pointer (which will instantiate another buffer). */
BUF_PTR
} sol_buftype_t;
/** Ownership types.
*
* These functions determine what happens to the memory region aliased by a
* buffer when that object is freed or copied.
*/
typedef enum {
/** Nothing happens; the object is freed or copied normally. */
OWN_NONE,
/** The libc `free` function is called on the buffer. Nothing happens when a new buffer is made to alias it. */
OWN_FREE,
/** The movefunc and freefunc are respectively consulted. */
OWN_CALLF
} sol_owntype_t;
/**
* Transput modes.
*
* These constants are defined (by the same name) on the `io` module as valid bits for the second argument to `io.open`.
*/
typedef enum {
/** Permit reading. If this is not set, any attempt to read will raise an error. */
MODE_READ = 1,
/** Permit writing. If this is not set, any attempt to write will raise an error. */
MODE_WRITE = 2,
/** 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. */
MODE_APPEND = 4,
/** When opened for writing, truncate the file to zero size. Previous contents are lost. */
MODE_TRUNCATE = 8,
/** Prepare the file for reading or writing binary data as opposed to text. */
MODE_BINARY = 16
} sol_modes_t;
/** Buffer freeing function.
*
* This is called with the buffer region and given size when a buffer object is
* freed (from state.BufferOps.free) when the `sol_owntype_t` is set to
* `OWN_CALLF`. It should do whatever is needed to release this one alias of
* memory. Note that care should be taken if multiple buffer objects alias the
* same region.
*/
typedef void (*sol_freefunc_t)(void *, size_t);
/** Buffer moving function.
*
* This is called with the buffer region and given size when a buffer object is
* somehow copied (usually by dereferencing a `BUF_PTR`). It should return the
* region that the new buffer object should refer to. The size is assumed to
* not change.
*/
typedef void *(*sol_movefunc_t)(void *, size_t);
/** Object structure.
*
* This structure defines the interface of every Sol object. Just as well (and
* as an implementation detail), it contains the operative members of every
* built-in type.
*/
typedef struct sol_tag_object_t {
/** The type of this object. */
sol_objtype_t type;
/** The number of living references to this object, increased by `sol_incref` and decreased by `sol_obj_free`. */
int refcnt;
/** The ops structure defining the behavior of this object under certain operations (more or less, its behavioral "type"). */
sol_ops_t *ops;
union {
/** For `SOL_INTEGER`, the value of the integer. */
long ival;
/** For `SOL_FLOAT`, the value of the floating point number. */
double fval;
/** For `SOL_STRING`, the C string pointer. For `SOL_SINGLET`, the name of this singlet. */
char *str;
/** For `SOL_LIST` and `SOL_MAP`, the DSL sequence that contains the items or pairs. */
dsl_seq *seq;
struct {
/** For `SOL_MCELL`, the key of the pair. */
struct sol_tag_object_t *key;
/** For `SOL_MCELL`, the value of the pair. */
struct sol_tag_object_t *val;
};
struct {
/** For `SOL_FUNCTION`, the `stmt_node` pointer representing the function's body. */
void *func; // Actually a stmt_node *
/** For `SOL_FUNCTION`, the `identlist_node` pointer representing the list of the functions argument names. */
void *args; // Actually an identlist_node *
/** For `SOL_FUNCTION`, a map representing the closure (initial scope, updated on exit) of the function. */
struct sol_tag_object_t *closure;
/** For `SOL_FUNCTION`, a map of data defined by the user on this function object. */
struct sol_tag_object_t *udata;
/** For `SOL_FUNCTION`, the name of the function if it was not declared anonymously (otherwise NULL). */
char *fname;
};
/** For `SOL_CFUNCTION`, the C function pointer. */
sol_cfunc_t cfunc;
/** For `SOL_STMT` and `SOL_EXPR`, the `stmt_node` or `expr_node` pointer, respectively. */
void *node;
struct {
/** For `SOL_BUFFER`, the memory region referred to by this buffer. */
void *buffer;
/** For `SOL_BUFFER`, the size of this memory region. Negative values indicate no or unknown size. */
ssize_t sz;
/** For `SOL_BUFFER`, the ownership type of this buffer's region. */
sol_owntype_t own;
/** For `SOL_BUFFER`, the freeing function if own == `OWN_CALLF` */
sol_freefunc_t freef;
/** For `SOL_BUFFER`, the moving function if own == `OWN_CALLF` */
sol_movefunc_t movef;
};
/** For `SOL_DYLIB`, the handle as returned by `dlopen`. */
void *dlhandle;
struct {
/** For `SOL_DYSYM`, the symbol as resolved by `dlsym`. */
void *dlsym;
/** 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. */
dsl_seq *argtp;
/** 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. */
sol_buftype_t rettp;
};
struct {
/** For `SOL_STREAM`, the actual file object. */
FILE *stream;
/** For `SOL_STREAM`, the modes for which this stream is open. */
sol_modes_t modes;
};
/** For `SOL_CDATA`, an arbitrary, user-defined pointer. */
void *cdata;
};
} sol_object_t;
/** State flags.
*
* These flags get set during execution and indicate an altered state of
* interpretation (other than the altered state of interpretation that comes
* about due to an error propagation).
*/
typedef enum {SF_NORMAL, SF_BREAKING, SF_CONTINUING} sol_state_flag_t;
typedef struct sol_tag_state_t {

불러오는 중...
취소
저장