Support the libconfig native library.
SYNOPSIS
The liblcconfig package is a library for processing configuration files
link:-Lpath -llcconfigor automake:LDADD = liblcconfig.la
The liblcconfig package is a composition of multiple classes defining the Programming-Language-Micro-Kernel (PLMK) :
| object | description |
|---|---|
Lc | the namespace with all liblcconfig specific definitions |
LcAttribute(…) | the interface to access the package specific attribute |
LcClassAttribute(…) | the interface to access the class specific attribute |
LcClassAttribute(Instance,…) | the interface to access the instance specific attribute |
To access all features without Lc prefix use:
#include "LibLcConfig_lc.h"
Using the liblcconfig package ...
orLDADD = path/to/liblcconfig.la
Example from acmds/Makefile.am using libmkkernel.la and libmqmsgque.la:mylib_la_LIBADD = path/to/liblcconfig.la
TABLE OF CONTENTS
- PACKAGE
- Philosophy ,
- CLASS
- LcConfig PACKAGE , LcConfigC , LcSettingC ,
- MISC
- Examples
INTRODUCTION
C-API: LC_C_API - The theConfig API.
License
...
Introduction
liblcconfig is a library for reading, manipulating, and writing structured configuration files. The library features a fully reentrant parser and includes bindings for both the C and C++ programming languages.
The library runs on modern POSIX-compilant systems, such as Linux, Solaris, and Mac OS X (Darwin), as well as on Microsoft Windows 2000/XP and later (with either Microsoft Visual Studio 2005 or later, or the GNU toolchain via the MinGW environment).
Why Another Configuration File Library?
There are several open-source configuration file libraries available as of this writing. This library was written because each of those libraries falls short in one or more ways. The main features of libconfig that set it apart from the other libraries are:
- A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time.
- Both C and C++ bindings, as well as hooks to allow for the creation of wrappers in other languages.
- A simple, structured configuration file format that is more readable and compact than XML and more flexible than the obsolete but prevalent Windows ''INI'' file format.
- A low-footprint implementation (just 37K for the C library and 76K for the C++ library) that is suitable for memory-constrained systems.
- Proper documentation.
Multithreading Issues
liblcconfig is fully reentrant; the functions in the library do not make use of global variables and do not maintain state between successive calls. Therefore two independent configurations may be safely manipulated concurrently by two distinct threads.
liblcconfig is not thread-safe. The library is not aware of the presence of threads and knows nothing about the host system's threading model. Therefore, if an instance of a configuration is to be accessed from multiple threads, it must be suitably protected by synchronization mechanisms like read-write locks or mutexes; the standard rules for safe multithreaded access to shared data must be observed.
liblcconfig is not async-safe. Calls should not be made into the library from signal handlers, because some of the C library routines that it uses may not be async-safe.
liblcconfig is not guaranteed to be cancel-safe. Since it is not aware of the host system's threading model, the library does not contain any thread cancellation points. In most cases this will not be an issue for multithreaded programs. However, be aware that some of the routines in the library (namely those that read/write configurations from/to files or streams) perform I/O using C library routines which may potentially block; whether or not these C library routines are cancel-safe depends on the host system.
Internationalization Issues
liblcconfig does not natively support Unicode configuration files, but string values may contain Unicode text encoded in UTF-8; such strings will be treated as ordinary 8-bit ASCII text by the library. It is the responsibility of the calling program to perform the necessary conversions to/from wide (wchar_t) strings using the wide string conversion functions such as mbsrtowcs() and wcsrtombs() or the iconv() function of the libiconv library.
The textual representation of a floating point value varies by locale. However, the libconfig grammar specifies that floating point values are represented using a period ('.') as the radix symbol; this is consistent with the grammar of most programming languages. When a configuration is read in or written out, libconfig temporarily changes the LC_NUMERIC category of the locale of the calling thread to the ''C'' locale to ensure consistent handling of floating point values regardless of the locale(s) in use by the calling program.
Note that the MinGW environment does not (as of this writing) provide functions for changing the locale of the calling thread. Therefore, when using libconfig in that environment, the calling program is responsible for changing the LC_NUMERIC category of the locale to the "C" locale before reading or writing a configuration.
Configuration Files
liblcconfig supports structured, hierarchical configurations. These configurations can be read from and written to files and manipulated in memory.
A configuration consists of a group of settings, which associate names with values. A value can be one of the following:
- A scalar value: integer, 64-bit integer, floating-point number, boolean, or string
- An array, which is a sequence of scalar values, all of which must have the same type
- A group, which is a collection of settings
- A list, which is a sequence of values of any type, including other lists
Consider the following configuration file for a hypothetical GUI application, which illustrates all of the elements of the configuration file grammar.
Settings can be uniquely identified within the configuration by a path. The path is a dot-separated sequence of names, beginning at a top-level group and ending at the setting itself. Each name in the path is the name of a setting; if the setting has no name because it is an element in a list or array, an integer index in square brackets can be used as the name.
For example, in our hypothetical configuration file, the path to the x setting is application.window.pos.x; the path to the version setting is simply version; and the path to the title setting of the second book in the books list is application.books.[1].title.
The datatype of a value is determined from the format of the value itself. If the value is enclosed in double quotes, it is treated as a string. If it looks like an integer or floating point number, it is treated as such. If it is one of the values TRUE, true, FALSE, or false (or any other mixed-case version of those tokens, e.g., True or FaLsE), it is treated as a boolean. If it consists of a comma-separated list of values enclosed in square brackets, it is treated as an array. And if it consists of a comma-separated list of values enclosed in parentheses, it is treated as a list. Any value which does not meet any of these criteria is considered invalid and results in a parse error.
All names are case-sensitive. They may consist only of alphanumeric characters, dashes ('-'), underscores ('_'), and asterisks ('*'), and must begin with a letter or asterisk. No other characters are allowed.
In C and C++, integer, 64-bit integer, floating point, and string values are mapped to the native types int, long long, double, and const char *, respectively. The boolean type is mapped to int in C and bool in C++.
The following sections describe the elements of the configuration file grammar in additional detail.
Settings
A setting has the form:
name = value ;
or:
name : value ;
The trailing semicolon is optional. Whitespace is not significant.
The value may be a scalar value, an array, a group, or a list.
Groups
A group has the form:
{ settings ... }
Groups can contain any number of settings, but each setting must have a unique name within the group.
Arrays
An array has the form:
[ value, value ... ]
An array may have zero or more elements, but the elements must all be scalar values of the same type.
The last element in an array may be followed by a comma, which will be ignored.
Lists
A list has the form:
( value, value ... )
A list may have zero or more elements, each of which can be a scalar value, an array, a group, or another list.
The last element in a list may be followed by a comma, which will be ignored.
Integer Values
Integers can be represented in one of two ways: as a series of one or more decimal digits ('0' - '9'), with an optional leading sign character ('+' or '-'); or as a hexadecimal value consisting of the characters '0x' followed by a series of one or more hexadecimal digits ('0' - '9', 'A' - 'F', 'a' - 'f'). Additionally, octal notation integers (that is, those having a leading zero with non-zero value) are also allowed.
64-bit Integer Values
Long long (64-bit) integers are represented identically to integers, except that an 'L' character is appended to indicate a 64-bit value. For example, '0L' indicates a 64-bit integer value 0. As of version 1.5 of the library, the trailing 'L' is optional; if the integer value exceeds the range of a 32-bit integer, it will automatically be interpreted as a 64-bit integer.
The integer and 64-bit integer setting types are interchangeable to the extent that a conversion between the corresponding native types would not result in an overflow or underflow. For example, a long long value can be written to a setting that has an integer type, if that value is within the range of an int. This rule applies to every API function or method that reads a value from or writes a value to a setting: if the type conversion would not result in an overflow or underflow, then the call will succeed, and otherwise it will fail. This behavior was not well-defined prior to version 1.7 of the library.
Floating Point Values
Floating point values consist of a series of one or more digits, one decimal point, an optional leading sign character ('+' or '-'), and an optional exponent. An exponent consists of the letter 'E' or 'e', an optional sign character, and a series of one or more digits.
Boolean Values
Boolean values may have one of the following values: 'true', 'false', or any mixed-case variation thereof.
String Values
String values consist of arbitrary text delimited by double quotes. Literal double quotes can be escaped by preceding them with a backslash: '\"'. The escape sequences '\\', '\f', '\n', '\r', and '\t' are also recognized, and have the usual meaning.
In addition, the '\x' escape sequence is supported; this sequence must be followed by exactly two hexadecimal digits, which represent an 8-bit ASCII value. For example, '\xFF' represents the character with ASCII code 0xFF.
No other escape sequences are currently supported.
Adjacent strings are automatically concatenated, as in C/C++ source code. This is useful for formatting very long strings as sequences of shorter strings. For example, the following constructs are equivalent:
"The quick brown fox jumped over the lazy dog."
"The quick brown fox"
" jumped over the lazy dog."
"The quick" /* comment */ " brown fox " // another comment
"jumped over the lazy dog."
Comments
Three types of comments are allowed within a configuration:
- Script-style comments. All text beginning with a '#' character to the end of the line is ignored.
- C-style comments. All text, including line breaks, between a starting '/*' sequence and an ending '*/' sequence is ignored.
- C++-style comments. All text beginning with a '//' sequence to the end of the line is ignored.
As expected, comment delimiters appearing within quoted strings are treated as literal text.
Comments are ignored when the configuration is read in, so they are not treated as part of the configuration. Therefore if the configuration is written back out to a stream, any comments that were present in the original configuration will be lost.
Include Directives
A configuration file may ''include'' the contents of other files using an include directive. This directive has the effect of inlining the contents of the named file(s) at the point of inclusion.
An include directive must appear on its own line in the input. It has the form:
@include "path"
The interpretation of path depends on the currently registered include function. The default include function prepends the include directory, if any, to path, and then interprets the result as a single, literal file path. The application may supply its own include function which does variable substitution, wildcard expansion, or other transformations, returning a list of zero or more paths to files whose contents should be inlined at the point of inclusion.
Any backslashes or double quotes in the path must be escaped as '\\' and '\"', respectively.
For example, consider the following two configuration files:
The resulting configuration will be equivalent to one in which the contents of the file 'quote.cfg' appeared at the point where the include directive is placed.
Include files may be nested to a maximum of 10 levels; exceeding this limit results in a parse error.
When the path argument to an @include directive is a relative path, then it will be interpreted as being relative to the include directory that has been been set by means of ConfigSetIncludeDir. If no include directory has been set, then it will be taken as being relative to the program's current working directory.
Like comments, include directives are not part of the configuration file syntax. They are processed before the configuration itself is parsed. Therefore, they are not preserved when the configuration is written back out to a stream. There is presently no support for programmatically inserting include directives into a configuration.
The C API
This chapter describes the C library API. The type LcConfigC represents a configuration, and the type LcSettingC represents a configuration setting.
The boolean values CONFIG_TRUE and CONFIG_FALSE are macros defined as (1) and (0), respectively.
LcConfig PACKAGE
| LcConfig SETUP | |||
| Cleanup | cleanup liblcconfig internal memory … | ||
| Setup | setup liblcconfig internal memory … | ||
| SetupThreadCallback | callback used to register a new runtime … | ||
| LcConfig ENUM | |||
| enum LcErrorTypeE | error types | ||
| enum LcErrorE | Signals an error and is used as the return value of a function … | ||
| enum LcConfigTypeE | define the data-type of a LcSettingC … | ||
| enum LcConfigOptionsEF | define the configuration-option of a LcConfigC … | ||
| enum LcConfigFormatE | set the format of a LcSettingC … | ||
| LcConfig ERROR | |||
| ConfigErrorToMQ | if a libconfig funtion return a LcErrorE use this function to convert the libconfig-error into the libmkkernel-error … | ||
LcConfig DETAIL
C-API: LcConfig_C_API - LcConfig PACKAGE - the package is the toplevel structure of the liblcconfig …
The liblcconfig package is loaded with:
link:-Lpath -llcconfigor automake:LDADD = liblcconfig.la
and is a composition of one or more package-item and exact one package-main.
The liblcconfig package add the following classes into MkObjectC_C_API :
| Object | C-Short | Description |
|---|---|---|
| LcConfigC | LC_CFG | LcConfigC - the class known as lccfg or Config define the main-configuration-handle … |
| LcSettingC | LC_CFS | LcSettingC - the class known as lccfs or Setting define a single config-setting … |
The liblcconfig package add the following types into MkObjectC_C_API :
ABSTRACT: MkTypeSTT (TypeTypeType = type of a TypeType)
|
|- ABSTRACT: MkSuperTypeSTT (TypeType = type of a Type)
|
|- LcConfigST, LcSettingTLcConfig SETUP
C-API: LcConfig_Setup_C_API - LcConfig PACKAGE - setup library and Programming-Language-Micro-Kernel (PLMK) …
For details about Setup and Cleanup usage refer to MkKernel_Setup_libmkkernel_C_API
(static) void LcCleanup()
top cleanup liblcconfig internal memory … → API: LcCleanup
LcCleanup can only be called once and will be ignored if not called in the same thread as LcSetup. after a call to LcSetup the call to LcCleanup is possible again.
- Attention
- during cleanup objects will be deleted too -> the language interpreter have to be active
- the LcCleanup will call the MkCleanup also.
(static) void LcSetup()
top setup liblcconfig internal memory … → API: LcSetup
LcSetup can only be called once, additional call's will be ignored until a LcCleanup is called.
(static,hide) void LcSetupThreadCallback(LcSetupThreadF call)
top callback used to register a new runtime … → API: LcSetupThreadCallback
read more at: MkRuntimeCallbackAdd
LcConfig ENUM
C-API: LcConfig_Enum_C_API - LcConfig PACKAGE - definition of the enum type …
read more at: MkKernel_Enum_C_API
enum LcConfigFormatE
top set the format of a LcSettingC … → API: LcConfigFormatE
(static) enum MkErrorE LcConfigFormatE_FromInt(MK_I32 const value, enum LcConfigFormatE *value_out)
top return the LcConfigFormatE from integer … → API: LcConfigFormatE_FromInt
(static) MK_I32 LcConfigFormatE_ToInt(enum LcConfigFormatE value)
top return the LcConfigFormatE as integer … → API: LcConfigFormatE_ToInt
(static) MK_STRN LcConfigFormatE_ToString(enum LcConfigFormatE value)
top return the LcConfigFormatE as string … → API: LcConfigFormatE_ToString
enum LcConfigOptionsEF
top define the configuration-option of a LcConfigC … → API: LcConfigOptionsEF
(static) enum MkErrorE LcConfigOptionsEF_FromInt(MK_I32 const value, enum LcConfigOptionsEF *value_out)
top return the LcConfigOptionsEF from integer … → API: LcConfigOptionsEF_FromInt
(static) MK_I32 LcConfigOptionsEF_ToInt(enum LcConfigOptionsEF value)
top return the LcConfigOptionsEF as integer … → API: LcConfigOptionsEF_ToInt
(static) MK_STRN LcConfigOptionsEF_ToString(enum LcConfigOptionsEF value)
top return the LcConfigOptionsEF as string … → API: LcConfigOptionsEF_ToString
enum LcConfigTypeE
top define the data-type of a LcSettingC … → API: LcConfigTypeE
(static) enum MkErrorE LcConfigTypeE_FromInt(MK_I32 const value, enum LcConfigTypeE *value_out)
top return the LcConfigTypeE from integer … → API: LcConfigTypeE_FromInt
(static) MK_I32 LcConfigTypeE_ToInt(enum LcConfigTypeE value)
top return the LcConfigTypeE as integer … → API: LcConfigTypeE_ToInt
(static) MK_STRN LcConfigTypeE_ToString(enum LcConfigTypeE value)
top return the LcConfigTypeE as string … → API: LcConfigTypeE_ToString
enum LcErrorE
top Signals an error and is used as the return value of a function … → API: LcErrorE
(static) enum MkErrorE LcErrorE_FromInt(MK_I32 const value, enum LcErrorE *value_out)
top return the LcErrorE from integer … → API: LcErrorE_FromInt
(static) MK_I32 LcErrorE_ToInt(enum LcErrorE value)
top return the LcErrorE as integer … → API: LcErrorE_ToInt
(static) MK_STRN LcErrorE_ToString(enum LcErrorE value)
top return the LcErrorE as string … → API: LcErrorE_ToString
enum LcErrorTypeE
top error types → API: LcErrorTypeE
(static) enum MkErrorE LcErrorTypeE_FromInt(MK_I32 const value, enum LcErrorTypeE *value_out)
top return the LcErrorTypeE from integer … → API: LcErrorTypeE_FromInt
(static) MK_I32 LcErrorTypeE_ToInt(enum LcErrorTypeE value)
top return the LcErrorTypeE as integer … → API: LcErrorTypeE_ToInt
(static) MK_STRN LcErrorTypeE_ToString(enum LcErrorTypeE value)
top return the LcErrorTypeE as string … → API: LcErrorTypeE_ToString
LcConfig ERROR
C-API: LcConfig_Error_C_API - LcConfig PACKAGE - error handling in liblcconfig …
The error signals the end of an operation with an undesirable result or state.
- The error is defined using the both enum: enum LcErrorE and enum LcErrorTypeE
- In a programming language WITHOUT explicit error handling (eg "C") this value is returned and the subsequent code must process the error, eg with LcErrorE_Check.
- In a programming language WITH explicit error handling (eg "Java"), the error is converted into an exception and the program flow is aborted with an error message.
(static,hide) enum MkErrorE LcConfigErrorToMQ(MK_OBJN const obj, MK_STRN const func, MK_STRN const file, MK_I32 const line)
top if a libconfig funtion return a LcErrorE use this function to convert the libconfig-error into the libmkkernel-error … → API: LcConfigErrorToMQ
LcConfigC
| LcConfigC CLASS | |||
| Define | LcConfigC - low level definition, access and cast … | ||
| Export | LcConfigC - Export class functions … | ||
| Introspection | LcConfigC - Introspection class functions … | ||
| Misc | LcConfigC - Misc class functions … | ||
| LcConfigC TOR | |||
| Create | create a LcConfigC instance … | ||
| Delete | delete a LcConfigC instance … | ||
| LcConfigC SET | |||
| SetDefaultFormat | These functions, which are implemented as macros, get and set the default external format for settings in the configuration config … | ||
| SetFloatPrecision | 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 … | ||
| SetIncludeDir | ConfigSetIncludeDir specifies the include directory, include_dir, relative to which the files specified in '@include' directives will be located for the configuration config … | ||
| SetIncludeFunc | set the __parser__(callback-name) for the include-config-file … | ||
| SetIncludeFuncHide | Since v1.7 Specifies the include function func to use when processing include directives … | ||
| SetOption | Since v1.7 These functions get and set the given option of the configuration config … | ||
| SetOptions | These functions get and set the options for the configuration config … | ||
| SetSettingDeleteFunc | set the __parser__(callback-name) for the setting-delete … | ||
| SetTabWidth | These functions, which are implemented as macros, get and set the tab width for the configuration config … | ||
| LcConfigC GET | |||
| GetDefaultFormat | These functions, which are implemented as macros, get and set the default external format for settings in the configuration config … | ||
| GetFloatPrecision | 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 … | ||
| GetIncludeDir | ConfigSetIncludeDir specifies the include directory, include_dir, relative to which the files specified in '@include' directives will be located for the configuration config … | ||
| GetIncludeFunc | return the __parser__(callback-name) for include-config-file … | ||
| GetOption | Since v1.7 These functions get and set the given option of the configuration config … | ||
| GetOptions | These functions get and set the options for the configuration config … | ||
| GetSettingDeleteFunc | get the __parser__(callback-name) for setting-delete … | ||
| GetTabWidth | These functions, which are implemented as macros, get and set the tab width for the configuration config … | ||
| LcConfigC LOOKUP | |||
| Lookup | This function locates the setting in the configuration config specified by the path path … | ||
| LookupBool | These functions look up the value of the setting in the configuration config specified by the path path … | ||
| LookupFloat | These functions look up the value of the setting in the configuration config specified by the path path … | ||
| LookupInt | These functions look up the value of the setting in the configuration config specified by the path path … | ||
| LookupInt64 | These functions look up the value of the setting in the configuration config specified by the path path … | ||
| LookupString | These functions look up the value of the setting in the configuration config specified by the path path … | ||
| LcConfigC ERROR | |||
| ErrorType | This function, which is implemented as a macro, returns the type of error that occurred during the last call to one of the read or write functions … | ||
| LcConfigC MISC | |||
| Clear | Since v1.7 This function clears the configuration config … | ||
| Log | log the config … | ||
| ReadFile | This function reads and parses a configuration from the file named filename into the configuration object config … | ||
| ReadString | This function reads and parses a configuration from the string str into the configuration object config … | ||
| RootSetting | This function, which is implemented as a macro, returns the root setting for the configuration config … | ||
| WriteFile | This function writes the configuration config to the file named filename … | ||
| WriteString | read the entire configuration cfg into the string val_out … | ||
LcConfigC DETAIL
C-API: LcConfigC_C_API - LcConfigC - the class known as lccfg or Config define the main-configuration-handle …
LcConfigC CLASS
| Cfg | cast a unknown-object into an LcConfigS pointer or NULL if not possible | ||
| CfgCheck | check LcConfigS -> MkObjectS::signature … | ||
| CfgCheckO | check LcConfigS -> MkObjectS::signature … | ||
| CfgN | (const) cast a unknown-object into an LcConfigS pointer or NULL if not possible | ||
| HandleResolve | Handle-Resolve-Slot - return a LcConfigC from netHdl or MK_NULL if invalid… | ||
| HandleGet | Handle-Get-Slot - returns a export-hdl to the LcConfigC useable for external storage | ||
| Instances | get head-instance from linked-list of LcConfigS type … | ||
| Next | get next instance from linked-list of LcConfigS type | ||
| Prev | get previous instance from linked-list of LcConfigS type | ||
| GetNull | Null-Slot - return a LcConfigC typed | ||
LcConfigC CLASS DETAILS
C-API: LcConfigC_Class_C_API - LcConfigC - define the class …
LcConfigC CLASS DEFINE
C-API: LcConfigC_Class_Define_C_API - LcConfigC - low level definition, access and cast …
(static,hide) LC_CFG LcCfg(MK_MNG mng)
top cast a unknown-object into an LcConfigS pointer or NULL if not possible → API: LcCfg
(static,hide) MK_BOOL LcCfgCheck(MK_MNGN mng)
top check LcConfigS -> MkObjectS::signature … → API: LcCfgCheck
- Returns
- TRUE on valid cfg and FALSE an invalid cfg
(static,hide) MK_BOOL LcCfgCheckO(MK_OBJN obj)
top check LcConfigS -> MkObjectS::signature … → API: LcCfgCheckO
- Returns
- TRUE on valid cfg and FALSE an invalid cfg
(static,hide) LC_CFGN LcCfgN(MK_MNGN mng)
top (const) cast a unknown-object into an LcConfigS pointer or NULL if not possible → API: LcCfgN
LcConfigC CLASS EXPORT
LcConfigC - Export class functions …
(static,runtime) LC_CFG LcConfigHandleResolve(MK_HDL const netHdl)
top Handle-Resolve-Slot - return a LcConfigC from netHdl or MK_NULL if invalid… → API: LcConfigHandleResolve_RT
The LcConfigHandleResolve undo the LcConfigHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] netHdl handle former exported with LcConfigHandleGet
- Returns
- the required handle or
MK_NULLif netHdl is invalid
(runtime) MK_HDL LcConfigHandleGet(LC_CFG const cfg)
top Handle-Get-Slot - returns a export-hdl to the LcConfigC useable for external storage → API: LcConfigHandleGet_RT
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the LcConfigHandleResolve.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] cfg Programming-Language-Micro-Kernel (PLMK) instance from config_t
- Returns
- the required export-hdl
LcConfigC CLASS INTROSPECTION
LcConfigC - Introspection class functions …
(static,runtime) LC_CFG LcConfigInstances()
top get head-instance from linked-list of LcConfigS type … → API: LcConfigInstances_RT
The head-instance is the last instance created.
LC_CFG LcConfigNext(LC_CFG const cfg)
top get next instance from linked-list of LcConfigS type → API: LcConfigNext
LC_CFG LcConfigPrev(LC_CFG const cfg)
top get previous instance from linked-list of LcConfigS type → API: LcConfigPrev
LcConfigC CLASS MISC
LcConfigC - Misc class functions …
(static) LC_CFG LcConfigGetNull()
top Null-Slot - return a LcConfigC typed NULL instance … → API: LcConfigGetNull
LcConfigC TOR
C-API: LcConfigC_TOR_C_API - LcConfigC - various functions to create, initialize and destroy …
(constructor,static) LC_CFG LcConfigCreate()
top create a LcConfigC instance … → API: LcConfigCreate
- Parameters
-
[in] type the MkTypeS instance to work on - class-type with base LcConfigS - (default = MK_NULL= LcConfigS)[in] nat external nat pointer - (default: MK_NULL= internal)
- Returns
- instance of LcConfigC or
MK_NULLif setup failed
(destructor,runtime) void LcConfigDelete(LC_CFG const cfg)
top delete a LcConfigC instance … → API: LcConfigDelete_RT
LcConfigC SET
C-API: LcConfigC_Set_C_API - LcConfigC - various functions to set config-data …
void LcConfigSetDefaultFormat(LC_CFG config, enum LcConfigFormatE format)
top These functions, which are implemented as macros, get and set the default external format for settings in the configuration config … → API: LcConfigSetDefaultFormat
If a non-default format has not been set for a setting with SettingSetFormat, this configuration-wide default format will be used instead when that setting is written to a file or stream.
- See also
- ConfigGetDefaultFormat
void LcConfigSetFloatPrecision(LC_CFG config, MK_I16 digits)
top 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 … → API: LcConfigSetFloatPrecision
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
- ConfigGetFloatPrecision
void LcConfigSetIncludeDir(LC_CFG config, MK_STRN include_dir)
top ConfigSetIncludeDir specifies the include directory, include_dir, relative to which the files specified in '@include' directives will be located for the configuration config … → API: LcConfigSetIncludeDir
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.
ConfigGetIncludeDir returns the current include directory for the configuration config, or NULL if none is set.
- See also
- ConfigGetIncludeDir
(runtime) enum MkErrorE LcConfigSetIncludeFunc(LC_CFG const cfg, LcConfigIncludeCallF fConfigIncludeCall, LC_CBP fConfigIncludeData)
top set the __parser__(callback-name) for the include-config-file … → API: LcConfigSetIncludeFunc_RT
This is the Programming-Language-Micro-Kernel (PLMK) wrapper for LcConfigSetIncludeFuncHide to provide additional capabilities.
LcConfigSetIncludeFunc: callback signature- #define LcConfigIncludeCallF_ARGS \MK_RT_ARGS struct LcConfigS* const cfg, MK_STRN incDir, MK_STRN path, MK_BFL ret_inout#define LcConfigIncludeFreeF_ARGS MK_RT_ARGS struct LcConfigS* const cfg
Read more about how to define a service-callback in theLink .
LcConfigSetIncludeFuncHide: documentationSince 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 aNULL-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 returnNULLand 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 aNULL-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.
(hide) void LcConfigSetIncludeFuncHide(LC_CFG config, config_include_fn_t func)
top Since v1.7 Specifies the include function func to use when processing include directives … → API: LcConfigSetIncludeFuncHide
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:
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.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.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:
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.
void LcConfigSetOption(LC_CFG config, enum LcConfigOptionsEF option, MK_BOOL flag)
top Since v1.7 These functions get and set the given option of the configuration config … → API: LcConfigSetOption
The option is enabled if flag is CONFIG_TRUE and disabled if it is CONFIG_FALSE.
See ConfigSetOptions above for the list of available options.
- See also
- ConfigGetOption
void LcConfigSetOptions(LC_CFG config, enum LcConfigOptionsEF options)
top These functions get and set the options for the configuration config … → API: LcConfigSetOptions
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 |
| CONFIG_OPTION_FSYNC | (Since v1.7.1) This option controls whether the ConfigWriteFile 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
- ConfigGetOptions
(runtime) enum MkErrorE LcConfigSetSettingDeleteFunc(LC_CFG const cfg, LcSettingDeleteCallF fSettingDeleteCall, LC_CBP fSettingDeleteData)
top set the __parser__(callback-name) for the setting-delete … → API: LcConfigSetSettingDeleteFunc_RT
This is the Programming-Language-Micro-Kernel (PLMK) wrapper for LcSettingSetHookHide to provide additional capabilities.
LcConfigSetSettingDeleteFunc: callback signature- #define LcSettingDeleteCallF_ARGS \MK_RT_ARGS struct LcConfigS* const cfg, struct LcSettingS* const cfs#define LcSettingDeleteFreeF_ARGS MK_RT_ARGS struct LcConfigS* const cfg
Read more about how to define a service-callback in theLink .
LcSettingSetHookHide: documentationThese functions make it possible to attach arbitrary data to each setting structure, for instance a ''wrapper'' or ''peer'' object written in another programming language …
The destructor function, if one has been supplied via a call to config_set_destructor, will be called by the library to dispose of this data when the setting itself is destroyed. There is no default destructor.
- See also
- config_setting_get_hook
void LcConfigSetTabWidth(LC_CFG config, MK_I16 width)
top These functions, which are implemented as macros, get and set the tab width for the configuration config … → API: LcConfigSetTabWidth
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
- ConfigGetTabWidth
LcConfigC GET
C-API: LcConfigC_Get_C_API - LcConfigC - various functions to get config-data …
enum LcConfigFormatE LcConfigGetDefaultFormat(LC_CFGN config)
top These functions, which are implemented as macros, get and set the default external format for settings in the configuration config … → API: LcConfigGetDefaultFormat
If a non-default format has not been set for a setting with SettingSetFormat, this configuration-wide default format will be used instead when that setting is written to a file or stream.
- See also
- ConfigSetDefaultFormat
MK_I16 LcConfigGetFloatPrecision(LC_CFGN config)
top 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 … → API: LcConfigGetFloatPrecision
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
- ConfigSetFloatPrecision
MK_STRN LcConfigGetIncludeDir(LC_CFGN config)
top ConfigSetIncludeDir specifies the include directory, include_dir, relative to which the files specified in '@include' directives will be located for the configuration config … → API: LcConfigGetIncludeDir
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.
ConfigGetIncludeDir returns the current include directory for the configuration config, or NULL if none is set.
- See also
- ConfigSetIncludeDir
(hide) MK_PTR LcConfigGetIncludeFunc(LC_CFG const cfg)
top return the __parser__(callback-name) for include-config-file … → API: LcConfigGetIncludeFunc
- See also
- LcConfigSetIncludeFunc
MK_BOOL LcConfigGetOption(LC_CFGN config, enum LcConfigOptionsEF option)
top Since v1.7 These functions get and set the given option of the configuration config … → API: LcConfigGetOption
The option is enabled if flag is CONFIG_TRUE and disabled if it is CONFIG_FALSE.
See ConfigSetOptions above for the list of available options.
- See also
- ConfigSetOption
enum LcConfigOptionsEF LcConfigGetOptions(LC_CFGN config)
top These functions get and set the options for the configuration config … → API: LcConfigGetOptions
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 |
| CONFIG_OPTION_FSYNC | (Since v1.7.1) This option controls whether the ConfigWriteFile 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
- ConfigSetOptions
(hide) MK_PTR LcConfigGetSettingDeleteFunc(LC_CFG const cfg)
top get the __parser__(callback-name) for setting-delete … → API: LcConfigGetSettingDeleteFunc
- See also
- LcConfigSetSettingDeleteFunc
config_setting_get_hook documentation
These functions make it possible to attach arbitrary data to each setting structure, for instance a ''wrapper'' or ''peer'' object written in another programming language …
The destructor function, if one has been supplied via a call to config_set_destructor, will be called by the library to dispose of this data when the setting itself is destroyed. There is no default destructor.
- See also
- config_setting_set_hook
MK_I16 LcConfigGetTabWidth(LC_CFGN config)
top These functions, which are implemented as macros, get and set the tab width for the configuration config … → API: LcConfigGetTabWidth
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
- ConfigSetTabWidth
LcConfigC LOOKUP
C-API: LcConfigC_Lookup_C_API - LcConfigC - various functions to lookup config-data …
LC_CFS LcConfigLookup(LC_CFGN config, MK_STRN path)
top This function locates the setting in the configuration config specified by the path path … → API: LcConfigLookup
It returns a pointer to the LcSettingC structure on success, or NULL if the setting was not found.
enum MkErrorE LcConfigLookupBool(LC_CFGN config, MK_STRN path, MK_BOOL *value_out)
top These functions look up the value of the setting in the configuration config specified by the path path … → API: LcConfigLookupBool
They store the value of the setting at value and return CONFIG_TRUE on success. If the setting was not found or if the type of the value did not match the type requested, they leave the data pointed to by value unmodified and return CONFIG_FALSE.
Storage for the string returned by ConfigLookupString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
enum MkErrorE LcConfigLookupFloat(LC_CFGN config, MK_STRN path, MK_DBL *value_out)
top These functions look up the value of the setting in the configuration config specified by the path path … → API: LcConfigLookupFloat
They store the value of the setting at value and return CONFIG_TRUE on success. If the setting was not found or if the type of the value did not match the type requested, they leave the data pointed to by value unmodified and return CONFIG_FALSE.
Storage for the string returned by ConfigLookupString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
enum MkErrorE LcConfigLookupInt(LC_CFGN config, MK_STRN path, MK_I32 *value_out)
top These functions look up the value of the setting in the configuration config specified by the path path … → API: LcConfigLookupInt
They store the value of the setting at value and return CONFIG_TRUE on success. If the setting was not found or if the type of the value did not match the type requested, they leave the data pointed to by value unmodified and return CONFIG_FALSE.
Storage for the string returned by ConfigLookupString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
enum MkErrorE LcConfigLookupInt64(LC_CFGN config, MK_STRN path, MK_I64 *value_out)
top These functions look up the value of the setting in the configuration config specified by the path path … → API: LcConfigLookupInt64
They store the value of the setting at value and return CONFIG_TRUE on success. If the setting was not found or if the type of the value did not match the type requested, they leave the data pointed to by value unmodified and return CONFIG_FALSE.
Storage for the string returned by ConfigLookupString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
enum MkErrorE LcConfigLookupString(LC_CFGN config, MK_STRN path, MK_STRN *value_out)
top These functions look up the value of the setting in the configuration config specified by the path path … → API: LcConfigLookupString
They store the value of the setting at value and return CONFIG_TRUE on success. If the setting was not found or if the type of the value did not match the type requested, they leave the data pointed to by value unmodified and return CONFIG_FALSE.
Storage for the string returned by ConfigLookupString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
LcConfigC ERROR
C-API: LcConfigC_Error_C_API - LcConfigC - dealing with a native-error …
enum LcErrorTypeE LcConfigErrorType(LC_CFGN config)
top This function, which is implemented as a macro, returns the type of error that occurred during the last call to one of the read or write functions … → API: LcConfigErrorType
The LcErrorTypeE type is an enumeration with the following values: CONFIG_ERR_NONE, CONFIG_ERR_FILE_IO, CONFIG_ERR_PARSE. These represent success, a file I/O error, and a parsing error, respectively.
LcConfigC MISC
C-API: LcConfigC_Misc_C_API - LcConfigC - various functions to perform misc operations …
void LcConfigClear(LC_CFG config)
top Since v1.7 This function clears the configuration config … → API: LcConfigClear
All child settings of the root setting are recursively destroyed. All other attributes of the configuration are left unchanged.
(runtime) void LcConfigLog(LC_CFGN const cfg, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)
top log the config … → API: LcConfigLog_RT
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] cfg Programming-Language-Micro-Kernel (PLMK) instance from config_t [in] fmtobj managed object used to format the log-message (default= MK_NULL→ use default-format)[in] debug the debug levelfrom MkRuntimeS::debug, use0 <= debug <= 9(default=0)[in] callfunc a user-defined postfix to identify the calling function or the environment (default= name-of-function)[in] lvl a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default= 0)
enum MkErrorE LcConfigReadFile(LC_CFG config, MK_STRN filename)
top This function reads and parses a configuration from the file named filename into the configuration object config … → API: LcConfigReadFile
It returns CONFIG_TRUE on success, or CONFIG_FALSE on failure; the config_error_text and config_error_line functions, described below, can be used to obtain information about the error.
enum MkErrorE LcConfigReadString(LC_CFG config, MK_STRN str)
top This function reads and parses a configuration from the string str into the configuration object config … → API: LcConfigReadString
It returns CONFIG_TRUE on success, or CONFIG_FALSE on failure; the config_error_text and config_error_line functions, described below, can be used to obtain information about the error.
LC_CFS LcConfigRootSetting(LC_CFGN config)
top This function, which is implemented as a macro, returns the root setting for the configuration config … → API: LcConfigRootSetting
The root setting is a group.
enum MkErrorE LcConfigWriteFile(LC_CFG config, MK_STRN filename)
top This function writes the configuration config to the file named filename … → API: LcConfigWriteFile
It returns CONFIG_TRUE on success, or CONFIG_FALSE on failure.
(runtime) enum MkErrorE LcConfigWriteString(LC_CFGN const cfg, MK_STRN *val_out)
top read the entire configuration cfg into the string val_out … → API: LcConfigWriteString_RT
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] cfg Programming-Language-Micro-Kernel (PLMK) instance from config_t [out] val_out the entire configuration as string - value owed by (runtime) enum MkErrorE LcConfigWriteString(LC_CFGN const cfg, MK_STRN *val_out).
- Returns
- The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk
LcSettingC
| LcSettingC CLASS | |||
| Define | LcSettingC - low level definition, access and cast … | ||
| Export | LcSettingC - Export class functions … | ||
| Introspection | LcSettingC - Introspection class functions … | ||
| Misc | LcSettingC - Misc class functions … | ||
| LcSettingC TOR | |||
| Add | This function adds a new child setting or element to the setting parent, which must be a group, array, or list … | ||
| GetConfig | addon - return the LcConfigC from the LcSettingC … | ||
| LcSettingC SET | |||
| SetBool | These functions set the value of the given setting to value … | ||
| SetBoolElem | These functions set the value at the specified index index in the setting setting to value … | ||
| SetFloat | These functions set the value of the given setting to value … | ||
| SetFloatElem | These functions set the value at the specified index index in the setting setting to value … | ||
| SetFormat | These functions get and set the external format for the setting setting … | ||
| SetHookHide | These functions make it possible to attach arbitrary data to each setting structure, for instance a ''wrapper'' or ''peer'' object written in another programming language … | ||
| SetInt | These functions set the value of the given setting to value … | ||
| SetInt64 | These functions set the value of the given setting to value … | ||
| SetInt64Elem | These functions set the value at the specified index index in the setting setting to value … | ||
| SetIntElem | These functions set the value at the specified index index in the setting setting to value … | ||
| SetString | These functions set the value of the given setting to value … | ||
| SetStringElem | These functions set the value at the specified index index in the setting setting to value … | ||
| LcSettingC GET | |||
| GetBool | These functions return the value of the given setting … | ||
| GetBoolElem | These functions return the value at the specified index index in the setting setting … | ||
| GetElem | This function fetches the element at the given index index in the setting setting, which must be an array, list, or group … | ||
| GetFloat | These functions return the value of the given setting … | ||
| GetFloatElem | These functions return the value at the specified index index in the setting setting … | ||
| GetFormat | These functions get and set the external format for the setting setting … | ||
| GetHookHide | These functions make it possible to attach arbitrary data to each setting structure, for instance a ''wrapper'' or ''peer'' object written in another programming language … | ||
| GetInt | These functions return the value of the given setting … | ||
| GetInt64 | These functions return the value of the given setting … | ||
| GetInt64Elem | These functions return the value at the specified index index in the setting setting … | ||
| GetIntElem | These functions return the value at the specified index index in the setting setting … | ||
| GetMember | This function fetches the child setting named name from the group setting … | ||
| GetString | These functions return the value of the given setting … | ||
| GetStringElem | These functions return the value at the specified index index in the setting setting … | ||
| LcSettingC IS | |||
| IsAggregate | These convenience functions, some of which are implemented as macros, test if the setting setting is of an aggregate type (a group, array, or list), of a scalar type (integer, 64-bit integer, floating point, boolean, or string), and of a number (integer, 64-bit integer, or floating point), respectively … | ||
| IsArray | These convenience functions, which are implemented as macros, test if the setting setting is of a given type … | ||
| IsGroup | These convenience functions, which are implemented as macros, test if the setting setting is of a given type … | ||
| IsList | These convenience functions, which are implemented as macros, test if the setting setting is of a given type … | ||
| IsNumber | These convenience functions, some of which are implemented as macros, test if the setting setting is of an aggregate type (a group, array, or list), of a scalar type (integer, 64-bit integer, floating point, boolean, or string), and of a number (integer, 64-bit integer, or floating point), respectively … | ||
| IsRoot | This function returns CONFIG_TRUE if the given setting is the root setting, and CONFIG_FALSE otherwise … | ||
| IsScalar | These convenience functions, some of which are implemented as macros, test if the setting setting is of an aggregate type (a group, array, or list), of a scalar type (integer, 64-bit integer, floating point, boolean, or string), and of a number (integer, 64-bit integer, or floating point), respectively … | ||
| LcSettingC LOOKUP | |||
| Lookup | This function locates a setting by a path path relative to the setting setting … | ||
| LookupAll | addon - read an entire configuration below setting into MkBufferListC … | ||
| LookupBool | These functions look up the value of the child setting named name of the setting setting … | ||
| LookupFloat | These functions look up the value of the child setting named name of the setting setting … | ||
| LookupInt | These functions look up the value of the child setting named name of the setting setting … | ||
| LookupInt64 | These functions look up the value of the child setting named name of the setting setting … | ||
| LookupString | These functions look up the value of the child setting named name of the setting setting … | ||
| LcSettingC MISC | |||
| AddIfNotExists | addon - add name with type only if not exists in the setting … | ||
| Exists | addon - return true if name exists in the setting otherwise false … | ||
| Index | This function returns the index of the given setting within its parent setting … | ||
| Length | This function returns the number of settings in a group, or the number of elements in a list or array … | ||
| Log | log the setting … | ||
| Name | This function returns the name of the given setting, or NULL if the setting has no name … | ||
| Parent | This function returns the parent setting of the given setting, or NULL if setting is the root setting … | ||
| Remove | This function removes and destroys the setting named name from the parent setting parent, which must be a group … | ||
| RemoveElem | This function removes the child setting at the given index index from the setting parent, which must be a group, list, or array … | ||
| SourceFile | This function returns the name of the file from which the setting setting was read, or NULL if the setting was not read from a file … | ||
| SourceLine | This function returns the line number of the configuration file or stream at which the setting setting was read, or 0 if no line number is available … | ||
| Type | This function returns the type of the given setting … | ||
LcSettingC DETAIL
C-API: LcSettingC_C_API - LcSettingC - the class known as lccfs or Setting define a single config-setting …
LcSettingC CLASS
| Cfs | cast a unknown-object into an LcSettingS pointer or NULL if not possible | ||
| CfsCheck | check LcSettingS -> MkObjectS::signature … | ||
| CfsCheckO | check LcSettingS -> MkObjectS::signature … | ||
| CfsN | (const) cast a unknown-object into an LcSettingS pointer or NULL if not possible | ||
| HandleResolve | Handle-Resolve-Slot - return a LcSettingC from netHdl or MK_NULL if invalid… | ||
| HandleGet | Handle-Get-Slot - returns a export-hdl to the LcSettingC useable for external storage | ||
LcSettingC CLASS INTROSPECTION
| Instances | get head-instance from linked-list of LcSettingS type … | ||
| Next | get next instance from linked-list of LcSettingS type | ||
| Prev | get previous instance from linked-list of LcSettingS type | ||
| GetNull | Null-Slot - return a LcSettingC typed | ||
LcSettingC CLASS DETAILS
C-API: LcSettingC_Class_C_API - LcSettingC - define the class …
LcSettingC CLASS DEFINE
C-API: LcSettingC_Class_Define_C_API - LcSettingC - low level definition, access and cast …
(static,hide) LC_CFS LcCfs(MK_MNG mng)
top cast a unknown-object into an LcSettingS pointer or NULL if not possible → API: LcCfs
(static,hide) MK_BOOL LcCfsCheck(MK_MNGN mng)
top check LcSettingS -> MkObjectS::signature … → API: LcCfsCheck
- Returns
- TRUE on valid cfs and FALSE an invalid cfs
(static,hide) MK_BOOL LcCfsCheckO(MK_OBJN obj)
top check LcSettingS -> MkObjectS::signature … → API: LcCfsCheckO
- Returns
- TRUE on valid cfs and FALSE an invalid cfs
(static,hide) LC_CFSN LcCfsN(MK_MNGN mng)
top (const) cast a unknown-object into an LcSettingS pointer or NULL if not possible → API: LcCfsN
LcSettingC CLASS EXPORT
LcSettingC - Export class functions …
(static,runtime) LC_CFS LcSettingHandleResolve(MK_HDL const netHdl)
top Handle-Resolve-Slot - return a LcSettingC from netHdl or MK_NULL if invalid… → API: LcSettingHandleResolve_RT
The LcSettingHandleResolve undo the LcSettingHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] netHdl handle former exported with LcSettingHandleGet
- Returns
- the required handle or
MK_NULLif netHdl is invalid
(runtime) MK_HDL LcSettingHandleGet(LC_CFS const cfs)
top Handle-Get-Slot - returns a export-hdl to the LcSettingC useable for external storage → API: LcSettingHandleGet_RT
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the LcSettingHandleResolve.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] cfs Programming-Language-Micro-Kernel (PLMK) instance from config_setting_t
- Returns
- the required export-hdl
LcSettingC CLASS INTROSPECTION
LcSettingC - Introspection class functions …
(static,runtime) LC_CFS LcSettingInstances()
top get head-instance from linked-list of LcSettingS type … → API: LcSettingInstances_RT
The head-instance is the last instance created.
LC_CFS LcSettingNext(LC_CFS const cfs)
top get next instance from linked-list of LcSettingS type → API: LcSettingNext
LC_CFS LcSettingPrev(LC_CFS const cfs)
top get previous instance from linked-list of LcSettingS type → API: LcSettingPrev
LcSettingC CLASS MISC
LcSettingC - Misc class functions …
(static) LC_CFS LcSettingGetNull()
top Null-Slot - return a LcSettingC typed NULL instance … → API: LcSettingGetNull
LcSettingC TOR
C-API: LcSettingC_TOR_C_API - LcSettingC - various functions to create, initialize and destroy …
(constructor) LC_CFS LcSettingAdd(LC_CFS parent, MK_STRN name, enum LcConfigTypeE __type)
top This function adds a new child setting or element to the setting parent, which must be a group, array, or list … → API: LcSettingAdd
If parent is an array or list, the name parameter is ignored and may be NULL.
The function returns the new setting on success, or NULL if parent is not a group, array, or list; or if there is already a child setting of parent named name; or if type is invalid. If type is a scalar type, the new setting will have a default value of 0, 0.0, false, or NULL, as appropriate.
LC_CFG LcSettingGetConfig(LC_CFSN setting)
top addon - return the LcConfigC from the LcSettingC … → API: LcSettingGetConfig
LcSettingC SET
C-API: LcSettingC_Set_C_API - LcSettingC - various functions to set date into a setting …
enum MkErrorE LcSettingSetBool(LC_CFS setting, MK_BOOL value)
top These functions set the value of the given setting to value … → API: LcSettingSetBool
On success, they return CONFIG_TRUE. If the setting does not match the type of the value, they return CONFIG_FALSE. SettingSetString makes a copy of the passed string value, so it may be subsequently freed or modified by the caller without affecting the value of the setting.
LC_CFS LcSettingSetBoolElem(LC_CFS setting, MK_I32 idx, MK_I32 value)
top These functions set the value at the specified index index in the setting setting to value … → API: LcSettingSetBoolElem
If index is negative, a new element is added to the end of the array or list. On success, these functions return a pointer to the setting representing the element. If the setting is not an array or list, or if the setting is an array and the type of the array does not match the type of the value, or if index is out of range, they return NULL. SettingSetStringElem makes a copy of the passed string value, so it may be subsequently freed or modified by the caller without affecting the value of the setting.
enum MkErrorE LcSettingSetFloat(LC_CFS setting, MK_DBL value)
top These functions set the value of the given setting to value … → API: LcSettingSetFloat
On success, they return CONFIG_TRUE. If the setting does not match the type of the value, they return CONFIG_FALSE. SettingSetString makes a copy of the passed string value, so it may be subsequently freed or modified by the caller without affecting the value of the setting.
LC_CFS LcSettingSetFloatElem(LC_CFS setting, MK_I32 idx, MK_DBL value)
top These functions set the value at the specified index index in the setting setting to value … → API: LcSettingSetFloatElem
If index is negative, a new element is added to the end of the array or list. On success, these functions return a pointer to the setting representing the element. If the setting is not an array or list, or if the setting is an array and the type of the array does not match the type of the value, or if index is out of range, they return NULL. SettingSetStringElem makes a copy of the passed string value, so it may be subsequently freed or modified by the caller without affecting the value of the setting.
enum MkErrorE LcSettingSetFormat(LC_CFS setting, enum LcConfigFormatE format)
top These functions get and set the external format for the setting setting … → API: LcSettingSetFormat
The format must be one of the constants CONFIG_FORMAT_DEFAULT or CONFIG_FORMAT_HEX. All settings support the CONFIG_FORMAT_DEFAULT format. The CONFIG_FORMAT_HEX format specifies hexadecimal formatting for integer values, and hence only applies to settings of type CONFIG_TYPE_INT and CONFIG_TYPE_INT64. If format is invalid for the given setting, it is ignored.
If a non-default format has not been set for the setting, SettingGetFormat returns the default format for the configuration, as set by ConfigSetDefaultFormat.
SettingSetFormat returns CONFIG_TRUE on success and CONFIG_FALSE on failure.
- See also
- SettingGetFormat
(hide) void LcSettingSetHookHide(LC_CFS setting, MK_PTR hook)
top These functions make it possible to attach arbitrary data to each setting structure, for instance a ''wrapper'' or ''peer'' object written in another programming language … → API: LcSettingSetHookHide
The destructor function, if one has been supplied via a call to config_set_destructor, will be called by the library to dispose of this data when the setting itself is destroyed. There is no default destructor.
- See also
- config_setting_get_hook
enum MkErrorE LcSettingSetInt(LC_CFS setting, MK_I32 value)
top These functions set the value of the given setting to value … → API: LcSettingSetInt
On success, they return CONFIG_TRUE. If the setting does not match the type of the value, they return CONFIG_FALSE. SettingSetString makes a copy of the passed string value, so it may be subsequently freed or modified by the caller without affecting the value of the setting.
enum MkErrorE LcSettingSetInt64(LC_CFS setting, MK_I64 value)
top These functions set the value of the given setting to value … → API: LcSettingSetInt64
On success, they return CONFIG_TRUE. If the setting does not match the type of the value, they return CONFIG_FALSE. SettingSetString makes a copy of the passed string value, so it may be subsequently freed or modified by the caller without affecting the value of the setting.
LC_CFS LcSettingSetInt64Elem(LC_CFS setting, MK_I32 idx, MK_I64 value)
top These functions set the value at the specified index index in the setting setting to value … → API: LcSettingSetInt64Elem
If index is negative, a new element is added to the end of the array or list. On success, these functions return a pointer to the setting representing the element. If the setting is not an array or list, or if the setting is an array and the type of the array does not match the type of the value, or if index is out of range, they return NULL. SettingSetStringElem makes a copy of the passed string value, so it may be subsequently freed or modified by the caller without affecting the value of the setting.
LC_CFS LcSettingSetIntElem(LC_CFS setting, MK_I32 idx, MK_I32 value)
top These functions set the value at the specified index index in the setting setting to value … → API: LcSettingSetIntElem
If index is negative, a new element is added to the end of the array or list. On success, these functions return a pointer to the setting representing the element. If the setting is not an array or list, or if the setting is an array and the type of the array does not match the type of the value, or if index is out of range, they return NULL. SettingSetStringElem makes a copy of the passed string value, so it may be subsequently freed or modified by the caller without affecting the value of the setting.
enum MkErrorE LcSettingSetString(LC_CFS setting, MK_STRN value)
top These functions set the value of the given setting to value … → API: LcSettingSetString
On success, they return CONFIG_TRUE. If the setting does not match the type of the value, they return CONFIG_FALSE. SettingSetString makes a copy of the passed string value, so it may be subsequently freed or modified by the caller without affecting the value of the setting.
LC_CFS LcSettingSetStringElem(LC_CFS setting, MK_I32 idx, MK_STRN value)
top These functions set the value at the specified index index in the setting setting to value … → API: LcSettingSetStringElem
If index is negative, a new element is added to the end of the array or list. On success, these functions return a pointer to the setting representing the element. If the setting is not an array or list, or if the setting is an array and the type of the array does not match the type of the value, or if index is out of range, they return NULL. SettingSetStringElem makes a copy of the passed string value, so it may be subsequently freed or modified by the caller without affecting the value of the setting.
LcSettingC GET
C-API: LcSettingC_Get_C_API - LcSettingC - various functions to get data from a setting …
MK_BOOL LcSettingGetBool(LC_CFSN setting)
top These functions return the value of the given setting … → API: LcSettingGetBool
If the type of the setting does not match the type requested, a 0 or NULL value is returned. Storage for the string returned by SettingGetString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
MK_BOOL LcSettingGetBoolElem(LC_CFSN setting, MK_I32 idx)
top These functions return the value at the specified index index in the setting setting … → API: LcSettingGetBoolElem
If the setting is not an array or list, or if the type of the element does not match the type requested, or if index is out of range, they return 0 or NULL. Storage for the string returned by SettingGetStringElem is managed by the library and released automatically when the setting is destroyed or when its value is changed; the string must not be freed by the caller.
LC_CFS LcSettingGetElem(LC_CFSN setting, MK_I32 idx)
top This function fetches the element at the given index index in the setting setting, which must be an array, list, or group … → API: LcSettingGetElem
It returns the requested setting on success, or NULL if index is out of range or if setting is not an array, list, or group.
MK_DBL LcSettingGetFloat(LC_CFSN setting)
top These functions return the value of the given setting … → API: LcSettingGetFloat
If the type of the setting does not match the type requested, a 0 or NULL value is returned. Storage for the string returned by SettingGetString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
MK_DBL LcSettingGetFloatElem(LC_CFSN setting, MK_I32 idx)
top These functions return the value at the specified index index in the setting setting … → API: LcSettingGetFloatElem
If the setting is not an array or list, or if the type of the element does not match the type requested, or if index is out of range, they return 0 or NULL. Storage for the string returned by SettingGetStringElem is managed by the library and released automatically when the setting is destroyed or when its value is changed; the string must not be freed by the caller.
enum LcConfigFormatE LcSettingGetFormat(LC_CFSN setting)
top These functions get and set the external format for the setting setting … → API: LcSettingGetFormat
The format must be one of the constants CONFIG_FORMAT_DEFAULT or CONFIG_FORMAT_HEX. All settings support the CONFIG_FORMAT_DEFAULT format. The CONFIG_FORMAT_HEX format specifies hexadecimal formatting for integer values, and hence only applies to settings of type CONFIG_TYPE_INT and CONFIG_TYPE_INT64. If format is invalid for the given setting, it is ignored.
If a non-default format has not been set for the setting, SettingGetFormat returns the default format for the configuration, as set by ConfigSetDefaultFormat.
SettingSetFormat returns CONFIG_TRUE on success and CONFIG_FALSE on failure.
- See also
- SettingSetFormat
(hide) MK_PTR LcSettingGetHookHide(LC_CFSN setting)
top These functions make it possible to attach arbitrary data to each setting structure, for instance a ''wrapper'' or ''peer'' object written in another programming language … → API: LcSettingGetHookHide
The destructor function, if one has been supplied via a call to config_set_destructor, will be called by the library to dispose of this data when the setting itself is destroyed. There is no default destructor.
- See also
- config_setting_set_hook
MK_I32 LcSettingGetInt(LC_CFSN setting)
top These functions return the value of the given setting … → API: LcSettingGetInt
If the type of the setting does not match the type requested, a 0 or NULL value is returned. Storage for the string returned by SettingGetString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
MK_I64 LcSettingGetInt64(LC_CFSN setting)
top These functions return the value of the given setting … → API: LcSettingGetInt64
If the type of the setting does not match the type requested, a 0 or NULL value is returned. Storage for the string returned by SettingGetString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
MK_I64 LcSettingGetInt64Elem(LC_CFSN setting, MK_I32 idx)
top These functions return the value at the specified index index in the setting setting … → API: LcSettingGetInt64Elem
If the setting is not an array or list, or if the type of the element does not match the type requested, or if index is out of range, they return 0 or NULL. Storage for the string returned by SettingGetStringElem is managed by the library and released automatically when the setting is destroyed or when its value is changed; the string must not be freed by the caller.
MK_I32 LcSettingGetIntElem(LC_CFSN setting, MK_I32 idx)
top These functions return the value at the specified index index in the setting setting … → API: LcSettingGetIntElem
If the setting is not an array or list, or if the type of the element does not match the type requested, or if index is out of range, they return 0 or NULL. Storage for the string returned by SettingGetStringElem is managed by the library and released automatically when the setting is destroyed or when its value is changed; the string must not be freed by the caller.
LC_CFS LcSettingGetMember(LC_CFSN setting, MK_STRN name)
top This function fetches the child setting named name from the group setting … → API: LcSettingGetMember
It returns the requested setting on success, or NULL if the setting was not found or if setting is not a group.
MK_STRN LcSettingGetString(LC_CFSN setting)
top These functions return the value of the given setting … → API: LcSettingGetString
If the type of the setting does not match the type requested, a 0 or NULL value is returned. Storage for the string returned by SettingGetString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
MK_STRN LcSettingGetStringElem(LC_CFSN setting, MK_I32 idx)
top These functions return the value at the specified index index in the setting setting … → API: LcSettingGetStringElem
If the setting is not an array or list, or if the type of the element does not match the type requested, or if index is out of range, they return 0 or NULL. Storage for the string returned by SettingGetStringElem is managed by the library and released automatically when the setting is destroyed or when its value is changed; the string must not be freed by the caller.
LcSettingC IS
C-API: LcSettingC_Is_C_API - LcSettingC - various functions to check a setting …
MK_BOOL LcSettingIsAggregate(LC_CFSN setting)
top These convenience functions, some of which are implemented as macros, test if the setting setting is of an aggregate type (a group, array, or list), of a scalar type (integer, 64-bit integer, floating point, boolean, or string), and of a number (integer, 64-bit integer, or floating point), respectively … → API: LcSettingIsAggregate
They return CONFIG_TRUE or CONFIG_FALSE.
- See also
- SettingIsNumber, SettingIsScalar
MK_BOOL LcSettingIsArray(LC_CFSN setting)
top These convenience functions, which are implemented as macros, test if the setting setting is of a given type … → API: LcSettingIsArray
They return CONFIG_TRUE or CONFIG_FALSE.
- See also
- SettingIsGroup, SettingIsList
MK_BOOL LcSettingIsGroup(LC_CFSN setting)
top These convenience functions, which are implemented as macros, test if the setting setting is of a given type … → API: LcSettingIsGroup
They return CONFIG_TRUE or CONFIG_FALSE.
- See also
- SettingIsArray, SettingIsList
MK_BOOL LcSettingIsList(LC_CFSN setting)
top These convenience functions, which are implemented as macros, test if the setting setting is of a given type … → API: LcSettingIsList
They return CONFIG_TRUE or CONFIG_FALSE.
- See also
- SettingIsArray, SettingIsGroup
MK_BOOL LcSettingIsNumber(LC_CFSN setting)
top These convenience functions, some of which are implemented as macros, test if the setting setting is of an aggregate type (a group, array, or list), of a scalar type (integer, 64-bit integer, floating point, boolean, or string), and of a number (integer, 64-bit integer, or floating point), respectively … → API: LcSettingIsNumber
They return CONFIG_TRUE or CONFIG_FALSE.
- See also
- SettingIsAggregate, SettingIsScalar
MK_BOOL LcSettingIsRoot(LC_CFSN setting)
top This function returns CONFIG_TRUE if the given setting is the root setting, and CONFIG_FALSE otherwise … → API: LcSettingIsRoot
MK_BOOL LcSettingIsScalar(LC_CFSN setting)
top These convenience functions, some of which are implemented as macros, test if the setting setting is of an aggregate type (a group, array, or list), of a scalar type (integer, 64-bit integer, floating point, boolean, or string), and of a number (integer, 64-bit integer, or floating point), respectively … → API: LcSettingIsScalar
They return CONFIG_TRUE or CONFIG_FALSE.
- See also
- SettingIsAggregate, SettingIsNumber
LcSettingC LOOKUP
C-API: LcSettingC_Lookup_C_API - LcSettingC - various functions to lookup a setting …
LC_CFS LcSettingLookup(LC_CFS setting, MK_STRN path)
top This function locates a setting by a path path relative to the setting setting … → API: LcSettingLookup
It returns a pointer to the LcSettingC structure on success, or NULL if the setting was not found.
MK_BFL LcSettingLookupAll(LC_CFSN setting)
top addon - read an entire configuration below setting into MkBufferListC … → API: LcSettingLookupAll
- Returns
- instand of MkBufferListC owned by
MK_BFL LcSettingLookupAll(LC_CFSN setting)
enum MkErrorE LcSettingLookupBool(LC_CFSN setting, MK_STRN name, MK_BOOL *value_out)
top These functions look up the value of the child setting named name of the setting setting … → API: LcSettingLookupBool
They store the value at value and return CONFIG_TRUE on success. If the setting was not found or if the type of the value did not match the type requested, they leave the data pointed to by value unmodified and return CONFIG_FALSE.
Storage for the string returned by SettingLookupString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
enum MkErrorE LcSettingLookupFloat(LC_CFSN setting, MK_STRN name, MK_DBL *value_out)
top These functions look up the value of the child setting named name of the setting setting … → API: LcSettingLookupFloat
They store the value at value and return CONFIG_TRUE on success. If the setting was not found or if the type of the value did not match the type requested, they leave the data pointed to by value unmodified and return CONFIG_FALSE.
Storage for the string returned by SettingLookupString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
enum MkErrorE LcSettingLookupInt(LC_CFSN setting, MK_STRN name, MK_I32 *value_out)
top These functions look up the value of the child setting named name of the setting setting … → API: LcSettingLookupInt
They store the value at value and return CONFIG_TRUE on success. If the setting was not found or if the type of the value did not match the type requested, they leave the data pointed to by value unmodified and return CONFIG_FALSE.
Storage for the string returned by SettingLookupString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
enum MkErrorE LcSettingLookupInt64(LC_CFSN setting, MK_STRN name, MK_I64 *value_out)
top These functions look up the value of the child setting named name of the setting setting … → API: LcSettingLookupInt64
They store the value at value and return CONFIG_TRUE on success. If the setting was not found or if the type of the value did not match the type requested, they leave the data pointed to by value unmodified and return CONFIG_FALSE.
Storage for the string returned by SettingLookupString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
enum MkErrorE LcSettingLookupString(LC_CFSN setting, MK_STRN name, MK_STRN *value_out)
top These functions look up the value of the child setting named name of the setting setting … → API: LcSettingLookupString
They store the value at value and return CONFIG_TRUE on success. If the setting was not found or if the type of the value did not match the type requested, they leave the data pointed to by value unmodified and return CONFIG_FALSE.
Storage for the string returned by SettingLookupString is managed by the library and released automatically when the setting is destroyed or when the setting's value is changed; the string must not be freed by the caller.
LcSettingC MISC
C-API: LcSettingC_Misc_C_API - LcSettingC - various functions to perform misc operations …
LC_CFS LcSettingAddIfNotExists(LC_CFS setting, MK_STRN name, enum LcConfigTypeE cfgtype)
top addon - add name with type only if not exists in the setting … → API: LcSettingAddIfNotExists
If parent is an array or list, the name parameter is ignored and may be NULL.
The function returns the new setting on success, or NULL if parent is not a group, array, or list; or if there is already a child setting of parent named name; or if type is invalid. If type is a scalar type, the new setting will have a default value of 0, 0.0, false, or NULL, as appropriate.
MK_BOOL LcSettingExists(LC_CFS const setting, MK_STRN name)
top addon - return true if name exists in the setting otherwise false … → API: LcSettingExists
Same as LcSettingGetMember but only test on exists
MK_I32 LcSettingIndex(LC_CFSN setting)
top This function returns the index of the given setting within its parent setting … → API: LcSettingIndex
If setting is the root setting, this function returns -1.
MK_I32 LcSettingLength(LC_CFSN setting)
top This function returns the number of settings in a group, or the number of elements in a list or array … → API: LcSettingLength
For other types of settings, it returns
(runtime) void LcSettingLog(LC_CFSN const setting, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)
top log the setting … → API: LcSettingLog_RT
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] setting same as config_setting_t [in] fmtobj managed object used to format the log-message (default= MK_NULL→ use default-format)[in] debug the debug levelfrom MkRuntimeS::debug, use0 <= debug <= 9(default=0)[in] callfunc a user-defined postfix to identify the calling function or the environment (default= name-of-function)[in] lvl a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default= 0)
MK_STRN LcSettingName(LC_CFSN setting)
top This function returns the name of the given setting, or NULL if the setting has no name … → API: LcSettingName
Storage for the returned string is managed by the library and released automatically when the setting is destroyed; the string must not be freed by the caller.
LC_CFS LcSettingParent(LC_CFSN setting)
top This function returns the parent setting of the given setting, or NULL if setting is the root setting … → API: LcSettingParent
enum MkErrorE LcSettingRemove(LC_CFS parent, MK_STRN name)
top This function removes and destroys the setting named name from the parent setting parent, which must be a group … → API: LcSettingRemove
Any child settings of the setting are recursively destroyed as well.
The name parameter can also specify a setting path relative to the provided parent. (In that case, the setting will be looked up and removed.)
The function returns CONFIG_TRUE on success. If parent is not a group, or if it has no setting with the given name, it returns CONFIG_FALSE.
enum MkErrorE LcSettingRemoveElem(LC_CFS parent, MK_I32 idx)
top This function removes the child setting at the given index index from the setting parent, which must be a group, list, or array … → API: LcSettingRemoveElem
Any child settings of the removed setting are recursively destroyed as well.
The function returns CONFIG_TRUE on success. If parent is not a group, list, or array, or if index is out of range, it returns CONFIG_FALSE.
MK_STRN LcSettingSourceFile(LC_CFSN setting)
top This function returns the name of the file from which the setting setting was read, or NULL if the setting was not read from a file … → API: LcSettingSourceFile
This information is useful for reporting application-level errors. Storage for the returned string is managed by the library and released automatically when the configuration is destroyed; the string must not be freed by the caller.
MK_I32 LcSettingSourceLine(LC_CFSN setting)
top This function returns the line number of the configuration file or stream at which the setting setting was read, or 0 if no line number is available … → API: LcSettingSourceLine
This information is useful for reporting application-level errors.
enum LcConfigTypeE LcSettingType(LC_CFSN setting)
top This function returns the type of the given setting … → API: LcSettingType
The return value is one of the constants CONFIG_TYPE_INT, CONFIG_TYPE_INT64, CONFIG_TYPE_FLOAT, CONFIG_TYPE_STRING, CONFIG_TYPE_BOOL, CONFIG_TYPE_ARRAY, CONFIG_TYPE_LIST, or CONFIG_TYPE_GROUP.
EXAMPLES
SEE ALSO
liblcconfig, cclcconfig, cslcconfig, javalcconfig, golcconfig, pylcconfig, rubylcconfig, tcllcconfig, perllcconfig, phplcconfig
KEYWORDS
C, unix, libconfig
Generated on Wed Sep 25 2024 12:16:11 for theConfig by
1.13.0