aboutsummaryrefslogtreecommitdiff
path: root/src/ls.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/ls.h')
-rw-r--r--src/ls.h42
1 files changed, 23 insertions, 19 deletions
diff --git a/src/ls.h b/src/ls.h
index 4db66e6..38a2b38 100644
--- a/src/ls.h
+++ b/src/ls.h
@@ -24,7 +24,7 @@
// --- PRIVATE DATATYPES -------------------------------------------------------
// --- PUBLIC DATATYPES --------------------------------------------------------
-/// Fetcher. This function accepts a void* context and a byte address, and
+/// Fetcher. This function accepts a void* argument and a byte address, and
/// returns the byte at that location.
///
/// Fetchers not reading out of fast memory (for example, ones reading from a
@@ -34,28 +34,31 @@
/// from ls_error_t. If no more characters are present, return
/// -LS_NO_MORE_PROGRAM, but do not perform cleanup operations --- the parser
/// must be allowed to read off the end.
-typedef int (*ls_fetcher_t)(void * ctx, uint16_t loc);
+typedef int (*ls_fetcher_t)(void * arg, uint16_t loc);
// fw decl
-struct ls_context_s;
+struct ls_s;
-/// Main LS execution context struct.
-typedef struct ls_context_s {
- /// Fetcher to retrieve data. See ls_run().
+/// Main LS execution struct.
+typedef struct ls_s {
+ // --------- begin user-controlled fields ---------
+
+ /// Fetcher to retrieve data. See ls_run(). User-controlled.
ls_fetcher_t fetcher;
- /// Context for fetcher
- void * fetcher_ctx;
+ /// Argument for fetcher. User-controlled.
+ void * fetcher_arg;
/// Line trace hook. If not null, this will be called for each line.
- void (*line_trace_hook)(struct ls_context_s * ctx);
+ /// User-controlled.
+ void (*line_trace_hook)(struct ls_s * ctx);
/// Set true to stop execution on the next line. The interpreter will
/// exit with error LS_STOPPED. Note that LS_STOPPED is also given if
- /// the interpreter encounters the END statement.
+ /// the interpreter encounters the END statement. User-controlled.
bool stop;
- // --------- end items relevant to the user ---------
+ // --------- end user-controlled fields ---------
/// Execution stack.
ls_value_t * callstack;
@@ -84,26 +87,27 @@ typedef struct ls_context_s {
/// Next label cache entry. This rotates so that the oldest entry is
/// always overwritten.
uint8_t label_cache_i;
-} ls_context_t;
+} ls_t;
// --- PUBLIC CONSTANTS --------------------------------------------------------
// --- PUBLIC VARIABLES --------------------------------------------------------
// --- PUBLIC FUNCTIONS --------------------------------------------------------
-/// Execute a script, returning any unhandled errors. The context should first
-/// be initialized by providing a fetcher, assigned to ctx->fetcher and
-/// ctx->fetcher_ctx. All other fields will be managed by ls_run().
+/// Execute a script, returning any unhandled errors. The user-controlled
+/// fields in the ls_t should be initialized first (these are between
+/// begin/end "user-controlled fields", and documented as such in their
+/// doc comments).
///
-/// @param ctx - context, initialized with fetcher
+/// @param self
/// @param pool - an array of ls_value_t to use as the allocation pool
/// @param szpool - number of elements in @a pool
-ls_error_t ls_run(ls_context_t * ctx, ls_value_t * pool, size_t szpool);
+ls_error_t ls_run(ls_t * self, ls_value_t * pool, size_t szpool);
/// Convert a program counter value to a line and column number. This is
/// expensive and should only be called in rare cases (for example, printing
/// out a line number in an error message).
///
-/// @param ctx - context
+/// @param self
/// @param pc - program counter to look up
/// @param[out] line - 1-based line number
/// @param[out] col - 1-based column number
@@ -111,7 +115,7 @@ ls_error_t ls_run(ls_context_t * ctx, ls_value_t * pool, size_t szpool);
/// @retval false - the PC doesn't exist
///
/// If the PC doesn't exist, @a line and @a col are unchanged.
-bool ls_translate_pc(ls_context_t * ctx, ls_addr_t pc, uint16_t * line,
+bool ls_translate_pc(ls_t * self, ls_addr_t pc, uint16_t * line,
uint16_t * col);
/// Print out a ls_value_t. For diagnostics.