Mercurial > hg > ucx / file comparison

comparison: ucx/properties.h

ucx/properties.h

changeset 133
0a70e0d36949
parent 130
633f15ce2ee4
child 146
aa376dba1ba8
equal deleted inserted replaced
132:c7d7e4eeb76b 133:0a70e0d36949
42 42
43 #ifdef __cplusplus 43 #ifdef __cplusplus
44 extern "C" { 44 extern "C" {
45 #endif 45 #endif
46 46
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 */
47 typedef struct { 53 typedef struct {
54 /**
55 * Input buffer (don't set manually).
56 * Automatically set by calls to ucx_properties_fill().
57 */
48 char *buffer; 58 char *buffer;
59 /**
60 * Length of the input buffer (don't set manually).
61 * Automatically set by calls to ucx_properties_fill().
62 */
49 size_t buflen; 63 size_t buflen;
64 /**
65 * Current buffer position (don't set manually).
66 * Used by ucx_properties_next().
67 */
50 size_t pos; 68 size_t pos;
69 /**
70 * Internal temporary buffer (don't set manually).
71 * Used by ucx_properties_next().
72 */
51 char *tmp; 73 char *tmp;
74 /**
75 * Internal temporary buffer length (don't set manually).
76 * Used by ucx_properties_next().
77 */
52 size_t tmplen; 78 size_t tmplen;
79 /**
80 * Internal temporary buffer capacity (don't set manually).
81 * Used by ucx_properties_next().
82 */
53 size_t tmpcap; 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 */
54 int error; 89 int error;
90 /**
91 * The delimiter that shall be used.
92 * This is '=' by default.
93 */
55 char delimiter; 94 char delimiter;
95 /**
96 * The first comment character.
97 * This is '#' by default.
98 */
56 char comment1; 99 char comment1;
100 /**
101 * The second comment character.
102 * This is not set by default.
103 */
57 char comment2; 104 char comment2;
105 /**
106 * The third comment character.
107 * This is not set by default.
108 */
58 char comment3; 109 char comment3;
59 } UcxProperties; 110 } UcxProperties;
60 111
61 112
62 /** 113 /**
63 * Constructs a new UcxProperties object. 114 * Constructs a new UcxProperties object.
64 * @return A pointer to the new UcxProperties object. 115 * @return a pointer to the new UcxProperties object
65 */ 116 */
66 UcxProperties *ucx_properties_new(); 117 UcxProperties *ucx_properties_new();
67 /** 118 /**
68 * Destroys an UcxProperties object. 119 * Destroys an UcxProperties object.
69 * @param prop The UcxProperties object to destroy. 120 * @param prop the UcxProperties object to destroy
70 */ 121 */
71 void ucx_properties_free(UcxProperties *prop); 122 void ucx_properties_free(UcxProperties *prop);
72 /** 123 /**
73 * Refills the input buffer. 124 * Sets the input buffer for the properties parser.
74 * @param prop The UcxProperties object. 125 *
75 * @param buf A pointer to the new buffer. 126 * After calling this function, you may parse the data by calling
76 * @param len The payload length of the buffer. 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()
77 */ 137 */
78 void ucx_properties_fill(UcxProperties *prop, char *buf, size_t len); 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 */
79 int ucx_properties_next(UcxProperties *prop, sstr_t *name, sstr_t *value); 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 */
80 int ucx_properties2map(UcxProperties *prop, UcxMap *map); 169 int ucx_properties2map(UcxProperties *prop, UcxMap *map);
81 170
82 /** 171 /**
83 * Loads a properties file to an UcxMap. 172 * Loads a properties file to an UcxMap.
84 * 173 *
85 * This is a convenience function that reads chunks of 1 KB from an input 174 * This is a convenience function that reads chunks of 1 KB from an input
86 * stream until the end of the stream is reached. 175 * stream until the end of the stream is reached.
87 * 176 *
88 * An UcxProperties object is implicitly created and destroyed. 177 * An UcxProperties object is implicitly created and destroyed.
89 * 178 *
90 * @param map The map object to write the key/value-pairs to. 179 * @param map the map object to write the key/value-pairs to
91 * @param file The <code>FILE*</code> stream to read from. 180 * @param file the <code>FILE*</code> stream to read from
92 * @return 0 on success, or a non-zero value on error 181 * @return 0 on success, or a non-zero value on error
93 * 182 *
94 * @see ucx_properties_fill() 183 * @see ucx_properties_fill()
95 * @see ucx_properties2map() 184 * @see ucx_properties2map()
96 */ 185 */
100 * 189 *
101 * The key/value-pairs are written by using the following format: 190 * The key/value-pairs are written by using the following format:
102 * 191 *
103 * <code>[key] = [value]\\n</code> 192 * <code>[key] = [value]\\n</code>
104 * 193 *
105 * @param map The map to store. 194 * @param map the map to store
106 * @param file The <code>FILE*</code> stream to write to. 195 * @param file the <code>FILE*</code> stream to write to
107 * @return 0 on success, or a non-zero value on error 196 * @return 0 on success, or a non-zero value on error
108 */ 197 */
109 int ucx_properties_store(UcxMap *map, FILE *file); 198 int ucx_properties_store(UcxMap *map, FILE *file);
110 199
111 #ifdef __cplusplus 200 #ifdef __cplusplus

Mercurial Repository: ucx

mercurial