application/properties.h

   1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
   3  *
   4  * Copyright 2017 Mike Becker, Olaf Wintermann All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions are met:
   8  *
   9  *   1. Redistributions of source code must retain the above copyright
  10  *      notice, this list of conditions and the following disclaimer.
  11  *
  12  *   2. Redistributions in binary form must reproduce the above copyright
  13  *      notice, this list of conditions and the following disclaimer in the
  14  *      documentation and/or other materials provided with the distribution.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  20  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26  * POSSIBILITY OF SUCH DAMAGE.
  27  */
  28 /**
  29  * @file properties.h
  30  *
  31  * Load / store utilities for properties files.
  32  *
  33  * @author Mike Becker
  34  * @author Olaf Wintermann
  35  */
  36
  37 #ifndef UCX_PROPERTIES_H
  38 #define UCX_PROPERTIES_H
  39
  40 #include <cx/hash_map.h>
  41 #include <cx/string.h>
  42
  43 #include <stdio.h>
  44
  45 #ifdef  __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 /**
  50  * UcxProperties object for parsing properties data.
  51  * Most of the fields are for internal use only. You may configure the
  52  * properties parser, e.g. by changing the used delimiter or specifying
  53  * up to three different characters that shall introduce comments.
  54  */
  55 typedef struct {
  56     /**
  57      * Input buffer (don't set manually).
  58      * Automatically set by calls to ucx_properties_fill().
  59      */
  60     char   *buffer;
  61
  62     /**
  63      * Length of the input buffer (don't set manually).
  64      * Automatically set by calls to ucx_properties_fill().
  65      */
  66     size_t buflen;
  67
  68     /**
  69      * Current buffer position (don't set manually).
  70      * Used by ucx_properties_next().
  71      */
  72     size_t pos;
  73
  74     /**
  75      * Internal temporary buffer (don't set manually).
  76      * Used by ucx_properties_next().
  77      */
  78     char   *tmp;
  79
  80     /**
  81      * Internal temporary buffer length (don't set manually).
  82      * Used by ucx_properties_next().
  83      */
  84     size_t tmplen;
  85
  86     /**
  87      * Internal temporary buffer capacity (don't set manually).
  88      * Used by ucx_properties_next().
  89      */
  90     size_t tmpcap;
  91
  92     /**
  93      * Parser error code.
  94      * This is always 0 on success and a nonzero value on syntax errors.
  95      * The value is set by ucx_properties_next().
  96      */
  97     int    error;
  98
  99     /**
 100      * The delimiter that shall be used.
 101      * This is '=' by default.
 102      */
 103     char   delimiter;
 104
 105     /**
 106      * The first comment character.
 107      * This is '#' by default.
 108      */
 109     char   comment1;
 110
 111     /**
 112      * The second comment character.
 113      * This is not set by default.
 114      */
 115     char   comment2;
 116
 117     /**
 118      * The third comment character.
 119      * This is not set by default.
 120      */
 121     char   comment3;
 122 } UcxProperties;
 123
 124
 125 /**
 126  * Constructs a new UcxProperties object.
 127  * @return a pointer to the new UcxProperties object
 128  */
 129 UcxProperties *ucx_properties_new();
 130
 131 /**
 132  * Destroys a UcxProperties object.
 133  * @param prop the UcxProperties object to destroy
 134  */
 135 void ucx_properties_free(UcxProperties *prop);
 136
 137 /**
 138  * Sets the input buffer for the properties parser.
 139  *
 140  * After calling this function, you may parse the data by calling
 141  * ucx_properties_next() until it returns 0. The function ucx_properties2map()
 142  * is a convenience function that reads as much data as possible by using this
 143  * function.
 144  *
 145  *
 146  * @param prop the UcxProperties object
 147  * @param buf a pointer to the new buffer
 148  * @param len the payload length of the buffer
 149  * @see ucx_properties_next()
 150  * @see ucx_properties2map()
 151  */
 152 void ucx_properties_fill(UcxProperties *prop, char *buf, size_t len);
 153
 154 /**
 155  * Retrieves the next key/value-pair.
 156  *
 157  * This function returns a nonzero value as long as there are key/value-pairs
 158  * found. If no more key/value-pairs are found, you may refill the input buffer
 159  * with ucx_properties_fill().
 160  *
 161  * <b>Attention:</b> the cxstring.ptr pointers of the output parameters point to
 162  * memory within the input buffer of the parser and will get invalid some time.
 163  * If you want long term copies of the key/value-pairs, use sstrdup() after
 164  * calling this function.
 165  *
 166  * @param prop the UcxProperties object
 167  * @param name a pointer to the cxstring that shall contain the property name
 168  * @param value a pointer to the cxstring that shall contain the property value
 169  * @return Nonzero, if a key/value-pair was successfully retrieved
 170  * @see ucx_properties_fill()
 171  */
 172 int ucx_properties_next(UcxProperties *prop, cxstring *name, cxstring *value);
 173
 174 /**
 175  * Retrieves all available key/value-pairs and puts them into a UcxMap.
 176  *
 177  * This is done by successive calls to ucx_properties_next() until no more
 178  * key/value-pairs can be retrieved.
 179  *
 180  * The memory for the map values is allocated by the map's own allocator.
 181  *
 182  * @param prop the UcxProperties object
 183  * @param map the target map
 184  * @return The UcxProperties.error code (i.e. 0 on success).
 185  * @see ucx_properties_fill()
 186  * @see UcxMap.allocator
 187  */
 188 int ucx_properties2map(UcxProperties *prop, CxMap *map);
 189
 190 /**
 191  * Loads a properties file to a UcxMap.
 192  *
 193  * This is a convenience function that reads data from an input
 194  * stream until the end of the stream is reached.
 195  *
 196  * @param map the map object to write the key/value-pairs to
 197  * @param file the <code>FILE*</code> stream to read from
 198  * @return 0 on success, or a non-zero value on error
 199  *
 200  * @see ucx_properties_fill()
 201  * @see ucx_properties2map()
 202  */
 203 int ucx_properties_load(CxMap *map, FILE *file);
 204
 205 /**
 206  * Stores a UcxMap to a file.
 207  *
 208  * The key/value-pairs are written by using the following format:
 209  *
 210  * <code>[key] = [value]\\n</code>
 211  *
 212  * @param map the map to store
 213  * @param file the <code>FILE*</code> stream to write to
 214  * @return 0 on success, or a non-zero value on error
 215  */
 216 int ucx_properties_store(CxMap *map, FILE *file);
 217
 218 #ifdef  __cplusplus
 219 }
 220 #endif
 221
 222 #endif  /* UCX_PROPERTIES_H */
 223