1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/ucx/properties.h Tue Oct 17 16:15:41 2017 +0200
1.3 @@ -0,0 +1,218 @@
1.4 +/*
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
1.6 + *
1.7 + * Copyright 2017 Olaf Wintermann. All rights reserved.
1.8 + *
1.9 + * Redistribution and use in source and binary forms, with or without
1.10 + * modification, are permitted provided that the following conditions are met:
1.11 + *
1.12 + * 1. Redistributions of source code must retain the above copyright
1.13 + * notice, this list of conditions and the following disclaimer.
1.14 + *
1.15 + * 2. Redistributions in binary form must reproduce the above copyright
1.16 + * notice, this list of conditions and the following disclaimer in the
1.17 + * documentation and/or other materials provided with the distribution.
1.18 + *
1.19 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
1.20 + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1.21 + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1.22 + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
1.23 + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1.24 + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
1.25 + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
1.26 + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
1.27 + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
1.28 + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1.29 + * POSSIBILITY OF SUCH DAMAGE.
1.30 + */
1.31 +/**
1.32 + * @file properties.h
1.33 + *
1.34 + * Load / store utilities for properties files.
1.35 + *
1.36 + * @author Mike Becker
1.37 + * @author Olaf Wintermann
1.38 + */
1.39 +
1.40 +#ifndef UCX_PROPERTIES_H
1.41 +#define UCX_PROPERTIES_H
1.42 +
1.43 +#include <ucx/ucx.h>
1.44 +#include <ucx/map.h>
1.45 +
1.46 +#ifdef __cplusplus
1.47 +extern "C" {
1.48 +#endif
1.49 +
1.50 +/**
1.51 + * UcxProperties object for parsing properties data.
1.52 + * Most of the fields are for internal use only. You may configure the
1.53 + * properties parser, e.g. by changing the used delimiter or specifying
1.54 + * up to three different characters that shall introduce comments.
1.55 + */
1.56 +typedef struct {
1.57 + /**
1.58 + * Input buffer (don't set manually).
1.59 + * Automatically set by calls to ucx_properties_fill().
1.60 + */
1.61 + char *buffer;
1.62 +
1.63 + /**
1.64 + * Length of the input buffer (don't set manually).
1.65 + * Automatically set by calls to ucx_properties_fill().
1.66 + */
1.67 + size_t buflen;
1.68 +
1.69 + /**
1.70 + * Current buffer position (don't set manually).
1.71 + * Used by ucx_properties_next().
1.72 + */
1.73 + size_t pos;
1.74 +
1.75 + /**
1.76 + * Internal temporary buffer (don't set manually).
1.77 + * Used by ucx_properties_next().
1.78 + */
1.79 + char *tmp;
1.80 +
1.81 + /**
1.82 + * Internal temporary buffer length (don't set manually).
1.83 + * Used by ucx_properties_next().
1.84 + */
1.85 + size_t tmplen;
1.86 +
1.87 + /**
1.88 + * Internal temporary buffer capacity (don't set manually).
1.89 + * Used by ucx_properties_next().
1.90 + */
1.91 + size_t tmpcap;
1.92 +
1.93 + /**
1.94 + * Parser error code.
1.95 + * This is always 0 on success and a nonzero value on syntax errors.
1.96 + * The value is set by ucx_properties_next().
1.97 + */
1.98 + int error;
1.99 +
1.100 + /**
1.101 + * The delimiter that shall be used.
1.102 + * This is '=' by default.
1.103 + */
1.104 + char delimiter;
1.105 +
1.106 + /**
1.107 + * The first comment character.
1.108 + * This is '#' by default.
1.109 + */
1.110 + char comment1;
1.111 +
1.112 + /**
1.113 + * The second comment character.
1.114 + * This is not set by default.
1.115 + */
1.116 + char comment2;
1.117 +
1.118 + /**
1.119 + * The third comment character.
1.120 + * This is not set by default.
1.121 + */
1.122 + char comment3;
1.123 +} UcxProperties;
1.124 +
1.125 +
1.126 +/**
1.127 + * Constructs a new UcxProperties object.
1.128 + * @return a pointer to the new UcxProperties object
1.129 + */
1.130 +UcxProperties *ucx_properties_new();
1.131 +
1.132 +/**
1.133 + * Destroys a UcxProperties object.
1.134 + * @param prop the UcxProperties object to destroy
1.135 + */
1.136 +void ucx_properties_free(UcxProperties *prop);
1.137 +
1.138 +/**
1.139 + * Sets the input buffer for the properties parser.
1.140 + *
1.141 + * After calling this function, you may parse the data by calling
1.142 + * ucx_properties_next() until it returns 0. The function ucx_properties2map()
1.143 + * is a convenience function that reads as much data as possible by using this
1.144 + * function.
1.145 + *
1.146 + *
1.147 + * @param prop the UcxProperties object
1.148 + * @param buf a pointer to the new buffer
1.149 + * @param len the payload length of the buffer
1.150 + * @see ucx_properties_next()
1.151 + * @see ucx_properties2map()
1.152 + */
1.153 +void ucx_properties_fill(UcxProperties *prop, char *buf, size_t len);
1.154 +
1.155 +/**
1.156 + * Retrieves the next key/value-pair.
1.157 + *
1.158 + * This function returns a nonzero value as long as there are key/value-pairs
1.159 + * found. If no more key/value-pairs are found, you may refill the input buffer
1.160 + * with ucx_properties_fill().
1.161 + *
1.162 + * <b>Attention:</b> the sstr_t.ptr pointers of the output parameters point to
1.163 + * memory within the input buffer of the parser and will get invalid some time.
1.164 + * If you want long term copies of the key/value-pairs, use sstrdup() after
1.165 + * calling this function.
1.166 + *
1.167 + * @param prop the UcxProperties object
1.168 + * @param name a pointer to the sstr_t that shall contain the property name
1.169 + * @param value a pointer to the sstr_t that shall contain the property value
1.170 + * @return Nonzero, if a key/value-pair was successfully retrieved
1.171 + * @see ucx_properties_fill()
1.172 + */
1.173 +int ucx_properties_next(UcxProperties *prop, sstr_t *name, sstr_t *value);
1.174 +
1.175 +/**
1.176 + * Retrieves all available key/value-pairs and puts them into a UcxMap.
1.177 + *
1.178 + * This is done by successive calls to ucx_properties_next() until no more
1.179 + * key/value-pairs can be retrieved.
1.180 + *
1.181 + * @param prop the UcxProperties object
1.182 + * @param map the target map
1.183 + * @return The UcxProperties.error code (i.e. 0 on success).
1.184 + * @see ucx_properties_fill()
1.185 + */
1.186 +int ucx_properties2map(UcxProperties *prop, UcxMap *map);
1.187 +
1.188 +/**
1.189 + * Loads a properties file to a UcxMap.
1.190 + *
1.191 + * This is a convenience function that reads data from an input
1.192 + * stream until the end of the stream is reached.
1.193 + *
1.194 + * @param map the map object to write the key/value-pairs to
1.195 + * @param file the <code>FILE*</code> stream to read from
1.196 + * @return 0 on success, or a non-zero value on error
1.197 + *
1.198 + * @see ucx_properties_fill()
1.199 + * @see ucx_properties2map()
1.200 + */
1.201 +int ucx_properties_load(UcxMap *map, FILE *file);
1.202 +
1.203 +/**
1.204 + * Stores a UcxMap to a file.
1.205 + *
1.206 + * The key/value-pairs are written by using the following format:
1.207 + *
1.208 + * <code>[key] = [value]\\n</code>
1.209 + *
1.210 + * @param map the map to store
1.211 + * @param file the <code>FILE*</code> stream to write to
1.212 + * @return 0 on success, or a non-zero value on error
1.213 + */
1.214 +int ucx_properties_store(UcxMap *map, FILE *file);
1.215 +
1.216 +#ifdef __cplusplus
1.217 +}
1.218 +#endif
1.219 +
1.220 +#endif /* UCX_PROPERTIES_H */
1.221 +
