ucx: src/ucx/properties.h@2f5dea574a75

     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  */

    37 #ifndef UCX_PROPERTIES_H

    38 #define	UCX_PROPERTIES_H

    40 #include "ucx.h"

    41 #include "map.h"

    43 #ifdef	__cplusplus

    44 extern "C" {

    45 #endif

    47 /**

    48  * UcxProperties object for parsing properties data.

    49  * Most of the fields are for internal use only. You may configure the

    50  * properties parser, e.g. by changing the used delimiter or specifying

    51  * up to three different characters that shall introduce comments.

    52  */

    53 typedef struct {

    54     /**

    55      * Input buffer (don't set manually).

    56      * Automatically set by calls to ucx_properties_fill().

    57      */

    58     char   *buffer;

    60     /**

    61      * Length of the input buffer (don't set manually).

    62      * Automatically set by calls to ucx_properties_fill().

    63      */

    64     size_t buflen;

    66     /**

    67      * Current buffer position (don't set manually).

    68      * Used by ucx_properties_next().

    69      */

    70     size_t pos;

    72     /**

    73      * Internal temporary buffer (don't set manually).

    74      * Used by ucx_properties_next().

    75      */

    76     char   *tmp;

    78     /**

    79      * Internal temporary buffer length (don't set manually).

    80      * Used by ucx_properties_next().

    81      */

    82     size_t tmplen;

    84     /**

    85      * Internal temporary buffer capacity (don't set manually).

    86      * Used by ucx_properties_next().

    87      */

    88     size_t tmpcap;

    90     /**

    91      * Parser error code.

    92      * This is always 0 on success and a nonzero value on syntax errors.

    93      * The value is set by ucx_properties_next().

    94      */

    95     int    error;

    97     /**

    98      * The delimiter that shall be used.

    99      * This is '=' by default.

   100      */

   101     char   delimiter;

   103     /**

   104      * The first comment character.

   105      * This is '#' by default.

   106      */

   107     char   comment1;

   109     /**

   110      * The second comment character.

   111      * This is not set by default.

   112      */

   113     char   comment2;

   115     /**

   116      * The third comment character.

   117      * This is not set by default.

   118      */

   119     char   comment3;

   120 } UcxProperties;

   123 /**

   124  * Constructs a new UcxProperties object.

   125  * @return a pointer to the new UcxProperties object

   126  */

   127 UcxProperties *ucx_properties_new();

   129 /**

   130  * Destroys a UcxProperties object.

   131  * @param prop the UcxProperties object to destroy

   132  */

   133 void ucx_properties_free(UcxProperties *prop);

   135 /**

   136  * Sets the input buffer for the properties parser.

   137  *

   138  * After calling this function, you may parse the data by calling

   139  * ucx_properties_next() until it returns 0. The function ucx_properties2map()

   140  * is a convenience function that reads as much data as possible by using this

   141  * function.

   142  *

   143  *

   144  * @param prop the UcxProperties object

   145  * @param buf a pointer to the new buffer

   146  * @param len the payload length of the buffer

   147  * @see ucx_properties_next()

   148  * @see ucx_properties2map()

   149  */

   150 void ucx_properties_fill(UcxProperties *prop, char *buf, size_t len);

   152 /**

   153  * Retrieves the next key/value-pair.

   154  *

   155  * This function returns a nonzero value as long as there are key/value-pairs

   156  * found. If no more key/value-pairs are found, you may refill the input buffer

   157  * with ucx_properties_fill().

   158  *

   159  * <b>Attention:</b> the sstr_t.ptr pointers of the output parameters point to

   160  * memory within the input buffer of the parser and will get invalid some time.

   161  * If you want long term copies of the key/value-pairs, use sstrdup() after

   162  * calling this function.

   163  *

   164  * @param prop the UcxProperties object

   165  * @param name a pointer to the sstr_t that shall contain the property name

   166  * @param value a pointer to the sstr_t that shall contain the property value

   167  * @return Nonzero, if a key/value-pair was successfully retrieved

   168  * @see ucx_properties_fill()

   169  */

   170 int ucx_properties_next(UcxProperties *prop, sstr_t *name, sstr_t *value);

   172 /**

   173  * Retrieves all available key/value-pairs and puts them into a UcxMap.

   174  *

   175  * This is done by successive calls to ucx_properties_next() until no more

   176  * key/value-pairs can be retrieved.

   177  *

   178  * @param prop the UcxProperties object

   179  * @param map the target map

   180  * @return The UcxProperties.error code (i.e. 0 on success).

   181  * @see ucx_properties_fill()

   182  */

   183 int ucx_properties2map(UcxProperties *prop, UcxMap *map);

   185 /**

   186  * Loads a properties file to a UcxMap.

   187  *

   188  * This is a convenience function that reads data from an input

   189  * stream until the end of the stream is reached.

   190  *

   191  * @param map the map object to write the key/value-pairs to

   192  * @param file the <code>FILE*</code> stream to read from

   193  * @return 0 on success, or a non-zero value on error

   194  *

   195  * @see ucx_properties_fill()

   196  * @see ucx_properties2map()

   197  */

   198 int ucx_properties_load(UcxMap *map, FILE *file);

   200 /**

   201  * Stores a UcxMap to a file.

   202  *

   203  * The key/value-pairs are written by using the following format:

   204  *

   205  * <code>[key] = [value]\\n</code>

   206  *

   207  * @param map the map to store

   208  * @param file the <code>FILE*</code> stream to write to

   209  * @return 0 on success, or a non-zero value on error

   210  */

   211 int ucx_properties_store(UcxMap *map, FILE *file);

   213 #ifdef	__cplusplus

   214 }

   215 #endif

   217 #endif	/* UCX_PROPERTIES_H */

Mercurial > hg > ucx / file revision