LcConfigC_Set_C_API

LcConfigC - various functions to set config-data … More...

Collaboration diagram for LcConfigC_Set_C_API:

Functions
enum MkErrorE	LcConfigIncludeCall (LcConfigIncludeCallF_ARGS)
	config-file include __parser__(callback-name) → call …
void	LcConfigIncludeFree (LcConfigIncludeFreeF_ARGS)
	config-file include __parser__(callback-name) → free …
enum MkErrorE	LcConfigSetIncludeFunc_RT (MK_RT mkrt, LC_CFG const cfg, LcConfigIncludeCallF fConfigIncludeCall, LC_CBP fConfigIncludeData, LcConfigIncludeFreeF fConfigIncludeFree)
	set the __parser__(callback-name) for the include-config-file …
enum MkErrorE	LcConfigSetSettingDeleteFunc_RT (MK_RT mkrt, LC_CFG const cfg, LcSettingDeleteCallF fSettingDeleteCall, LC_CBP fSettingDeleteData, LcSettingDeleteFreeF fSettingDeleteFree)
	set the callback-name for the setting-delete …
void	LcConfigSetDefaultFormat (LC_CFG config, enum LcConfigFormatE format)
	These functions, which are implemented as macros, get and set the default external format for settings in the configuration config …
void	LcConfigSetFloatPrecision (LC_CFG config, MK_I16 digits)
	Since v1.6 These functions get and set the number of decimal digits to output after the radix character when writing the configuration to a file or stream …
void	LcConfigSetIncludeDir (LC_CFG config, MK_STRN include_dir)
	config_set_include_dir specifies the include directory, include_dir, relative to which the files specified in '@include' directives will be located for the configuration config …
void	LcConfigSetIncludeFuncHide (LC_CFG config, config_include_fn_t func)
	Since v1.7 Specifies the include function func to use when processing include directives …
void	LcConfigSetOption (LC_CFG config, enum LcConfigOptionsEF option, MK_BOOL flag)
	Since v1.7 These functions get and set the given option of the configuration config …
void	LcConfigSetOptions (LC_CFG config, enum LcConfigOptionsEF options)
	These functions get and set the options for the configuration config …
void	LcConfigSetTabWidth (LC_CFG config, MK_I16 width)
	These functions, which are implemented as macros, get and set the tab width for the configuration config …

LcConfigC - LcConfigC_Set_C_API - function
LC_EXTERN void	LcConfigSetDefaultFormatP (LC_CFG config, enum LcConfigFormatE format)
	Non-inline replacement for LcConfigSetDefaultFormat …
LC_EXTERN void	LcConfigSetFloatPrecisionP (LC_CFG config, MK_I16 digits)
	Non-inline replacement for LcConfigSetFloatPrecision …
LC_EXTERN void	LcConfigSetIncludeDirP (LC_CFG config, MK_STRN include_dir)
	Non-inline replacement for LcConfigSetIncludeDir …
LC_EXTERN void	LcConfigSetIncludeFuncHideP (LC_CFG config, config_include_fn_t func)
	Non-inline replacement for LcConfigSetIncludeFuncHide …
LC_EXTERN void	LcConfigSetOptionP (LC_CFG config, enum LcConfigOptionsEF option, MK_BOOL flag)
	Non-inline replacement for LcConfigSetOption …
LC_EXTERN void	LcConfigSetOptionsP (LC_CFG config, enum LcConfigOptionsEF options)
	Non-inline replacement for LcConfigSetOptions …
LC_EXTERN void	LcConfigSetTabWidthP (LC_CFG config, MK_I16 width)
	Non-inline replacement for LcConfigSetTabWidth …

LcConfigC - LcConfigC_Set_C_API - overload
#define	LcConfigSetIncludeFunc_NULL(...)
#define	LcConfigSetIncludeFunc(...)
#define	LcConfigSetIncludeFunc_E(...)
#define	LcConfigSetIncludeFunc_C(...)
#define	LcConfigSetSettingDeleteFunc_NULL(...)
#define	LcConfigSetSettingDeleteFunc(...)
#define	LcConfigSetSettingDeleteFunc_E(...)
#define	LcConfigSetSettingDeleteFunc_C(...)

Detailed Description

LcConfigC - various functions to set config-data …

Macro Definition Documentation

LcConfigSetIncludeFunc

#define LcConfigSetIncludeFunc

(

...

)

Value:

LcConfigSetIncludeFunc_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 130 of file config_overload_lc.h.

LcConfigSetIncludeFunc_C

#define LcConfigSetIncludeFunc_C

(

...

)

Value:

if (MkErrorCheckI(LcConfigSetIncludeFunc(__VA_ARGS__)))

Definition at line 132 of file config_overload_lc.h.

LcConfigSetIncludeFunc_E

#define LcConfigSetIncludeFunc_E

(

...

)

Value:

MkErrorCheck(LcConfigSetIncludeFunc(__VA_ARGS__))

Definition at line 131 of file config_overload_lc.h.

LcConfigSetIncludeFunc_NULL

#define LcConfigSetIncludeFunc_NULL

(

...

)

Value:

LcConfigSetIncludeFunc_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 129 of file config_overload_lc.h.

LcConfigSetSettingDeleteFunc

#define LcConfigSetSettingDeleteFunc

(

...

)

Value:

LcConfigSetSettingDeleteFunc_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 134 of file config_overload_lc.h.

LcConfigSetSettingDeleteFunc_C

#define LcConfigSetSettingDeleteFunc_C

(

...

)

Value:

if (MkErrorCheckI(LcConfigSetSettingDeleteFunc(__VA_ARGS__)))

Definition at line 136 of file config_overload_lc.h.

LcConfigSetSettingDeleteFunc_E

#define LcConfigSetSettingDeleteFunc_E

(

...

)

Value:

MkErrorCheck(LcConfigSetSettingDeleteFunc(__VA_ARGS__))

Definition at line 135 of file config_overload_lc.h.

LcConfigSetSettingDeleteFunc_NULL

#define LcConfigSetSettingDeleteFunc_NULL

(

...

)

Value:

LcConfigSetSettingDeleteFunc_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 133 of file config_overload_lc.h.

Function Documentation

LcConfigIncludeCall()

enum MkErrorE LcConfigIncludeCall ( LcConfigIncludeCallF_ARGS )

extern

config-file include __parser__(callback-name) → call …

LcConfigIncludeFree()

void LcConfigIncludeFree ( LcConfigIncludeFreeF_ARGS )

extern

config-file include __parser__(callback-name) → free …

LcConfigSetDefaultFormat()

void LcConfigSetDefaultFormat ( LC_CFG config, enum LcConfigFormatE format )

inline

These functions, which are implemented as macros, get and set the default external format for settings in the configuration config …

If a non-default format has not been set for a setting with config_setting_set_format, this configuration-wide default format will be used instead when that setting is written to a file or stream.

See also

config_get_default_format

Definition at line 390 of file LcConfigC_lc.h.

                                                                                       {
    LC_INSTANCE_HDL(config);
    config_set_default_format(config->nat, format);
  }

LcConfigSetDefaultFormatP()

LC_EXTERN void LcConfigSetDefaultFormatP	(	LC_CFG	config,
		enum LcConfigFormatE	format )

Non-inline replacement for LcConfigSetDefaultFormat …

LcConfigSetFloatPrecision()

void LcConfigSetFloatPrecision ( LC_CFG config, MK_I16 digits )

inline

Since v1.6 These functions get and set the number of decimal digits to output after the radix character when writing the configuration to a file or stream …

Valid values for digits range from 0 (no decimals) to about 15 (implementation defined). This parameter has no effect on parsing.

The default float precision is 6.

See also

config_get_float_precision

Definition at line 396 of file LcConfigC_lc.h.

                                                                          {
    LC_INSTANCE_HDL(config);
    config_set_float_precision(config->nat, (MK_U16)digits);
  }

LcConfigSetFloatPrecisionP()

LC_EXTERN void LcConfigSetFloatPrecisionP	(	LC_CFG	config,
		MK_I16	digits )

Non-inline replacement for LcConfigSetFloatPrecision …

LcConfigSetIncludeDir()

void LcConfigSetIncludeDir ( LC_CFG config, MK_STRN include_dir )

inline

config_set_include_dir specifies the include directory, include_dir, relative to which the files specified in '@include' directives will be located for the configuration config …

By default, there is no include directory, and all include files are expected to be relative to the current working directory. If include_dir is NULL, the default behavior is reinstated.

For example, if the include directory is set to /usr/local/etc, the include directive '@include "configs/extra.cfg"' would include the file /usr/local/etc/configs/extra.cfg.

config_get_include_dir returns the current include directory for the configuration config, or NULL if none is set.

See also

config_get_include_dir

Definition at line 402 of file LcConfigC_lc.h.

                                                                            {
    LC_INSTANCE_HDL(config);
    config_set_include_dir(config->nat, include_dir);
  }

LcConfigSetIncludeDirP()

LC_EXTERN void LcConfigSetIncludeDirP	(	LC_CFG	config,
		MK_STRN	include_dir )

Non-inline replacement for LcConfigSetIncludeDir …

LcConfigSetIncludeFunc_RT()

enum MkErrorE LcConfigSetIncludeFunc_RT ( MK_RT mkrt, LC_CFG const cfg, LcConfigIncludeCallF fConfigIncludeCall, LC_CBP fConfigIncludeData, LcConfigIncludeFreeF fConfigIncludeFree )

extern

set the __parser__(callback-name) for the include-config-file …

This is the Programming-Language-Micro-Kernel (PLMK) wrapper for LcConfigSetIncludeFuncHide to provide additional capabilities.

See also

LcConfigGetIncludeFunc LcConfigSetIncludeFuncHide

LcConfigSetIncludeFunc : callback signature

#define LcConfigIncludeCallF_ARGS  \
  MK_RT_ARGS struct LcConfigS* const cfg, MK_STRN incDir, MK_STRN path, MK_BFL ret_inout
typedef enum MkErrorE ( MK_DECL *LcConfigIncludeCallF ) ( LcConfigIncludeCallF_ARGS );
 
#define LcConfigIncludeFreeF_ARGS  MK_RT_ARGS struct LcConfigS* const cfg
typedef void ( MK_DECL *LcConfigIncludeFreeF ) ( LcConfigIncludeFreeF_ARGS );

Read more about how to define a service-callback in theLink .

LcConfigSetIncludeFuncHide : documentation

Since v1.7 Specifies the include function func to use when processing include directives …

If func is NULL, the default include function, config_default_include_func, will be reinstated.

The type LcConfigIncludeCallF is a type alias for a function whose signature is:

const char ** func (\RDocLc{LcConfigC} *config, const char *include_dir, const char *path, const char **error)

The function receives the configuration config, the configuration's current include directory include_dir, the argument to the include directive path; and a pointer at which to return an error message error.

On success, the function should return a NULL-terminated array of paths. Any relative paths must be relative to the program's current working directory. The contents of these files will be inlined at the point of inclusion, in the order that the paths appear in the array. Both the array and its elements should be heap allocated; the library will take ownership of and eventually free the strings in the array and the array itself.

On failure, the function should return NULL and set *error to a static error string which should be used as the parse error for the configuration; the library does not take ownership of or free this string.

The default include function, config_default_include_func, simply returns a NULL-terminated array containing either a copy of path if it's an absolute path, or a concatenation of include_dir and path if it's a relative path.

Application-supplied include functions can perform custom tasks like wildcard expansion or variable substitution. For example, consider the include directive:

@include "configs/ *.cfg"

The include function would be invoked with the path 'configs/‌*.cfg' and could do wildcard expansion on that path, returning a list of paths to files with the file extension '.cfg' in the subdirectory 'configs'. Each of these files would then be inlined at the location of the include directive.

Tasks like wildcard expansion and variable substitution are non-trivial to implement and typically require platform-specific code. In the interests of keeping the library as compact and platform-independent as possible, implementations of such include functions are not included.

LcConfigSetIncludeFuncHide()

void LcConfigSetIncludeFuncHide ( LC_CFG config, config_include_fn_t func )

inline

Since v1.7 Specifies the include function func to use when processing include directives …

If func is NULL, the default include function, config_default_include_func, will be reinstated.

The type LcConfigIncludeCallF is a type alias for a function whose signature is:

const char ** func (\RDocLc{LcConfigC} *config, const char *include_dir, const char *path, const char **error)

The function receives the configuration config, the configuration's current include directory include_dir, the argument to the include directive path; and a pointer at which to return an error message error.

On success, the function should return a NULL-terminated array of paths. Any relative paths must be relative to the program's current working directory. The contents of these files will be inlined at the point of inclusion, in the order that the paths appear in the array. Both the array and its elements should be heap allocated; the library will take ownership of and eventually free the strings in the array and the array itself.

On failure, the function should return NULL and set *error to a static error string which should be used as the parse error for the configuration; the library does not take ownership of or free this string.

The default include function, config_default_include_func, simply returns a NULL-terminated array containing either a copy of path if it's an absolute path, or a concatenation of include_dir and path if it's a relative path.

Application-supplied include functions can perform custom tasks like wildcard expansion or variable substitution. For example, consider the include directive:

@include "configs/ *.cfg"

The include function would be invoked with the path 'configs/‌*.cfg' and could do wildcard expansion on that path, returning a list of paths to files with the file extension '.cfg' in the subdirectory 'configs'. Each of these files would then be inlined at the location of the include directive.

Tasks like wildcard expansion and variable substitution are non-trivial to implement and typically require platform-specific code. In the interests of keeping the library as compact and platform-independent as possible, implementations of such include functions are not included.

Definition at line 408 of file LcConfigC_lc.h.

                                                                                      {
    LC_INSTANCE_HDL(config);
    config_set_include_func(config->nat, func);
  }

LcConfigSetIncludeFuncHideP()

LC_EXTERN void LcConfigSetIncludeFuncHideP	(	LC_CFG	config,
		config_include_fn_t	func )

Non-inline replacement for LcConfigSetIncludeFuncHide …

LcConfigSetOption()

void LcConfigSetOption ( LC_CFG config, enum LcConfigOptionsEF option, MK_BOOL flag )

inline

Since v1.7 These functions get and set the given option of the configuration config …

The option is enabled if flag is CONFIG_TRUE and disabled if it is CONFIG_FALSE.

See config_set_options above for the list of available options.

See also

config_get_option

Definition at line 414 of file LcConfigC_lc.h.

                                                                                                {
    LC_INSTANCE_HDL(config);
    config_set_option(config->nat, option, flag);
  }

LcConfigSetOptionP()

LC_EXTERN void LcConfigSetOptionP	(	LC_CFG	config,
		enum LcConfigOptionsEF	option,
		MK_BOOL	flag )

Non-inline replacement for LcConfigSetOption …

LcConfigSetOptions()

void LcConfigSetOptions ( LC_CFG config, enum LcConfigOptionsEF options )

inline

These functions get and set the options for the configuration config …

The options affect how configurations are read and written. The following options are defined:

CONFIG_OPTION_AUTOCONVERT	Turning this option on enables number auto-conversion for the configuration. When this feature is enabled, an attempt to retrieve a floating point setting's value into an integer (or vice versa), or store an integer to a floating point setting's value (or vice versa) will cause the library to silently perform the necessary conversion (possibly leading to loss of data), rather than reporting failure. By default this option is turned off.
CONFIG_OPTION_SEMICOLON_SEPARATORS	This option controls whether a semicolon (';') is output after each setting when the configuration is written to a file or stream. (The semicolon separators are optional in the configuration syntax.) By default this option is turned on.
CONFIG_OPTION_COLON_ASSIGNMENT_FOR_GROUPS	This option controls whether a colon (':') is output between each group setting's name and its value when the configuration is written to a file or stream. If the option is turned off, an equals sign ('=') is output instead. (These tokens are interchangeable in the configuration syntax.) By default this option is turned on.
CONFIG_OPTION_COLON_ASSIGNMENT_FOR_NON_GROUPS	This option controls whether a colon (':') is output between each non-group setting's name and its value when the configuration is written to a file or stream. If the option is turned off, an equals sign ('=') is output instead. (These tokens are interchangeable in the configuration syntax.) By default this option is turned off.
CONFIG_OPTION_OPEN_BRACE_ON_SEPARATE_LINE	This option controls whether an open brace ('{') will be written on its own line when the configuration is written to a file or stream. If the option is turned off, the brace will be written at the end of the previous line. By default this option is turned on.
CONFIG_OPTION_ALLOW_SCIENTIFIC_NOTATION	(Since v1.7) This option controls whether scientific notation may be used as appropriate when writing floating point values (corresponding to printf 'g' format) or should never be used (corresponding to printf 'f' format). By default this option is turned off.
CONFIG_OPTION_FSYNC	(Since v1.7.1) This option controls whether the config_write_file function performs an fsync operation after writing the configuration and before closing the file. By default this option is turned off.
CONFIG_OPTION_ALLOW_OVERRIDES	(Since v1.7.3) This option controls whether duplicate settings override previous settings with the same name. If this option is turned off, duplicate settings are rejected. By default this option is turned off.

See also

config_get_options

Definition at line 420 of file LcConfigC_lc.h.

                                                                                    {
    LC_INSTANCE_HDL(config);
    config_set_options(config->nat, options);
  }

LcConfigSetOptionsP()

LC_EXTERN void LcConfigSetOptionsP	(	LC_CFG	config,
		enum LcConfigOptionsEF	options )

Non-inline replacement for LcConfigSetOptions …

LcConfigSetSettingDeleteFunc_RT()

enum MkErrorE LcConfigSetSettingDeleteFunc_RT ( MK_RT mkrt, LC_CFG const cfg, LcSettingDeleteCallF fSettingDeleteCall, LC_CBP fSettingDeleteData, LcSettingDeleteFreeF fSettingDeleteFree )

extern

set the callback-name for the setting-delete …

This callback is called if a setting is deleted.

Sometimes it is important to be informed about the deletion of a LcSettingC, as the LcSettingC is automatically deleted when the parent structure LcConfigC is deleted.
Internally, the mechanism is used to break the data connection between META and the Target-Programming-Language (TPL).
Previously there was a task for this function in connection with RPC, but this task has been replaced by a generalized mechanism described in MkObjectDeleteCallbackSetup.

The argument for the callback is a handle which was created by MkObjectHandleGet from the LcSettingC.

See also

LcConfigGetSettingDeleteFunc MkObjectDeleteCallbackSetup

LcConfigSetSettingDeleteFunc : callback signature

#define LcSettingDeleteCallF_ARGS  \
  MK_RT_ARGS struct LcConfigS* const cfg, struct LcSettingS* const cfs
typedef enum MkErrorE ( MK_DECL *LcSettingDeleteCallF ) ( LcSettingDeleteCallF_ARGS );
 
#define LcSettingDeleteFreeF_ARGS  MK_RT_ARGS struct LcConfigS* const cfg
typedef void ( MK_DECL *LcSettingDeleteFreeF ) ( LcSettingDeleteFreeF_ARGS );

Read more about how to define a service-callback in theLink .

LcConfigSetTabWidth()

void LcConfigSetTabWidth ( LC_CFG config, MK_I16 width )

inline

These functions, which are implemented as macros, get and set the tab width for the configuration config …

The tab width affects the formatting of the configuration when it is written to a file or stream: each level of nesting is indented by width spaces, or by a single tab character if width is 0. The tab width has no effect on parsing.

Valid tab widths range from 0 to 15. The default tab width is 2.

See also

config_get_tab_width

Definition at line 426 of file LcConfigC_lc.h.

                                                                   {
    LC_INSTANCE_HDL(config);
    config_set_tab_width(config->nat, (MK_U16)width);
  }

LcConfigSetTabWidthP()

LC_EXTERN void LcConfigSetTabWidthP	(	LC_CFG	config,
		MK_I16	width )

Non-inline replacement for LcConfigSetTabWidth …