1.1 --- a/src/ucx/properties.h Mon Dec 30 09:54:10 2019 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,221 +0,0 @@
1.4 -/*
1.5 - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
1.6 - *
1.7 - * Copyright 2017 Mike Becker, 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.h"
1.44 -#include "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 - * The memory for the map values is allocated by the map's own allocator.
1.182 - *
1.183 - * @param prop the UcxProperties object
1.184 - * @param map the target map
1.185 - * @return The UcxProperties.error code (i.e. 0 on success).
1.186 - * @see ucx_properties_fill()
1.187 - * @see UcxMap.allocator
1.188 - */
1.189 -int ucx_properties2map(UcxProperties *prop, UcxMap *map);
1.190 -
1.191 -/**
1.192 - * Loads a properties file to a UcxMap.
1.193 - *
1.194 - * This is a convenience function that reads data from an input
1.195 - * stream until the end of the stream is reached.
1.196 - *
1.197 - * @param map the map object to write the key/value-pairs to
1.198 - * @param file the <code>FILE*</code> stream to read from
1.199 - * @return 0 on success, or a non-zero value on error
1.200 - *
1.201 - * @see ucx_properties_fill()
1.202 - * @see ucx_properties2map()
1.203 - */
1.204 -int ucx_properties_load(UcxMap *map, FILE *file);
1.205 -
1.206 -/**
1.207 - * Stores a UcxMap to a file.
1.208 - *
1.209 - * The key/value-pairs are written by using the following format:
1.210 - *
1.211 - * <code>[key] = [value]\\n</code>
1.212 - *
1.213 - * @param map the map to store
1.214 - * @param file the <code>FILE*</code> stream to write to
1.215 - * @return 0 on success, or a non-zero value on error
1.216 - */
1.217 -int ucx_properties_store(UcxMap *map, FILE *file);
1.218 -
1.219 -#ifdef __cplusplus
1.220 -}
1.221 -#endif
1.222 -
1.223 -#endif /* UCX_PROPERTIES_H */
1.224 -
