diff options
Diffstat (limited to 'src/ls.h')
| -rw-r--r-- | src/ls.h | 42 |
1 files changed, 23 insertions, 19 deletions
@@ -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. |