Show misc_parse.h syntax highlighted
/*
*
* Copyright (c) 2003 The Regents of the University of California. All
* rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Neither the name of the University nor the names of its
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS''
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
*/
/**
* \file misc_parse.h Simple parser code for simple tasks
*/
#ifndef __MISC_PARSE_H__
#define __MISC_PARSE_H__
/**
* parser_state_t:
* @input:
* @input_len:
*
*
*/
typedef struct parser_state {
char *input; /**< input string */
int input_len;
/* options */
char *pair_delimit_set;
char *pair_assign_set;
int skip_whitespace:1;
char escape_char;
/* latest result */
char *key;
char *value;
uint8_t pair_delimit;
uint8_t pair_assign;
/* internal variables */
int consumed;
char *_input;
} parser_state_t;
#define MISC_PARSE_COLON_SCHEME 1
#define MISC_PARSE_COMMA_SCHEME 2
#define MISC_PARSE_LF_SCHEME 3
#define MISC_PARSE_AMPERSAND_SCHEME 4
#define MISC_PARSE_SEMICOLON_SCHEME 5
#define MISC_PARSE_SEMICOLON_KEY_SCHEME 6
/** \note */
/**
* misc_parse_init:
* @input: input string to the parser
* @scheme: one of the available parser schemes
*
* Initialize the parser with the input string and a scheme.
*
* Different schemes are available via _init().
* #COLON_SCHEME is k=v:k=v:k=v...
* #SEMICOLON_SCHEME is k=v;k=v;k=v...
* #COMMA_SCHEME is k=v,k=v,k=v...
* #COMMA_PAREN_SCHEME is (k=v,k=v,k=v...)
* #LF_SCHEME is k\nk\n...
* #SEMICOLON_KEY_SCHEME is k;k;k...
*
* You can use misc_parse_init() and misc_parse_cleanup() to create a
* malloc'd state struct or, you can statically alloc (and use reset
* if needed)
*
* Returns: parser state to use with the reset of the misc_parse
* functions
*/
parser_state_t * misc_parse_init(char *input, int scheme);
/**
* misc_parse_cleanup:
* @state: parser state for context
*
* Resets the state and frees @state
*/
void misc_parse_cleanup(parser_state_t *state);
/**
* misc_parse_test_key:
* @state: parser state for context
* @key: string to compare to current key in the key value pair
*
* strcasecmps @key and the key from the current key value pair and
* returns true if key matches
*
* Returns: 1 if there is a match, 0 otherwise
*/
int misc_parse_test_key(parser_state_t *state, char *key);
/**
* misc_parse_next_kvp:
* @state: parser state for context
*
* misc_parse_next_kvp is a simple parser for small tasks like command
* devices and the like. If you need a complicated parser then lex
* and yacc are for you -- but this one will cover the "trivial" cases
* that are nonetheless a pain to implement.
*
* Usage:
* Pass in a filled parser_state struct.
* - input: the input string (must be null-term)
* - input_len: (optional) enables the parser to handle strings with \0's
* - pair_delimit_set: (optional) specifies the set of delimiters of key
* value pairs. if not set, the default is ":\n". nulls are always
* pair delimiters.
* - pair_assign_set: (optional) specifies the set of assignment chars.
* if not set, the default is "=".
* - skip_whitespace: (optional) requests whitespace to be ignored
* - escape_char: (optional) defines char for escaping delimiters, default '\'
*
* The parse function returns the pair delimiter as a return value, or
* -1 if the end of the string was reached.
*
* Typical usage is to initialize the state structure and then call
* the function in a loop until -1 is returned.
*
* Different schemes are available via misc_parse_init().
* #COLON_SCHEME is k=v:k=v:k=v...
* #SEMICOLON_SCHEME is k=v;k=v;k=v...
* #COMMA_SCHEME is k=v,k=v,k=v...
* #COMMA_PAREN_SCHEME is (k=v,k=v,k=v...)
* #LF_SCHEME is k\nk\n...
* #SEMICOLON_KEY_SCHEME is k;k;k...
*
* Warning: misc_parse_kvp allocates memory. This memory is
* automatically freed if the parse completes, or in _cleanup(), but
* must be freed via a call to misc_parse_reset() if you are using a
* statically allocated parse structure and the parse does not run to
* completion.
*
* Returns: -1 when complete, >= 0 otherwise
*/
int misc_parse_next_kvp(parser_state_t *state);
/**
* misc_parse_dump_curr_to_buf:
* @buf: #buf_t to dump the current key value pair into
* @state: current parser state for context
*
* Dumps the current key, the assignment character, the value, and the
* pair delimiter to @buf
*/
void misc_parse_dump_curr_to_buf(buf_t *buf, parser_state_t *state);
/**
* misc_parse_n_args:
* @state: current parser state for context
* @keys: array of strings that gets filled in with the next @n keys
* @args: array of strings that gets filled in with the next @n values
* @n: the number of key value pairs to fill into @keys and @args
*
* Attempts to fill in @keys with the next @n keys and @args with the
* next @n values.
*
* Returns: 0 on success, -1 if there are not @n args, -1 if there are
* string remaining
*/
int misc_parse_n_args(parser_state_t *state, char **keys, char **args, int n);
/**
* misc_free_n_args:
* @args: array to free args of
* @n: number of args to free
*
* Iterates from args[0] to args[@n], calling free() on each args[i].
*/
void misc_free_n_args(char **args, int n);
/** \brief returns the current original input data, starting at the current value */
/**
* main_parse_get_raw_value:
* @state: current parser state for context
* @remain: if not NULL, gets set to the size of the value
*
* This will return a pointer to the value in the actual input string
* and fills in @remain with the size of the remaining input
*
* Returns: pointer to actuall value string in input string
*/
char *misc_parse_get_raw_value(parser_state_t *state, int *remain);
/**
* misc_parse_csv_to_vector:
* @str: string in the #MISC_PARSE_COMMA_SCHEME to turn into a vector
*
* Creates a vector of strings, where the strings are all the keys in @str
*
* Returns: a vector containing all the keys in @str
*/
char **misc_parse_csv_to_vector(char *str);
/**
* misc_parse_rest:
* @state: current parser state for context
*
* Reset parser to beginning of string and clears existing allocated
* memory. If the parse is aborted before completion, you must1 call
* reset() to clean up allocated memory! This is not needed if the
* parse runs to completion.
*/
void misc_parse_reset(parser_state_t *state);
/**
* misc_parse_unescape:
* @str: string to remove escape character from
* @esc: the escpae character to remove
*
* Removes escape character @esc from @str
*/
void misc_parse_unescape(char *str, char esc);
/**
* misc_usage_uniquify:
* @in: #buf_t in MISC_PARSE_LF_SCHEME to remove duplicates from
* @out: #buf_t is the output buffer which has the duplicates removed
* (user must initialize this #buf_t)
*
* Removes the duplicate keys from @in, which is in
* MISC_PARSE_LF_SCHEME. Keeps only the first line without preceding
* whitespace. Records the keeps only the first entry of each string
* e.g. entry:
*/
void misc_usage_uniquify(buf_t *in, buf_t *out);
/**
* misc_parse_string:
* @str: pointer to the character string with all the values and separators
* @esc: the character separator
* @val: pointer to the allocated memory pointer where the library
* copy the value of the string processed. It is optional. NOTE: it
* is responsability of the caller to deallocate the memory.
*
* This is a simple string parser for values separated with a
* character separator.
*
* It will take the first value that is not a separator and allocate
* memory for it. If a 'val' argument is provided, it will point to
* the allocated pointer with the value. The value returned is the
* pointer to the string with the value read removed.
*
* If @val is supplied, it is the CALLER responsability to deallocate
* the memory.
*
* Returns: pointer to the string with the first value parsed removed
* or a null string if empty
*/
char * misc_parse_string(char *str, char esc, char **val);
/**
* misc_num_args:
* @str: string to count the number of args in
* @esc: character which separates the args in @str
*
* Counts the number of arguments in @str separated by @esc
*
* Returns: the number of arguments in @str separated by @esc
*/
int misc_num_args(char *str, char esc);
#endif
See more files for this project here