/* * Copyright Redis Ltd. 2016 - present * Licensed under your choice of the Redis Source Available License 2.0 (RSALv2) or * the Server Side Public License v1 (SSPLv1). */ #ifndef RMUTIL_CMDPARSE_ #define RMUTIL_CMDPARSE_ #include "redismodule.h" #include #define CMDPARSE_OK 0 #define CMDPARSE_ERR 1 typedef enum { CmdArg_Integer, CmdArg_Double, CmdArg_String, CmdArg_Array, CmdArg_Object, CmdArg_Flag, // this is a special type returned from type checks when the arg is null, and not really used CmdArg_NullPtr, } CmdArgType; struct CmdArg; typedef struct { char *str; size_t len; } CmdString; #define CMD_STRING(s) ((CmdString){.str = s, .len = strlen(s)}) int CmdString_CaseEquals(CmdString *str, const char *other); typedef struct { const char *k; struct CmdArg *v; } CmdKeyValue; typedef struct { size_t len; size_t cap; CmdKeyValue *entries; } CmdObject; typedef struct { size_t len; size_t cap; struct CmdArg **args; } CmdArray; // Variant value union typedef struct CmdArg { union { // numeric value double d; int64_t i; // boolean flag int b; // string value CmdString s; // array value CmdArray a; CmdObject obj; }; CmdArgType type; } CmdArg; void CmdArg_Free(CmdArg *arg); /* General signature for a command validator func. You can inject your own */ typedef int (*CmdArgValidatorFunc)(CmdArg *arg, void *ctx); /************************************************************************************************************************* * * Command Schema Definition Objects *************************************************************************************************************************/ /* Single typed argument in a schema. Can have the following type chars: * * - s: will be parsed as a string * - l: Will be parsed as a long integer * - d: Will be parsed as a double */ typedef struct { char type; const char *name; } CmdSchemaArg; /* dummy struct for flags - they don't need anything */ typedef struct { } CmdSchemaFlag; /* Command schema option - represents a multiple choice, mutually exclusive options */ typedef struct { /* The number of options */ int num; /* The option strings */ const char **opts; } CmdSchemaOption; /* Schema tuple - a fixed length array with known types */ typedef struct { /* Format string, containing s, l or d. The length of the tuple is the length of the format string */ const char *fmt; /* Element names - for help prints only */ const char **names; } CmdSchemaTuple; /* Schema vector - multiple elements (known only at run time by the first argument) with a single * type, either l, s or d */ typedef struct { char type; } CmdSchemaVector; typedef struct { const char *fmt; } CmdSchemaVariadic; /* Command schema element types */ typedef enum { CmdSchemaElement_Arg, CmdSchemaElement_Tuple, CmdSchemaElement_Vector, CmdSchemaElement_Flag, CmdSchemaElement_Option, CmdSchemaElement_Variadic, } CmdSchemaElementType; /* A single element in a command schema. */ typedef struct { union { CmdSchemaArg arg; CmdSchemaTuple tup; CmdSchemaVector vec; CmdSchemaFlag flag; CmdSchemaOption opt; CmdSchemaVariadic var; }; CmdSchemaElementType type; CmdArgValidatorFunc validator; void *validatorCtx; } CmdSchemaElement; /* Command schema node flags */ typedef enum { /* Required argument */ CmdSchema_Required = 0x01, /* Optional argument */ CmdSchema_Optional = 0x02, /* Repeating argument - my have more than one instance per schema */ CmdSchema_Repeating = 0x04, } CmdSchemaFlags; /* Schema node type. */ typedef enum { /* A schema or sub-schema object. This is the root of the command schema */ CmdSchemaNode_Schema, /* A position argument - it can only be parsed once, at a specific position */ CmdSchemaNode_PositionalArg, /* A named argument. It can appear anywhere, after the last positional argument */ CmdSchemaNode_NamedArg, /* A flag - an argument that may or may not appear, setting a boolean value to 0 or 1 */ CmdSchemaNode_Flag, } CmdSchemaNodeType; /* Schema nodes. Each node contains an element (apart from schema nodes). The node has its name * and flags, and the element defines how to parse the element this node contains */ typedef struct CmdSchemaNode { /* The value element conatined in this node. NULL for schema/sub-schema nodes */ CmdSchemaElement *val; /* Flags - required / optional and repeatable */ CmdSchemaFlags flags; /* The node type */ CmdSchemaNodeType type; /* The node name. Even positional nodes have names so we can refer to them */ const char *name; /* Optional help string to extract documentation */ const char *help; /* If this is a schema node, it may have edge nodes - other nodes that may be traversed from it. */ struct CmdSchemaNode **edges; /* The number of edges */ int size; } CmdSchemaNode; /* Create a new named schema with a given help message (can be left NULL) */ CmdSchemaNode *NewSchema(const char *name, const char *help); void CmdSchemaNode_Free(CmdSchemaNode *n); /* Add a named parameter to a schema or sub-schema, with a given name, and an element which can be a * value, tuple, vector or option. Flags can indicate unique/repeating, or optional arg */ int CmdSchema_AddNamed(CmdSchemaNode *s, const char *param, CmdSchemaElement *elem, CmdSchemaFlags flags); /* Add a positional parameter to a schema or sub-schema, with a given name, and an element which can * be a value, tuple, vector or option. Flags can indicate unique/repeating, or optional arg. A * positional argument has a name so it can referenced when accessing the parsed document */ int CmdSchema_AddPostional(CmdSchemaNode *s, const char *param, CmdSchemaElement *elem, CmdSchemaFlags flags); /* Add named with a help message */ int CmdSchema_AddNamedWithHelp(CmdSchemaNode *s, const char *param, CmdSchemaElement *elem, CmdSchemaFlags flags, const char *help); /* Add a positional with a help message */ int CmdSchema_AddPostionalWithHelp(CmdSchemaNode *s, const char *param, CmdSchemaElement *elem, CmdSchemaFlags flags, const char *help); /* Create a new tuple schema element to be added as a named/positional. The format string can be * composed of the letters d (double), l (long) or s (string). The expected length of the tuple is * the length of the format string */ CmdSchemaElement *CmdSchema_NewTuple(const char *fmt, const char **names); /* Wrap a schema element with a validator func. Only one validator per element allowed */ CmdSchemaElement *CmdSchema_Validate(CmdSchemaElement *e, CmdArgValidatorFunc f, void *privdata); /* Create a new single argument (string, long or double) to be added as a named or positional. The * type char can be d (double), l (long) or s (string) */ CmdSchemaElement *CmdSchema_NewArg(const char type); /* Samve as CmdSchema_NewArg, but with a name annotation for help messages */ CmdSchemaElement *CmdSchema_NewArgAnnotated(const char type, const char *name); /* Create a new vector to be added as a named or positional argument. A vector is a list of values * of the same type that starts with a length specifier (i.e. 3 foo bar baz) */ CmdSchemaElement *CmdSchema_NewVector(const char type); /* Add a variadic vector. This can only be added at the end of the command */ CmdSchemaElement *CmdSchema_NewVariadicVector(const char *fmt); /* Create a new option between mutually exclusive string values, to be added as a named/positional */ CmdSchemaElement *CmdSchema_NewOption(int num, const char **opts); /* Add a flag - which is a boolean optional value. If the flag exists in the arguments, the value is * set to 1, else to 0 */ int CmdSchema_AddFlag(CmdSchemaNode *parent, const char *name); /* Add a flag with a help message */ int CmdSchema_AddFlagWithHelp(CmdSchemaNode *parent, const char *name, const char *help); /* Add a sub schema - that is a complex schema with arguments that can reside under another command */ CmdSchemaNode *CmdSchema_AddSubSchema(CmdSchemaNode *parent, const char *param, int flags, const char *help); void CmdSchema_Print(CmdSchemaNode *n); void CmdArg_Print(CmdArg *n, int depth); /* Parse a list of arguments using a command schema. If a parsing error occurs, CMDPARSE_ERR is * returned and an error string is put into err. Note that it is a newly allocated string that needs * to be freed. If strict is 1, we make sure that all arguments have been consumed. Strict set to 0 * means we can do partial parsing */ int CmdParser_ParseCmd(CmdSchemaNode *schema, CmdArg **arg, CmdString *argv, int argc, char **err, int strict); /* Parse a list of redis module arguments using a command schema. If a parsing error occurs, * CMDPARSE_ERR is returned and an error string is put into err. Note that err is a newly allocated * string that needs to be freed. If strict is 1, we make sure that all arguments have been * consumed. Strict set to 0 means we can do partial parsing */ int CmdParser_ParseRedisModuleCmd(CmdSchemaNode *schema, CmdArg **cmd, RedisModuleString **argv, int argc, char **err, int strict); /* Convert a variadic list of strings to an array of command strings. Does not do extra * reallocations, so only the array itself needs to be freed */ CmdString *CmdParser_NewArgListV(size_t size, ...); /* Convert an array of C NULL terminated strings to an arg list. Does not do extra * reallocations, so only the array itself needs to be freed */ CmdString *CmdParser_NewArgListC(const char **args, size_t size); typedef struct { CmdArg *arg; const char *key; size_t pos; } CmdArgIterator; /* Return the number of children for arrays and objects, 0 for all others */ size_t CmdArg_NumChildren(CmdArg *arg); /* count the number of children of an object that correspond to a specific key */ size_t CmdArg_Count(CmdArg *arg, const char *key); /* Create an iterator of all children of an object node, named as key. If none exist, the first call * to Next() will return NULL */ CmdArgIterator CmdArg_Select(CmdArg *arg, const char *key); /* Create an iterator of all the children of an objet or array node */ CmdArgIterator CmdArg_Children(CmdArg *arg); /* Parse an argument as a double. Argument may already be a double or an int in which case it gets * returned, or a string in which case we try to parse it. Returns 1 if the conversion/parsing was * successful, 0 if not */ int CmdArg_ParseDouble(CmdArg *arg, double *d); /* return 1 if a flag with a given name exists in parent and is set to true */ int CmdArg_GetFlag(CmdArg *parent, const char *flag); /* Parse an argument as a integer. Argument may already be a int or a double in which case it * gets returned, or a string in which case we try to parse it. Returns 1 if the * conversion/parsing was successful, 0 if not */ int CmdArg_ParseInt(CmdArg *arg, int64_t *i); #define CMDARG_TYPE(arg) (arg ? arg->type : CmdArg_NullPtr) #define CMDARRAY_ELEMENT(arr, i) (arr->args[i]) #define CMDARRAY_LENGTH(arr) (arr->len) #define CMDARG_INT(a) (a->i) #define CMDARG_DOUBLE(a) (a->d) #define CMDARG_STR(a) (a->s) #define CMDARG_ORNULL(a, expr) (a ? expr(a) : NULL) #define CMDARG_STRLEN(a) (a->s.len) #define CMDARG_STRPTR(a) (a->s.str) #define CMDARG_STRLEN(a) (a->s.len) #define CMDARG_ARR(arr) (arr->a) #define CMDARG_OBJ(a) (a->obj) #define CMDARG_OBJLEN(arg) (arg->obj.len) #define CMDARG_OBJCHILD(arg, n) (&arg->obj.entries[n]) #define CMDARG_BOOL(a) (a->b) #define CMDARG_ARRLEN(arg) (arg->a.len) #define CMDARG_ARRELEM(arg, i) (arg->a.args[i]) int CmdArg_ArrayAssign(CmdArray *arg, const char *fmt, ...); /* Advane an iterator. Return NULL if the no objects can be read from the iterator */ CmdArg *CmdArgIterator_Next(CmdArgIterator *it, const char **key); /* Return the fist child of an object node that is named as key, NULL if this is not an object or no * such child exists */ CmdArg *CmdArg_FirstOf(CmdArg *, const char *key); /* Convenience macro for iterating all children of an object arg with a given expression - either a * function call or a code block. arg is the command arg we're iterating, key is the selection. The * resulting argument in the loop is always called "result" */ #define CMD_FOREACH_SELECT(arg, key, blk) \ { \ CmdArgIterator it = CmdArg_Select(arg, key); \ CmdArg *result = NULL; \ while (NULL != (result = CmdArgIterator_Next(&it, NULL))) { \ blk; \ } \ } #endif