[RFC PATCH 14/28] cli: lil: Document structures
Sean Anderson
seanga2 at gmail.com
Thu Jul 1 08:15:57 CEST 2021
This documents the major structures of LIL.
Signed-off-by: Sean Anderson <seanga2 at gmail.com>
---
common/cli_lil.c | 100 ++++++++++++++++++++++++++++++++++++++++++++++
include/cli_lil.h | 57 ++++++++++++++++++++++++++
2 files changed, 157 insertions(+)
diff --git a/common/cli_lil.c b/common/cli_lil.c
index 66ee62bf33..7fbae1964a 100644
--- a/common/cli_lil.c
+++ b/common/cli_lil.c
@@ -29,20 +29,44 @@
#define HASHMAP_CELLS 256
#define HASHMAP_CELLMASK 0xFF
+/**
+ * struct hashentry - An entry in a cell
+ * @k: The key
+ * @v: The value
+ */
struct hashentry {
char *k;
void *v;
};
+/**
+ * struct hashcell - A list of entries with the same hash
+ * @e: An array of entries
+ * @c: The capacity of this cell
+ */
struct hashcell {
struct hashentry *e;
size_t c;
};
+/**
+ * struct hashmap - An array-based hash map
+ * @cell: An array of cells
+ *
+ * This hash map uses separate chaining with an array for each cell. We cannot
+ * use the existing hash map functions (hsearch_r et al.) because they assume
+ * that the value is a string.
+ */
struct hashmap {
struct hashcell cell[HASHMAP_CELLS];
};
+/**
+ * struct lil_value - A string and its length
+ * @l: The length of the value.
+ * @c: The capacity of this value (maximum of @l before requiring reallocation).
+ * @d: The contents of the value, as a nul-terminated string.
+ */
struct lil_value {
size_t l;
#ifdef LIL_ENABLE_POOLS
@@ -51,12 +75,34 @@ struct lil_value {
char *d;
};
+/**
+ * struct lil_var - A variable
+ * @n: The name of this variable
+ * @env: The environment containing this variable
+ * @v: The value of this variable
+ */
struct lil_var {
char *n;
struct lil_env *env;
struct lil_value *v;
};
+/**
+ * struct lil_env - A function call's execution environment
+ * @parent: The parent of this environment. This is %NULL for the root
+ * environment.
+ * @func: The currently-executing function
+ * @proc: The name of the currently-executing built-in procedure
+ * @var: A list of the variables in this environment
+ * @vars: The number of variables in @var
+ * @varmap: A hash map mapping variable names to pointers to variables in @var
+ * @retval: The value set by "return" or "result"
+ * @retval_set: Whether @retval has been set
+ * @breakrun: Whether to immediately break out the current run of execution.
+ * This is set by "return"
+ *
+ * Variables are inherited from @parent.
+ */
struct lil_env {
struct lil_env *parent;
struct lil_func *func;
@@ -69,12 +115,28 @@ struct lil_env {
int breakrun;
};
+/**
+ * struct list - A list of values
+ * @v: A list of pointers to &struct lil_value
+ * @c: The number of values in this list
+ * @cap: The space allocated for @v
+ */
struct lil_list {
struct lil_value **v;
size_t c;
size_t cap;
};
+/**
+ * struct lil_func - A function which may be evaluated with a list of arguments
+ * @name: The name of the function
+ * @code: A value containing LIL code to be evaluated
+ * @argnames: The names of variables to assign to the passed-in arguments
+ * @proc: A C function to use to evaluate this function
+ *
+ * @code and @argnames are only used to evaluate the function if @proc is %NULL.
+ * If @argnames is empty, then the arguments are assigned to a variable "args".
+ */
struct lil_func {
char *name;
struct lil_value *code;
@@ -82,6 +144,31 @@ struct lil_func {
lil_func_proc_t proc;
};
+/**
+ * struct lil - The current state of the interpreter
+ * @code: The code which is being interpreted
+ * @rootcode: The top-level code (e.g. the code for the initial call to
+ * lil_parse())
+ * @clen: The length of @code
+ * @head: The first uninterpreted part of this code, as an index of @code
+ * @ignoreeol: Whether to treat newlines as whitespace or command terminators
+ * @cmd: A list of the current commands
+ * @cmds: The number of commands in @cmd
+ * @cmdmap: A hash map mapping command names to pointers to commands in @cmd
+ * @env: The current environment to evaluate commands in
+ * @rootenv: The top-level "root" environment
+ * @downenv: The original environment after a call to "topeval" or "upeval"
+ * @empty: An empty value, allocated once
+ * @ERROR_NOERROR: There is no error.
+ * @ERROR_DEFAULT: There was an error.
+ * @ERROR_FIXHEAD: There was an error, but @err_head needs to be fixed.
+ * @ERROR_UNBALANCED: An opening quote or bracket lacks a balancing closing
+ * quote or bracket.
+ * @error: The current error status
+ * @err_head: The offset in @code which caused the @error
+ * @err_msg: An optional string describing the current @error
+ * @parse_depth: The depth of recursive function calls
+ */
struct lil {
const char *code; /* need save on parse */
const char *rootcode;
@@ -101,6 +188,19 @@ struct lil {
size_t parse_depth;
};
+/**
+ * struct expreval - A (mathematical) expression being evaluated
+ * @code: The complete code for this expression
+ * @len: The length of @code
+ * @head: The first unevaluated part of this expression, as an index of @code
+ * @ival: The integer value of this expression
+ * @EERR_NO_ERROR: There is no error
+ * @EERR_SYNTAX_ERROR: Syntax error. For now this is just mismatched
+ * parentheses.
+ * @EERR_DIVISION_BY_ZERO: Attempted division by zero
+ * @EERR_INVALID_EXPRESSION: A non-number was present
+ * @error: The error of this expression (if any)
+ */
struct expreval {
const char *code;
size_t len, head;
diff --git a/include/cli_lil.h b/include/cli_lil.h
index cdaa79fd15..91e79c12f4 100644
--- a/include/cli_lil.h
+++ b/include/cli_lil.h
@@ -13,10 +13,35 @@
#define LIL_VERSION_STRING "0.1"
+/**
+ * enum lil_setvar - The strategy to use when creating new variables
+ */
enum lil_setvar {
+ /**
+ * @LIL_SETVAR_GLOBAL: Set in the root environment
+ */
LIL_SETVAR_GLOBAL = 0,
+ /**
+ * @LIL_SETVAR_LOCAL: Set, starting with the local environment
+ *
+ * Search for a variable. If one is found, overwrite it. Otherwise,
+ * create a new variable in the local environment.
+ */
LIL_SETVAR_LOCAL,
+ /**
+ * @LIL_SETVAR_LOCAL_NEW: Create in the local environment
+ *
+ * Create a new variable in the local environment. This never overrides
+ * existing variables (even if one exists in the local environment).
+ */
LIL_SETVAR_LOCAL_NEW,
+ /**
+ * @LIL_SETVAR_LOCAL_ONLY: Set in a local environment only
+ *
+ * Search for a variable in the local environment. If one is found,
+ * overwrite it. Otherwise, create a new variable in the local
+ * environment.
+ */
LIL_SETVAR_LOCAL_ONLY,
};
@@ -32,9 +57,41 @@ struct lil;
typedef struct lil_value *(*lil_func_proc_t)(struct lil *lil, size_t argc,
struct lil_value **argv);
+/**
+ * struct lil_callbacks - Functions called by LIL to allow overriding behavior
+ */
struct lil_callbacks {
+ /**
+ * @setvar: Called when a non-existent global variable is assigned
+ *
+ * @lil: The LIL interpreter
+ *
+ * @name: The name of the variable
+ *
+ * @value: A pointer to the value which would be assigned. This may be
+ * modified to assign a different value.
+ *
+ * This can be used to override or cancel the assignment of a variable
+ *
+ * @Return: A negative value to prevent the assignment, %0 to assign the
+ * original value, or a positive value to assign @value.
+ */
int (*setvar)(struct lil *lil, const char *name,
struct lil_value **value);
+ /**
+ * @getvar: Called when a global variable is read
+ *
+ * @lil: The LIL interpreter
+ *
+ * @name The name of the variable
+ *
+ * @value: The pointer to the value which would be read. This may be
+ * modified to read a different value.
+ *
+ * @Return: A non-zero value to read the value pointed to by @value
+ * instead of the original value, or anything else to use the
+ * original value
+ */
int (*getvar)(struct lil *lil, const char *name,
struct lil_value **value);
};
--
2.32.0
More information about the U-Boot
mailing list