Mercurial > hg > ucx / changeset

     1.1 --- a/ucx/properties.h	Wed Aug 07 09:40:46 2013 +0200
     1.2 +++ b/ucx/properties.h	Fri Aug 09 10:24:02 2013 +0200
     1.3 @@ -44,39 +44,128 @@
     1.4  extern "C" {
     1.5  #endif
     1.6  
     1.7 +/**
     1.8 + * UcxProperties object for parsing properties data.
     1.9 + * Most of the fields are for internal use only. You may configure the
    1.10 + * properties parser, e.g. by changing the used delimiter or specifying 
    1.11 + * up to three different characters that shall introduce comments.
    1.12 + */
    1.13  typedef struct {
    1.14 +    /**
    1.15 +     * Input buffer (don't set manually).
    1.16 +     * Automatically set by calls to ucx_properties_fill().
    1.17 +     */
    1.18      char   *buffer;
    1.19 +    /**
    1.20 +     * Length of the input buffer (don't set manually).
    1.21 +     * Automatically set by calls to ucx_properties_fill().
    1.22 +     */
    1.23      size_t buflen;
    1.24 +    /**
    1.25 +     * Current buffer position (don't set manually).
    1.26 +     * Used by ucx_properties_next().
    1.27 +     */
    1.28      size_t pos;
    1.29 +    /**
    1.30 +     * Internal temporary buffer (don't set manually).
    1.31 +     * Used by ucx_properties_next().
    1.32 +     */
    1.33      char   *tmp;
    1.34 +    /**
    1.35 +     * Internal temporary buffer length (don't set manually).
    1.36 +     * Used by ucx_properties_next().
    1.37 +     */
    1.38      size_t tmplen;
    1.39 +    /**
    1.40 +     * Internal temporary buffer capacity (don't set manually).
    1.41 +     * Used by ucx_properties_next().
    1.42 +     */
    1.43      size_t tmpcap;
    1.44 +    /**
    1.45 +     * Parser error code.
    1.46 +     * This is always 0 on success and a nonzero value on syntax errors.
    1.47 +     * The value is set by ucx_properties_next().
    1.48 +     */
    1.49      int    error;
    1.50 +    /**
    1.51 +     * The delimiter that shall be used.
    1.52 +     * This is '=' by default.
    1.53 +     */
    1.54      char   delimiter;
    1.55 +    /**
    1.56 +     * The first comment character.
    1.57 +     * This is '#' by default.
    1.58 +     */
    1.59      char   comment1;
    1.60 +    /**
    1.61 +     * The second comment character.
    1.62 +     * This is not set by default.
    1.63 +     */
    1.64      char   comment2;
    1.65 +    /**
    1.66 +     * The third comment character.
    1.67 +     * This is not set by default.
    1.68 +     */
    1.69      char   comment3;
    1.70  } UcxProperties;
    1.71  
    1.72  
    1.73  /**
    1.74   * Constructs a new UcxProperties object.
    1.75 - * @return A pointer to the new UcxProperties object.
    1.76 + * @return a pointer to the new UcxProperties object
    1.77   */
    1.78  UcxProperties *ucx_properties_new();
    1.79  /**
    1.80   * Destroys an UcxProperties object.
    1.81 - * @param prop The UcxProperties object to destroy.
    1.82 + * @param prop the UcxProperties object to destroy
    1.83   */
    1.84  void ucx_properties_free(UcxProperties *prop);
    1.85  /**
    1.86 - * Refills the input buffer.
    1.87 - * @param prop The UcxProperties object.
    1.88 - * @param buf A pointer to the new buffer.
    1.89 - * @param len The payload length of the buffer.
    1.90 + * Sets the input buffer for the properties parser.
    1.91 + * 
    1.92 + * After calling this function, you may parse the data by calling
    1.93 + * ucx_properties_next() until it returns 0. The function ucx_properties2map()
    1.94 + * is a convenience function that performs these successive calls of
    1.95 + * ucx_properties_next() within a while loop and puts the properties to a map.
    1.96 + * 
    1.97 + * 
    1.98 + * @param prop the UcxProperties object
    1.99 + * @param buf a pointer to the new buffer
   1.100 + * @param len the payload length of the buffer
   1.101 + * @see ucx_properties_next()
   1.102 + * @see ucx_properties2map()
   1.103   */
   1.104  void ucx_properties_fill(UcxProperties *prop, char *buf, size_t len);
   1.105 +/**
   1.106 + * Retrieves the next key/value-pair.
   1.107 + * 
   1.108 + * This function returns a nonzero value as long as there are key/value-pairs
   1.109 + * found. If no more key/value-pairs are found, you may refill the input buffer
   1.110 + * with ucx_properties_fill().
   1.111 + * 
   1.112 + * <b>Attention:</b> the sstr_t.ptr pointers of the output parameters point to
   1.113 + * memory within the input buffer of the parser and will get invalid some time.
   1.114 + * If you want long term copies of the key/value-pairs, use sstrdup() after
   1.115 + * calling this function.
   1.116 + * 
   1.117 + * @param prop the UcxProperties object
   1.118 + * @param name a pointer to the sstr_t that shall contain the property name
   1.119 + * @param value a pointer to the sstr_t that shall contain the property value
   1.120 + * @return Nonzero, if a key/value-pair was successfully retrieved
   1.121 + * @see ucx_properties_fill()
   1.122 + */
   1.123  int ucx_properties_next(UcxProperties *prop, sstr_t *name, sstr_t *value);
   1.124 +/**
   1.125 + * Retrieves all available key/value-pairs and puts them into an UcxMap.
   1.126 + * 
   1.127 + * This is done by successive calls to ucx_properties_next() until no more
   1.128 + * key/value-pairs can be retrieved. 
   1.129 + * 
   1.130 + * @param prop the UcxProperties object
   1.131 + * @param map the target map
   1.132 + * @return The UcxProperties.error code (i.e. 0 on success).
   1.133 + * @see ucx_properties_fill()
   1.134 + */
   1.135  int ucx_properties2map(UcxProperties *prop, UcxMap *map);
   1.136  
   1.137  /**
   1.138 @@ -87,8 +176,8 @@
   1.139   * 
   1.140   * An UcxProperties object is implicitly created and destroyed.
   1.141   * 
   1.142 - * @param map The map object to write the key/value-pairs to.
   1.143 - * @param file The <code>FILE*</code> stream to read from.
   1.144 + * @param map the map object to write the key/value-pairs to
   1.145 + * @param file the <code>FILE*</code> stream to read from
   1.146   * @return 0 on success, or a non-zero value on error
   1.147   * 
   1.148   * @see ucx_properties_fill()
   1.149 @@ -102,8 +191,8 @@
   1.150   * 
   1.151   * <code>[key] = [value]\\n</code>
   1.152   * 
   1.153 - * @param map The map to store.
   1.154 - * @param file The <code>FILE*</code> stream to write to.
   1.155 + * @param map the map to store
   1.156 + * @param file the <code>FILE*</code> stream to write to
   1.157   * @return 0 on success, or a non-zero value on error
   1.158   */
   1.159  int ucx_properties_store(UcxMap *map, FILE *file);