/*
**  VAR - OSSP variable expression library.
**  Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
**  Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/)
**
**  This file is part of OSSP VAR, an extensible data serialization
**  library which can be found at http://www.ossp.org/pkg/var/.
**
**  Permission to use, copy, modify, and distribute this software for
**  any purpose with or without fee is hereby granted, provided that
**  the above copyright notice and this permission notice appear in all
**  copies.
**
**  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED 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 AUTHORS AND COPYRIGHT HOLDERS AND THEIR
**  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.
**
**  var.h: VAR library API
*/

#ifndef __VAR_H__
#define __VAR_H__

#include <stdlib.h>

/* Error codes returned by the varexp library. */

typedef enum {
    VAR_ERR_CALLBACK = -64,
    VAR_ERR_INCOMPLETE_QUOTED_PAIR = -36,
    VAR_ERR_INVALID_ARGUMENT = -35,
    VAR_ERR_SUBMATCH_OUT_OF_RANGE = -34,
    VAR_ERR_UNKNOWN_QUOTED_PAIR_IN_REPLACE = -33,
    VAR_ERR_EMPTY_PADDING_FILL_STRING = -32,
    VAR_ERR_MISSING_PADDING_WIDTH = -31,
    VAR_ERR_MALFORMATTED_PADDING = -30,
    VAR_ERR_INCORRECT_TRANSPOSE_CLASS_SPEC = -29,
    VAR_ERR_EMPTY_TRANSPOSE_CLASS = -28,
    VAR_ERR_TRANSPOSE_CLASSES_MISMATCH = -27,
    VAR_ERR_MALFORMATTED_TRANSPOSE = -26,
    VAR_ERR_OFFSET_LOGIC = -25,
    VAR_ERR_OFFSET_OUT_OF_BOUNDS = -24,
    VAR_ERR_RANGE_OUT_OF_BOUNDS = -23,
    VAR_ERR_INVALID_OFFSET_DELIMITER = -22,
    VAR_ERR_MISSING_START_OFFSET = -21,
    VAR_ERR_EMPTY_SEARCH_STRING = -20,
    VAR_ERR_MISSING_PARAMETER_IN_COMMAND = -19,
    VAR_ERR_INVALID_REGEX_IN_REPLACE = -18,
    VAR_ERR_UNKNOWN_REPLACE_FLAG = -17,
    VAR_ERR_MALFORMATTED_REPLACE = -16,
    VAR_ERR_UNKNOWN_COMMAND_CHAR = -14,
    VAR_ERR_INPUT_ISNT_TEXT_NOR_VARIABLE = -13,
    VAR_ERR_UNDEFINED_VARIABLE = -12,
    VAR_ERR_INCOMPLETE_VARIABLE_SPEC = -11,
    VAR_ERR_OUT_OF_MEMORY = -10,
    VAR_ERR_INVALID_CONFIGURATION = -9,
    VAR_ERR_INCORRECT_CLASS_SPEC = -8,
    VAR_ERR_INCOMPLETE_GROUPED_HEX = -7,
    VAR_ERR_INCOMPLETE_OCTAL = -6,
    VAR_ERR_INVALID_OCTAL = -5,
    VAR_ERR_OCTAL_TOO_LARGE = -4,
    VAR_ERR_INVALID_HEX = -3,
    VAR_ERR_INCOMPLETE_HEX = -2,
    VAR_ERR_INCOMPLETE_NAMED_CHARACTER = -1,
    VAR_OK = 0
} var_rc_t;

/*
   Expand the following named characters to their binary
   representation:

       \t          tab
       \n          newline
       \r          return
       \033        octal char
       \x1B        hex char
       \x{263a}    wide hex char

  Any other character quoted by a backslash is copied verbatim.
*/

var_rc_t var_unescape(const char *src, size_t len, char *dst,
    int unescape_all);

/*
   The callback will be called by variable_expand(), providing the
   following parameterns:

        context         - passed through from variable_expand()'s
                          parameters
        varname         - pointer to the name of the variable to
                          expand
        name_len        - length of the string starting at varname
        data            - location, where the callback should store
                          the pointer to the contents of the looked-up
                          variable
        data_len        - location, where the callback should store
                          the length of the data
        malloced_buffer - location, where the callback should store
                          either TRUE or FALSE, telling the framework
                          whether the buffer must be free(3)ed.

   The return code is interpreted as follows:
       >0               - OK
        0               - undefined variable
       <0 - error
*/

typedef int (*var_cb_t) (void *context,
    const char *varname, size_t name_len,
    const char **data, size_t * data_len,
    size_t * buffer_size);

/*
   This structure configures the parser's specials. I think, the fields
   are pretty self-explanatory. The only one worth mentioning is
   force_expand, which is a boolean. If set to TRUE, variable_expand()
   will fail with an error if the lookup callback returns "undefined
   variable". If set to FALSE, variable_expand() will copy the
   expression that failed verbatimly to the output so that another pass
   may expand it.

   The comments after each field show the default configuration.
*/

typedef struct {
    char varinit;        /* '$' */
    char startdelim;     /* '{' */
    char enddelim;       /* '}' */
    char escape;         /* '\' */
    char *namechars;     /* 'a-zA-Z0-9_' */
} var_config_t;
extern const var_config_t var_config_default;

/*
   variable_expand() will parse the contents of input for variable
   expressions and expand them using the provided lookup callback. The
   pointer to the resulting buffer is stored in result, its length in
   result_len. The buffer is always terminated by a '\0' byte, which is
   not included in the result_len count. The buffer must be free(3)ed
   by the caller.
*/

var_rc_t var_expand(const char *input, size_t input_len,
    char **result, size_t * result_len,
    var_cb_t lookup, void *lookup_context,
    const var_config_t * config, int force_expand);

#endif /* __VAR_H__ */