ucx/properties.h@0a70e0d36949
ucx/properties.h
Fri, 09 Aug 2013 10:24:02 +0200
- author
- Mike Becker <universe@uap-core.de>
- date
- Fri, 09 Aug 2013 10:24:02 +0200
- changeset 133
- 0a70e0d36949
- parent 130
- 633f15ce2ee4
- child 146
- aa376dba1ba8
- permissions
- -rw-r--r--
finished documentation of UcxProperties
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2013 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;
59 /**
60 * Length of the input buffer (don't set manually).
61 * Automatically set by calls to ucx_properties_fill().
62 */
63 size_t buflen;
64 /**
65 * Current buffer position (don't set manually).
66 * Used by ucx_properties_next().
67 */
68 size_t pos;
69 /**
70 * Internal temporary buffer (don't set manually).
71 * Used by ucx_properties_next().
72 */
73 char *tmp;
74 /**
75 * Internal temporary buffer length (don't set manually).
76 * Used by ucx_properties_next().
77 */
78 size_t tmplen;
79 /**
80 * Internal temporary buffer capacity (don't set manually).
81 * Used by ucx_properties_next().
82 */
83 size_t tmpcap;
84 /**
85 * Parser error code.
86 * This is always 0 on success and a nonzero value on syntax errors.
87 * The value is set by ucx_properties_next().
88 */
89 int error;
90 /**
91 * The delimiter that shall be used.
92 * This is '=' by default.
93 */
94 char delimiter;
95 /**
96 * The first comment character.
97 * This is '#' by default.
98 */
99 char comment1;
100 /**
101 * The second comment character.
102 * This is not set by default.
103 */
104 char comment2;
105 /**
106 * The third comment character.
107 * This is not set by default.
108 */
109 char comment3;
110 } UcxProperties;
113 /**
114 * Constructs a new UcxProperties object.
115 * @return a pointer to the new UcxProperties object
116 */
117 UcxProperties *ucx_properties_new();
118 /**
119 * Destroys an UcxProperties object.
120 * @param prop the UcxProperties object to destroy
121 */
122 void ucx_properties_free(UcxProperties *prop);
123 /**
124 * Sets the input buffer for the properties parser.
125 *
126 * After calling this function, you may parse the data by calling
127 * ucx_properties_next() until it returns 0. The function ucx_properties2map()
128 * is a convenience function that performs these successive calls of
129 * ucx_properties_next() within a while loop and puts the properties to a map.
130 *
131 *
132 * @param prop the UcxProperties object
133 * @param buf a pointer to the new buffer
134 * @param len the payload length of the buffer
135 * @see ucx_properties_next()
136 * @see ucx_properties2map()
137 */
138 void ucx_properties_fill(UcxProperties *prop, char *buf, size_t len);
139 /**
140 * Retrieves the next key/value-pair.
141 *
142 * This function returns a nonzero value as long as there are key/value-pairs
143 * found. If no more key/value-pairs are found, you may refill the input buffer
144 * with ucx_properties_fill().
145 *
146 * <b>Attention:</b> the sstr_t.ptr pointers of the output parameters point to
147 * memory within the input buffer of the parser and will get invalid some time.
148 * If you want long term copies of the key/value-pairs, use sstrdup() after
149 * calling this function.
150 *
151 * @param prop the UcxProperties object
152 * @param name a pointer to the sstr_t that shall contain the property name
153 * @param value a pointer to the sstr_t that shall contain the property value
154 * @return Nonzero, if a key/value-pair was successfully retrieved
155 * @see ucx_properties_fill()
156 */
157 int ucx_properties_next(UcxProperties *prop, sstr_t *name, sstr_t *value);
158 /**
159 * Retrieves all available key/value-pairs and puts them into an UcxMap.
160 *
161 * This is done by successive calls to ucx_properties_next() until no more
162 * key/value-pairs can be retrieved.
163 *
164 * @param prop the UcxProperties object
165 * @param map the target map
166 * @return The UcxProperties.error code (i.e. 0 on success).
167 * @see ucx_properties_fill()
168 */
169 int ucx_properties2map(UcxProperties *prop, UcxMap *map);
171 /**
172 * Loads a properties file to an UcxMap.
173 *
174 * This is a convenience function that reads chunks of 1 KB from an input
175 * stream until the end of the stream is reached.
176 *
177 * An UcxProperties object is implicitly created and destroyed.
178 *
179 * @param map the map object to write the key/value-pairs to
180 * @param file the <code>FILE*</code> stream to read from
181 * @return 0 on success, or a non-zero value on error
182 *
183 * @see ucx_properties_fill()
184 * @see ucx_properties2map()
185 */
186 int ucx_properties_load(UcxMap *map, FILE *file);
187 /**
188 * Stores an UcxMap to a file.
189 *
190 * The key/value-pairs are written by using the following format:
191 *
192 * <code>[key] = [value]\\n</code>
193 *
194 * @param map the map to store
195 * @param file the <code>FILE*</code> stream to write to
196 * @return 0 on success, or a non-zero value on error
197 */
198 int ucx_properties_store(UcxMap *map, FILE *file);
200 #ifdef __cplusplus
201 }
202 #endif
204 #endif /* UCX_PROPERTIES_H */
