* uns value;
* };
*
- * struct clist nodes;
+ * static struct clist nodes;
*
* static struct cf_section node = {
* CF_TYPE(struct list_node),
* CF_END
* };
*
- * You could use <<def_CF_STATIC,`def_CF_STATIC`>> or <<def_CF_DYNAMIC,`def_CF_DYNAMIC`>>
+ * You could use <<def_CF_STATIC,`CF_STATIC`>> or <<def_CF_DYNAMIC,`CF_DYNAMIC`>>
* macros to create arrays.
*/
#define CF_TYPE(s) .size = sizeof(s)
-#define CF_INIT(f) .init = (cf_hook*) f /** Init <<hooks,hook>>. **/
-#define CF_COMMIT(f) .commit = (cf_hook*) f /** Commit <<hooks,hook>>. **/
-#define CF_COPY(f) .copy = (cf_copier*) f /** <<hooks,Copy function>>. **/
+/**
+ * An init <<hooks,hook>>.
+ * You can use this to initialize dynamically allocated items (for a dynamic array or list).
+ * The hook returns an error message or NULL if everything was OK.
+ */
+#define CF_INIT(f) .init = (cf_hook*) f
+/**
+ * A commit <<hooks,hook>>.
+ * You can use this one to check sanity of loaded data and postprocess them.
+ * You must call @cf_journal_block() if you change anything.
+ *
+ * Return error message or NULL if everything went OK.
+ **/
+#define CF_COMMIT(f) .commit = (cf_hook*) f
+/**
+ * A <<hooks,copy function>>.
+ * You need to provide one for too complicated sections where a memcpy is not
+ * enough to copy it properly. It happens, for example, when you have a dynamically
+ * allocated section containing a list of other sections.
+ *
+ * You return an error message or NULL if you succeed.
+ **/
+#define CF_COPY(f) .copy = (cf_copier*) f /** **/
#define CF_ITEMS .cfg = ( struct cf_item[] ) /** List of sub-items. **/
#define CF_END { .cls = CC_END } /** End of the structure. **/
/***
* * @c -- count.
**/
#define CF_INT(n,p) CF_STATIC(n,p,INT,int,1) /** Single `int` value. **/
-#define CF_INT_ARY(n,p,c) CF_STATIC(n,p,INT,int,c) /** Static array of `int` s. **/
-#define CF_INT_DYN(n,p,c) CF_DYNAMIC(n,p,INT,int,c) /** Dynamic array of `int` s. **/
+#define CF_INT_ARY(n,p,c) CF_STATIC(n,p,INT,int,c) /** Static array of integers. **/
+#define CF_INT_DYN(n,p,c) CF_DYNAMIC(n,p,INT,int,c) /** Dynamic array of integers. **/
#define CF_UNS(n,p) CF_STATIC(n,p,INT,uns,1) /** Single `uns` (`unsigned`) value. **/
-#define CF_UNS_ARY(n,p,c) CF_STATIC(n,p,INT,uns,c) /** Static array of `uns` es. **/
-#define CF_UNS_DYN(n,p,c) CF_DYNAMIC(n,p,INT,uns,c) /** Dynamic array of `uns` es. **/
+#define CF_UNS_ARY(n,p,c) CF_STATIC(n,p,INT,uns,c) /** Static array of unsigned integers. **/
+#define CF_UNS_DYN(n,p,c) CF_DYNAMIC(n,p,INT,uns,c) /** Dynamic array of unsigned integers. **/
#define CF_U64(n,p) CF_STATIC(n,p,U64,u64,1) /** Single unsigned 64bit integer (`u64`). **/
-#define CF_U64_ARY(n,p,c) CF_STATIC(n,p,U64,u64,c) /** Static array of `u64` s. **/
-#define CF_U64_DYN(n,p,c) CF_DYNAMIC(n,p,U64,u64,c) /** Dynamic array of `u64` s. **/
+#define CF_U64_ARY(n,p,c) CF_STATIC(n,p,U64,u64,c) /** Static array of u64s. **/
+#define CF_U64_DYN(n,p,c) CF_DYNAMIC(n,p,U64,u64,c) /** Dynamic array of u64s. **/
#define CF_DOUBLE(n,p) CF_STATIC(n,p,DOUBLE,double,1) /** Single instance of `double`. **/
-#define CF_DOUBLE_ARY(n,p,c) CF_STATIC(n,p,DOUBLE,double,c) /** Static array of `double` s. **/
-#define CF_DOUBLE_DYN(n,p,c) CF_DYNAMIC(n,p,DOUBLE,double,c) /** Dynamic array of `double` s. **/
+#define CF_DOUBLE_ARY(n,p,c) CF_STATIC(n,p,DOUBLE,double,c) /** Static array of doubles. **/
+#define CF_DOUBLE_DYN(n,p,c) CF_DYNAMIC(n,p,DOUBLE,double,c) /** Dynamic array of doubles. **/
#define CF_IP(n,p) CF_STATIC(n,p,IP,u32,1) /** Single IPv4 address. **/
#define CF_IP_ARY(n,p,c) CF_STATIC(n,p,IP,u32,c) /** Static array of IP addresses. **/.
#define CF_IP_DYN(n,p,c) CF_DYNAMIC(n,p,IP,u32,c) /** Dynamic array of IP addresses. **/
-#define CF_STRING(n,p) CF_STATIC(n,p,STRING,char*,1) /** One string. **/
+/**
+ * A string.
+ * You provide a pointer to a `char *` variable and it will fill it with
+ * dynamically allocated string. For example:
+ *
+ * static char *string = "Default string";
+ *
+ * static struct cf_section section = {
+ * CF_ITEMS {
+ * CF_STRING("string", &string),
+ * CF_END
+ * }
+ * };
+ **/
+#define CF_STRING(n,p) CF_STATIC(n,p,STRING,char*,1)
#define CF_STRING_ARY(n,p,c) CF_STATIC(n,p,STRING,char*,c) /** Static array of strings. **/
#define CF_STRING_DYN(n,p,c) CF_DYNAMIC(n,p,STRING,char*,c) /** Dynamic array of strings. **/
/**
* One string out of a predefined set.
* You provide the set as an array of strings terminated by NULL (similar to @argv argument
* of main()) as the @t parameter.
+ *
+ * The configured variable (pointer to `int`) is set to index of the string.
+ * So, it works this way:
+ *
+ * static *strings[] = { "First", "Second", "Third", NULL };
+ *
+ * static int variable;
+ *
+ * static struct cf_section section = {
+ * CF_ITEMS {
+ * CF_LOOKUP("choice", &variable, strings),
+ * CF_END
+ * }
+ * };
+ *
+ * Now, if the configuration contains `choice "Second"`, `variable` will be set to 1.
**/
#define CF_LOOKUP(n,p,t) { .cls = CC_STATIC, .type = CT_LOOKUP, .name = n, .number = 1, .ptr = CHECK_PTR_TYPE(p,int*), .u.lookup = t }
/**
* Static array of strings out of predefined set.
- * See <<def_CF_LOOKUP,`CF_LOOKUP`>>.
**/
#define CF_LOOKUP_ARY(n,p,t,c) { .cls = CC_STATIC, .type = CT_LOOKUP, .name = n, .number = c, .ptr = CHECK_PTR_TYPE(p,int*), .u.lookup = t }
/**
* Dynamic array of strings out of predefined set.
- * See <<def_CF_LOOKUP,`CF_LOOKUP`>>.
**/
#define CF_LOOKUP_DYN(n,p,t,c) { .cls = CC_DYNAMIC, .type = CT_LOOKUP, .name = n, .number = c, .ptr = CHECK_PTR_TYPE(p,int**), .u.lookup = t }
/**
- * A user defined type.
+ * A user-defined type.
* See <<custom_parser,creating custom parsers>> section if you want to know more.
**/
#define CF_USER(n,p,t) { .cls = CC_STATIC, .type = CT_USER, .name = n, .number = 1, .ptr = p, .u.utype = t }
/**
- * Static array of user defined types (all of the same type).
+ * Static array of user-defined types (all of the same type).
* See <<custom_parser,creating custom parsers>> section.
**/
#define CF_USER_ARY(n,p,t,c) { .cls = CC_STATIC, .type = CT_USER, .name = n, .number = c, .ptr = p, .u.utype = t }
/**
- * Dynamic array of user defined types.
+ * Dynamic array of user-defined types.
* See <<custom_parser,creating custom parsers>> section.
**/
#define CF_USER_DYN(n,p,t,c) { .cls = CC_DYNAMIC, .type = CT_USER, .name = n, .number = c, .ptr = p, .u.utype = t }
* You should use these routines when implementing custom parsers.
***/
struct mempool;
-extern struct mempool *cf_pool; /** A <<mempool:type_mempool,memory pool>> for configuration parser needs. **/
-void *cf_malloc(uns size); /** Returns @size bytes of memory. **/
+/**
+ * A <<mempool:type_mempool,memory pool>> for configuration parser needs.
+ * Memory allocated from here is valid as long as the current config is loaded
+ * (if you allocate some memory and rollback the transaction or you load some
+ * other configuration, it gets lost).
+ **/
+extern struct mempool *cf_pool;
+void *cf_malloc(uns size); /** Returns @size bytes of memory. Allocates from <<var_cf_pool,`cf_pool`>>. **/
void *cf_malloc_zero(uns size); /** Like @cf_malloc(), but zeroes the memory. **/
char *cf_strdup(const char *s); /** Copy a string into @cf_malloc()ed memory. **/
char *cf_printf(const char *fmt, ...) FORMAT_CHECK(printf,1,2); /** printf() into @cf_malloc()ed memory. **/
* Undo journal
* ~~~~~~~~~~~~
*
- * For error recovery
+ * For error recovery when <<reload,reloading configuration>>.
***/
-extern uns cf_need_journal;
+extern uns cf_need_journal; /** Is the journal needed? If you do not reload configuration, you set this to 0 and gain a little more performance and free memory. **/
+/**
+ * When a block of memory is about to be changed, put the old value
+ * into journal with this function. You need to call it from a <<hooks,commit hook>>
+ * if you change anything. It is used internally by low-level parsers.
+ * <<custom_parser,Custom parsers>> do not need to call it, it is called
+ * before them.
+ **/
void cf_journal_block(void *ptr, uns len);
-#define CF_JOURNAL_VAR(var) cf_journal_block(&(var), sizeof(var))
+#define CF_JOURNAL_VAR(var) cf_journal_block(&(var), sizeof(var)) // Store single value into journal.
-/* Declaration: conf-section.c */
+/***
+ * [[declare]]
+ * Section declaration
+ * ~~~~~~~~~~~~~~~~~~~
+ **/
+
+/**
+ * Plug another top-level section into the configuration system.
+ * @name is the name in the configuration file,
+ * @sec is pointer to the section description.
+ * If @allow_unknown is set to 0 and a variable not described in @sec
+ * is found in the configuration file, it produces an error.
+ * If you set it to 1, all such variables are ignored.
+ **/
void cf_declare_section(const char *name, struct cf_section *sec, uns allow_unknown);
+/**
+ * If you have a section in a structure and you want to initialize it
+ * (eg. if you want a copy of default values outside the configuration),
+ * you can use this. It initializes it recursively.
+ *
+ * This is used mostly internally. You probably do not need it.
+ **/
void cf_init_section(const char *name, struct cf_section *sec, void *ptr, uns do_bzero);
-/*** === Parsers for basic types [[bparser]] ***/
+/***
+ * [[bparser]]
+ * Parsers for basic types
+ * ~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * Each of them gets a string to parse and pointer to store the value.
+ * It returns either NULL or error message.
+ *
+ * The parsers support units. See <<config:units,their list>>.
+ ***/
char *cf_parse_int(const char *str, int *ptr); /** Parser for integers. **/
char *cf_parse_u64(const char *str, u64 *ptr); /** Parser for 64 unsigned integers. **/
char *cf_parse_double(const char *str, double *ptr); /** Parser for doubles. **/
projects / libucw.git / blobdiff