Support the libconfig native library.

SYNOPSIS

The tcllcconfig package is a library for processing configuration files

package require tcllcconfig

The tcllcconfig package is a composition of multiple classes defining the Programming-Language-Micro-Kernel (PLMK) :

object	description
`tcllcconfig`	the namespace with all tcllcconfig specific definitions
`tcllcconfig Attribute`	the interface to access the package specific attribute
`tcllcconfig::LcClassC Attribute`	the interface to access the class specific attribute
`$Instance Attribute`	the interface to access the instance specific attribute

To access all features without tcllcconfig prefix use:

namespace import tcllcconfig::*

Using the tcllcconfig package ...

TCL package libraries

libtcllcconfig.so: A shared library or shared object is a computer file that contains executable code designed to be used by multiple computer programs or other libraries at runtime.
libtcllcconfig.la: A .la file is a text file used by the GNU libtools package to describe the files that make up the corresponding library.

> man n env

To access the tcllcconfig package the environment variable TCLLIBPATH have to include the directory.

TCLLIBPATH
      If set, then it must contain a valid Tcl list giving directories to search during auto-load operations.
      Directories must be specified in Tcl format, using “/” as the path separator, regardless of platform.  
      This variable is only used when initializing the auto_path variable.

> man n pkg_create

::pkg::create is a utility procedure that is part of the standard Tcl library.
It is used to create an appropriate `package ifneeded` command for a given package specification.
It can be used to construct a `pkgIndex.tcl` file for use with the package mechanism.

The syntax of the pkgIndex.tcl file is simple

package ifneeded NAME 9.0 [list load [file join $dir libNAME.so]]

INTRODUCTION

C-API: LC_C_API - The theConfig API.

License

https://hyperrealm.github.io/libconfig/

Introduction

tcllcconfig 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

tcllcconfig 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.

tcllcconfig 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.

tcllcconfig 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.

tcllcconfig 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

tcllcconfig 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

tcllcconfig 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.

# Example application configuration file
 
version = "1.0";
 
application:
{
  window:
  {
    title = "My Application";
    size = { w = 640; h = 480; };
    pos = { x = 350; y = 250; };
  };
 
  list = ( ( "abc", 123, true ), 1.234, ( / * an empty list * / ) );
 
  books = ( { title  = "Treasure Island";
              author = "Robert Louis Stevenson";
              price  = 29.95;
              qty    = 5; },
            { title  = "Snow Crash";
              author = "Neal Stephenson";
              price  = 9.99;
              qty    = 8; } );
 
  misc:
  {
    pi = 3.141592654;
    bigint = 9223372036854775807L;
    columns = [ "Last Name", "First Name", "MI" ];
    bitmask = 0x1FC3;   // hex
    umask = 0027;       // octal. Range limited to that of "int"
  };
};

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:

# file: quote.cfg
quote = "Criticism may not be agreeable, but it is necessary."
        " It fulfils the same function as pain in the human"
        " body. It calls attention to an unhealthy state of"
        " things.\\n"
        "\\t--Winston Churchill";

# file: test.cfg
info: {
  name = "Winston Churchill";
  @include "quote.cfg"
  country = "UK";
};

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.

Configuration File Grammar

Below is the BNF grammar for configuration files. Comments and include directives are not part of the grammar, so they are not included here.

<configuration> ::=
      <setting-list>
    | <empty>

<setting-list> ::=
      <setting>
    | <setting-list> <setting>

<setting> ::=
      <name> ( ":" | "=" ) <value> ( ";" | "," | <empty> )

<value> ::=
      <scalar-value>
    | <array>
    | <list>
    | <group>

<value-list> ::=
      <value>
    | <value-list> "," <value>
    | <value-list> ","

<scalar-value> ::=
      <boolean>
    | <integer>
    | <integer64>
    | <hex>
    | <hex64>
    | <float>
    | <string>

<scalar-value-list> ::=
      <scalar-value>
    | <scalar-value-list> "," <scalar-value>
    | <scalar-value-list> ","

<array> ::=
      "[" ( <scalar-value-list> | <empty> ) "]"

<list> ::=
      "(" ( <value-list> | <empty> ) ")"

<group> ::=
      "{" ( <setting-list> | <empty> ) "}"

<empty> ::=

Terminals are defined below as regular expressions:

`<boolean>`	`([Tt][Rr][Uu][Ee])\|([Ff][Aa][Ll][Ss][Ee])`
`<string>`	`"([^"\]\|\.)*"`
`<name>`	`[A-Za-z][-A-Za-z0-9_]*`
`<integer>`	`[-+]?[0-9]+`
`<integer64>`	`[-+]?[0-9]+L(L)?`
`<hex>`	`0[Xx][0-9A-Fa-f]+`
`<hex64>`	`0[Xx][0-9A-Fa-f]+(L(L)?)?`
`<float>`	`([-+]?([0-9])?.[0-9]([eE][-+]?[0-9]+)?)\|([-+]([0-9]+)(.[0-9]*)?[eE][-+]?[0-9]+)`

Note that adjacent strings are automatically concatenated. Non-printable characters can be represented within strings using a sequence '\xx', representing the ASCII value as two hex digits.

LcConfig PACKAGE

LcConfig SETUP
	Cleanup	cleanup tcllcconfig internal memory …
	Setup	setup tcllcconfig internal memory …
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 DETAIL

C-API: LcConfig_C_API - LcConfig PACKAGE - the package is the toplevel structure of the tcllcconfig …

The tcllcconfig package is loaded with:

package require tcllcconfig

and is a composition of one or more package-item and exact one package-main.

The tcllcconfig 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 tcllcconfig package add the following types into MkObjectC_C_API :

    ABSTRACT: MkTypeSTT (TypeTypeType = type of a TypeType)
    |
    |- ABSTRACT: MkTypeDefSTT (TypeType = type of a Type)
       |
       |- LcConfigST, LcSettingT

LcConfig 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) LcConfig Cleanup`

top cleanup tcllcconfig internal memory … → API: tcllcconfig_LcConfig_Cleanup

Cleanup will only be recognized once and will be ignored if not called in the same thread as Setup. After a call to Setup the call to MkCleanup is possible again.

By default, the public Cleanup with the gcc: __attribute__ ((cleanup(XXX))) is called when unloading the library.
The public Cleanup is only a placeholder and should not be used, the internal Cleanup is always called, even if the public Cleanup is not called.

Note: during cleanup objects will be deleted too -> the language interpreter have to be active

`(static) LcConfig Setup`

top setup tcllcconfig internal memory … → API: tcllcconfig_LcConfig_Setup

Setup will only be recognized once, additional call's will be ignored until a Cleanup is called.

By default, the public Setup with the gcc: __attribute__ ((constructor(XXX))) is called when loading the library.
If the Target-Programming-Language (TPL) supports late loading of a shared library with dlopen and additionally uses threads, a manual call to Setup very early at startup is required to enforce the correct order of type declarations.

LcConfig ENUM

C-API: LcConfig_Enum_C_API - LcConfig PACKAGE - definition of the enum type …

enum LcConfigFormatE

top set the format of a LcSettingC … → API: tcllcconfig_Get_LcConfigFormatE_FromObj

enum LcConfigFormatE {
  CONFIG_FORMAT_DEFAULT=0,
  CONFIG_FORMAT_HEX=1,
};

enum LcConfigOptionsEF

top define the configuration-option of a LcConfigC … → API: tcllcconfig_Get_LcConfigOptionsEF_FromObj

__parser__(enum-is-flag)
enum LcConfigOptionsEF {
  CONFIG_OPTION_NONE=0x0,
  CONFIG_OPTION_AUTOCONVERT=0x01,
  CONFIG_OPTION_SEMICOLON_SEPARATORS=0x02,
  CONFIG_OPTION_COLON_ASSIGNMENT_FOR_GROUPS=0x04,
  CONFIG_OPTION_COLON_ASSIGNMENT_FOR_NON_GROUPS=0x08,
  CONFIG_OPTION_OPEN_BRACE_ON_SEPARATE_LINE=0x10,
  CONFIG_OPTION_ALLOW_SCIENTIFIC_NOTATION=0x20,
  CONFIG_OPTION_FSYNC=0x40,
  CONFIG_OPTION_ALLOW_OVERRIDES=0x80,
};

`(static) LcConfigOptionsEF [LcConfig ConfigOptionsEF_FromInt value:int32]`

top return the LcConfigOptionsEF from integer … → API: tcllcconfig_LcConfig_ConfigOptionsEF_FromInt

`(static) int32 [LcConfig ConfigOptionsEF_ToInt value:LcConfigOptionsEF]`

top return the LcConfigOptionsEF as integer … → API: tcllcconfig_LcConfig_ConfigOptionsEF_ToInt

`(static) string [LcConfig ConfigOptionsEF_ToString value:LcConfigOptionsEF]`

top return the LcConfigOptionsEF as string … → API: tcllcconfig_LcConfig_ConfigOptionsEF_ToString

enum LcConfigTypeE

top define the data-type of a LcSettingC … → API: tcllcconfig_Get_LcConfigTypeE_FromObj

enum LcConfigTypeE {
  CONFIG_TYPE_NONE=0,
  CONFIG_TYPE_GROUP=1,
  CONFIG_TYPE_INT=2,
  CONFIG_TYPE_INT64=3,
  CONFIG_TYPE_FLOAT=4,
  CONFIG_TYPE_STRING=5,
  CONFIG_TYPE_BOOL=6,
  CONFIG_TYPE_ARRAY=7,
  CONFIG_TYPE_LIST=8,
};

`(static) LcConfigTypeE [LcConfig ConfigTypeE_FromInt value:int32]`

top return the LcConfigTypeE from integer … → API: tcllcconfig_LcConfig_ConfigTypeE_FromInt

`(static) int32 [LcConfig ConfigTypeE_ToInt value:LcConfigTypeE]`

top return the LcConfigTypeE as integer … → API: tcllcconfig_LcConfig_ConfigTypeE_ToInt

`(static) string [LcConfig ConfigTypeE_ToString value:LcConfigTypeE]`

top return the LcConfigTypeE as string … → API: tcllcconfig_LcConfig_ConfigTypeE_ToString

enum LcErrorE

top Signals an error and is used as the return value of a function … → API: tcllcconfig_Get_LcErrorE_FromObj

enum LcErrorE {
  CONFIG_FALSE=0,
  CONFIG_TRUE=1,
};

`(static) LcErrorE [LcConfig ErrorE_FromInt value:int32]`

top return the LcErrorE from integer … → API: tcllcconfig_LcConfig_ErrorE_FromInt

`(static) int32 [LcConfig ErrorE_ToInt value:LcErrorE]`

top return the LcErrorE as integer … → API: tcllcconfig_LcConfig_ErrorE_ToInt

`(static) string [LcConfig ErrorE_ToString value:LcErrorE]`

top return the LcErrorE as string … → API: tcllcconfig_LcConfig_ErrorE_ToString

enum LcErrorTypeE

top error types → API: tcllcconfig_Get_LcErrorTypeE_FromObj

enum LcErrorTypeE {
  CONFIG_ERRROR_NONE = 0,
  CONFIG_ERRROR_FILE_IO = 1,
  CONFIG_ERRROR_PARSE = 2
};

`(static) LcErrorTypeE [LcConfig ErrorTypeE_FromInt value:int32]`

top return the LcErrorTypeE from integer … → API: tcllcconfig_LcConfig_ErrorTypeE_FromInt

`(static) int32 [LcConfig ErrorTypeE_ToInt value:LcErrorTypeE]`

top return the LcErrorTypeE as integer … → API: tcllcconfig_LcConfig_ErrorTypeE_ToInt

`(static) string [LcConfig ErrorTypeE_ToString value:LcErrorTypeE]`

top return the LcErrorTypeE as string … → API: tcllcconfig_LcConfig_ErrorTypeE_ToString

LcConfigC

LcConfigC CLASS
	Export	LcConfigC - Export class functions …
	Introspection	LcConfigC - Introspection class functions …
	Misc	LcConfigC - Misc class functions …
LcConfigC TOR
	Create	create a LcConfigC instance …
	CTOR	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 …
	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 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* …
	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* …
	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

NAVI: top, up

LcConfigC CLASS EXPORT

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

LcConfigC CLASS INTROSPECTION

Instances

get head-instance from linked-list of LcConfigS type …

LcConfigC CLASS MISC

GetNull

Null-Slot - return a LcConfigC typed NULL instance …

LcConfigC CLASS DETAILS

C-API: LcConfigC_Class_C_API - LcConfigC - define the class …

LcConfigC CLASS EXPORT

LcConfigC - Export class functions …

`(static) LcConfigC [LcConfigC HandleResolve netHdl:MK_HDL]`

top Handle-Resolve-Slot - return a LcConfigC from netHdl or "MK_NULL" if invalid… → API: tcllcconfig_LcConfigC_HandleResolve

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_NULL" if netHdl is invalid

`MK_HDL [$cfg HandleGet]`

top Handle-Get-Slot - returns a export-hdl to the LcConfigC useable for external storage → API: tclmkkernel_MkObjectC_HandleGet

The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the LcConfigHandleResolve.

By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.

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) LcConfigC [LcConfigC Instances]`

top get head-instance from linked-list of LcConfigS type … → API: tcllcconfig_LcConfigC_Instances

The head-instance is the last instance created.

`LcConfigC [$cfg Next]`

top get next instance from linked-list of LcConfigS type → API: tcllcconfig_LcConfigC_Next

`LcConfigC [$cfg Prev]`

top get previous instance from linked-list of LcConfigS type → API: tcllcconfig_LcConfigC_Prev

LcConfigC CLASS MISC

LcConfigC - Misc class functions …

`(static) LcConfigC [LcConfigC GetNull]`

top Null-Slot - return a LcConfigC typed NULL instance … → API: tcllcconfig_LcConfigC_GetNull

LcConfigC TOR

C-API: LcConfigC_TOR_C_API - LcConfigC - various functions to create, initialize and destroy …

`(constructor,static) LcConfigC [LcConfigC Create]`

top create a LcConfigC instance … → API: tcllcconfig_LcConfigC_Create

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_NULL" if setup failed

`(constructor,static) LcConfigC [LcConfigC CTOR]`

top create a LcConfigC instance … → API: tcllcconfig_LcConfigC_CTOR

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_NULL" if setup failed

`(destructor) $cfg Delete`

top delete a LcConfigC instance … → API: LcConfigDelete_RT

LcConfigC SET

C-API: LcConfigC_Set_C_API - LcConfigC - various functions to set config-data …

`$config SetDefaultFormat format:LcConfigFormatE`

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

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

`$config SetFloatPrecision digits:int16`

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: tcllcconfig_LcConfigC_SetFloatPrecision

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

`$config SetIncludeDir include_dir:string`

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: tcllcconfig_LcConfigC_SetIncludeDir

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

`$cfg SetIncludeFunc ?fConfigIncludeData:LC_CBP="MK_NULL"?`

top set the __parser__(callback-name) for the include-config-file … → API: tcllcconfig_LcConfigC_SetIncludeFunc

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

See also: LcConfigGetIncludeFunc LcConfigSetIncludeFuncHide

LcConfigSetIncludeFunc : callback signature: callback-args := inclDir:String[in] path:String[in] ret:MkBufferListC[inout]

[static] proc callback { callback-args ?additional-args...? } ...

$cfg SetIncludeFunc callback

[instance] ::oo::class create YYY {

method callback { callback-args ?additional-args...? } ...

}

$cfg SetIncludeFunc [list [self] callback]

[class] ::oo::class create YYY {

self method callback { callback-args ?additional-args...? } ...

}

$cfg SetIncludeFunc [list YYY callback]

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.

`$config SetOption option:LcConfigOptionsEF flag:bool`

top Since v1.7 These functions get and set the given option of the configuration config … → API: tcllcconfig_LcConfigC_SetOption

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

`$config SetOptions options:LcConfigOptionsEF`

top These functions get and set the options for the configuration config … → API: tcllcconfig_LcConfigC_SetOptions

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 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

`$cfg SetSettingDeleteFunc ?fSettingDeleteData:LC_CBP="MK_NULL"?`

top set the callback-name for the setting-delete … → API: tcllcconfig_LcConfigC_SetSettingDeleteFunc

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: callback-args := hdl:EXPORT-HANDLE[in]

[static] proc callback { callback-args ?additional-args...? } ...

$cfg SetSettingDeleteFunc callback

[instance] ::oo::class create XXX {

method callback { callback-args ?additional-args...? } ...

}

$cfg SetSettingDeleteFunc [list [self] callback]

[class] ::oo::class create YYY {

self method callback { callback-args ?additional-args...? } ...

}

$cfg SetSettingDeleteFunc [list YYY callback]

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

`$config SetTabWidth width:int16`

top These functions, which are implemented as macros, get and set the tab width for the configuration config … → API: tcllcconfig_LcConfigC_SetTabWidth

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 …

`LcConfigFormatE [$config GetDefaultFormat]`

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

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

`int16 [$config GetFloatPrecision]`

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: tcllcconfig_LcConfigC_GetFloatPrecision

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

`string [$config GetIncludeDir]`

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: tcllcconfig_LcConfigC_GetIncludeDir

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

`bool [$config GetOption option:LcConfigOptionsEF]`

top Since v1.7 These functions get and set the given option of the configuration config … → API: tcllcconfig_LcConfigC_GetOption

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

`LcConfigOptionsEF [$config GetOptions]`

top These functions get and set the options for the configuration config … → API: tcllcconfig_LcConfigC_GetOptions

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 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

`int16 [$config GetTabWidth]`

top These functions, which are implemented as macros, get and set the tab width for the configuration config … → API: tcllcconfig_LcConfigC_GetTabWidth

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 …

`LcSettingC [$config Lookup path:string]`

top This function locates the setting in the configuration config specified by the path path … → API: tcllcconfig_LcConfigC_Lookup

It returns a pointer to the LcSettingC structure on success, or NULL if the setting was not found.

`bool [$config LookupBool path:string]`

top These functions look up the value of the setting in the configuration config specified by the path path … → API: tcllcconfig_LcConfigC_LookupBool

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.

See also: ConfigLookupFloat, ConfigLookupInt, ConfigLookupInt64, ConfigLookupString

`double [$config LookupFloat path:string]`

top These functions look up the value of the setting in the configuration config specified by the path path … → API: tcllcconfig_LcConfigC_LookupFloat

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.

See also: ConfigLookupBool, ConfigLookupInt, ConfigLookupInt64, ConfigLookupString

`int32 [$config LookupInt path:string]`

top These functions look up the value of the setting in the configuration config specified by the path path … → API: tcllcconfig_LcConfigC_LookupInt

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.

See also: ConfigLookupBool, ConfigLookupFloat, ConfigLookupInt64, ConfigLookupString

`int64 [$config LookupInt64 path:string]`

top These functions look up the value of the setting in the configuration config specified by the path path … → API: tcllcconfig_LcConfigC_LookupInt64

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.

See also: ConfigLookupBool, ConfigLookupFloat, ConfigLookupInt, ConfigLookupString

`string [$config LookupString path:string]`

top These functions look up the value of the setting in the configuration config specified by the path path … → API: tcllcconfig_LcConfigC_LookupString

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.

See also: ConfigLookupBool, ConfigLookupFloat, ConfigLookupInt, ConfigLookupInt64

LcConfigC ERROR

C-API: LcConfigC_Error_C_API - LcConfigC - dealing with a native-error …

`LcErrorTypeE [$config ErrorType]`

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: tcllcconfig_LcConfigC_ErrorType

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 …

`$config Clear`

top Since v1.7 This function clears the configuration config … → API: tcllcconfig_LcConfigC_Clear

All child settings of the root setting are recursively destroyed. All other attributes of the configuration are left unchanged.

`$cfg Log ?fmtobj:MkObjectC="MK_NULL"? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?`

top log the config … → API: tcllcconfig_LcConfigC_Log

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 level` from MkRuntimeS::debug, use `0 <= debug <= 9` (default=`0`)
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, `"MK_NULL"` = resolve-own-name)
[in]	lvl	a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=`0`)

`$config ReadFile filename:string`

top This function reads and parses a configuration from the file named filename into the configuration object config … → API: tcllcconfig_LcConfigC_ReadFile

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.

`$config ReadString str:string`

top This function reads and parses a configuration from the string str into the configuration object config … → API: tcllcconfig_LcConfigC_ReadString

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.

`LcSettingC [$config RootSetting]`

top This function, which is implemented as a macro, returns the root setting for the configuration config … → API: tcllcconfig_LcConfigC_RootSetting

The root setting is a group.

`$config WriteFile filename:string`

top This function writes the configuration config to the file named filename … → API: tcllcconfig_LcConfigC_WriteFile

It returns CONFIG_TRUE on success, or CONFIG_FALSE on failure.

`string [$cfg WriteString]`

top read the entire configuration cfg into the string val_out … → API: tcllcconfig_LcConfigC_WriteString

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 `string [$cfg WriteString]` .

Exceptions

MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)

LcSettingC

LcSettingC CLASS
	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* …
	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* …
	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

NAVI: top, up

LcSettingC CLASS EXPORT

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 …

LcSettingC CLASS MISC

GetNull

Null-Slot - return a LcSettingC typed NULL instance …

LcSettingC CLASS DETAILS

C-API: LcSettingC_Class_C_API - LcSettingC - define the class …

LcSettingC CLASS EXPORT

LcSettingC - Export class functions …

`(static) LcSettingC [LcSettingC HandleResolve netHdl:MK_HDL]`

top Handle-Resolve-Slot - return a LcSettingC from netHdl or "MK_NULL" if invalid… → API: tcllcconfig_LcSettingC_HandleResolve

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_NULL" if netHdl is invalid

`MK_HDL [$cfs HandleGet]`

top Handle-Get-Slot - returns a export-hdl to the LcSettingC useable for external storage → API: tclmkkernel_MkObjectC_HandleGet

The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the LcSettingHandleResolve.

By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.

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) LcSettingC [LcSettingC Instances]`

top get head-instance from linked-list of LcSettingS type … → API: tcllcconfig_LcSettingC_Instances

The head-instance is the last instance created.

`LcSettingC [$cfs Next]`

top get next instance from linked-list of LcSettingS type → API: tcllcconfig_LcSettingC_Next

`LcSettingC [$cfs Prev]`

top get previous instance from linked-list of LcSettingS type → API: tcllcconfig_LcSettingC_Prev

LcSettingC CLASS MISC

LcSettingC - Misc class functions …

`(static) LcSettingC [LcSettingC GetNull]`

top Null-Slot - return a LcSettingC typed NULL instance … → API: tcllcconfig_LcSettingC_GetNull

LcSettingC TOR

C-API: LcSettingC_TOR_C_API - LcSettingC - various functions to create, initialize and destroy …

`(constructor) LcSettingC [$parent Add name:string __type:LcConfigTypeE]`

top This function adds a new child setting or element to the setting parent, which must be a group, array, or list … → API: tcllcconfig_LcSettingC_Add

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.

`LcConfigC [$setting GetConfig]`

top addon - return the LcConfigC from the LcSettingC … → API: tcllcconfig_LcSettingC_GetConfig

LcSettingC SET

C-API: LcSettingC_Set_C_API - LcSettingC - various functions to set date into a setting …

`$setting SetBool value:bool`

top These functions set the value of the given setting to value … → API: tcllcconfig_LcSettingC_SetBool

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.

See also: SettingSetFloat, SettingSetInt, SettingSetInt64, SettingSetString

`LcSettingC [$setting SetBoolElem idx:int32 value:int32]`

top These functions set the value at the specified index index in the setting setting to value … → API: tcllcconfig_LcSettingC_SetBoolElem

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.

See also: SettingSetFloatElem, SettingSetInt64Elem, SettingSetIntElem, SettingSetStringElem

`$setting SetFloat value:double`

top These functions set the value of the given setting to value … → API: tcllcconfig_LcSettingC_SetFloat

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.

See also: SettingSetBool, SettingSetInt, SettingSetInt64, SettingSetString

`LcSettingC [$setting SetFloatElem idx:int32 value:double]`

top These functions set the value at the specified index index in the setting setting to value … → API: tcllcconfig_LcSettingC_SetFloatElem

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.

See also: SettingSetBoolElem, SettingSetInt64Elem, SettingSetIntElem, SettingSetStringElem

`$setting SetFormat format:LcConfigFormatE`

top These functions get and set the external format for the setting setting … → API: tcllcconfig_LcSettingC_SetFormat

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

`$setting SetInt value:int32`

top These functions set the value of the given setting to value … → API: tcllcconfig_LcSettingC_SetInt

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.

See also: SettingSetBool, SettingSetFloat, SettingSetInt64, SettingSetString

`$setting SetInt64 value:int64`

top These functions set the value of the given setting to value … → API: tcllcconfig_LcSettingC_SetInt64

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.

See also: SettingSetBool, SettingSetFloat, SettingSetInt, SettingSetString

`LcSettingC [$setting SetInt64Elem idx:int32 value:int64]`

top These functions set the value at the specified index index in the setting setting to value … → API: tcllcconfig_LcSettingC_SetInt64Elem

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.

See also: SettingSetBoolElem, SettingSetFloatElem, SettingSetIntElem, SettingSetStringElem

`LcSettingC [$setting SetIntElem idx:int32 value:int32]`

top These functions set the value at the specified index index in the setting setting to value … → API: tcllcconfig_LcSettingC_SetIntElem

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.

See also: SettingSetBoolElem, SettingSetFloatElem, SettingSetInt64Elem, SettingSetStringElem

`$setting SetString value:string`

top These functions set the value of the given setting to value … → API: tcllcconfig_LcSettingC_SetString

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.

See also: SettingSetBool, SettingSetFloat, SettingSetInt, SettingSetInt64

`LcSettingC [$setting SetStringElem idx:int32 value:string]`

top These functions set the value at the specified index index in the setting setting to value … → API: tcllcconfig_LcSettingC_SetStringElem

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.

See also: SettingSetBoolElem, SettingSetFloatElem, SettingSetInt64Elem, SettingSetIntElem

LcSettingC GET

C-API: LcSettingC_Get_C_API - LcSettingC - various functions to get data from a setting …

`bool [$setting GetBool]`

top These functions return the value of the given setting … → API: tcllcconfig_LcSettingC_GetBool

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.

See also: SettingGetFloat, SettingGetInt, SettingGetInt64, SettingGetString

`bool [$setting GetBoolElem idx:int32]`

top These functions return the value at the specified index index in the setting setting … → API: tcllcconfig_LcSettingC_GetBoolElem

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.

See also: SettingGetFloatElem, SettingGetInt64Elem, SettingGetIntElem, SettingGetStringElem

`LcSettingC [$setting GetElem idx:int32]`

top This function fetches the element at the given index index in the setting setting, which must be an array, list, or group … → API: tcllcconfig_LcSettingC_GetElem

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.

`double [$setting GetFloat]`

top These functions return the value of the given setting … → API: tcllcconfig_LcSettingC_GetFloat

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.

See also: SettingGetBool, SettingGetInt, SettingGetInt64, SettingGetString

`double [$setting GetFloatElem idx:int32]`

top These functions return the value at the specified index index in the setting setting … → API: tcllcconfig_LcSettingC_GetFloatElem

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.

See also: SettingGetBoolElem, SettingGetInt64Elem, SettingGetIntElem, SettingGetStringElem

`LcConfigFormatE [$setting GetFormat]`

top These functions get and set the external format for the setting setting … → API: tcllcconfig_LcSettingC_GetFormat

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

`int32 [$setting GetInt]`

top These functions return the value of the given setting … → API: tcllcconfig_LcSettingC_GetInt

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.

See also: SettingGetBool, SettingGetFloat, SettingGetInt64, SettingGetString

`int64 [$setting GetInt64]`

top These functions return the value of the given setting … → API: tcllcconfig_LcSettingC_GetInt64

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.

See also: SettingGetBool, SettingGetFloat, SettingGetInt, SettingGetString

`int64 [$setting GetInt64Elem idx:int32]`

top These functions return the value at the specified index index in the setting setting … → API: tcllcconfig_LcSettingC_GetInt64Elem

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.

See also: SettingGetBoolElem, SettingGetFloatElem, SettingGetIntElem, SettingGetStringElem

`int32 [$setting GetIntElem idx:int32]`

top These functions return the value at the specified index index in the setting setting … → API: tcllcconfig_LcSettingC_GetIntElem

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.

See also: SettingGetBoolElem, SettingGetFloatElem, SettingGetInt64Elem, SettingGetStringElem

`LcSettingC [$setting GetMember name:string]`

top This function fetches the child setting named name from the group setting … → API: tcllcconfig_LcSettingC_GetMember

It returns the requested setting on success, or NULL if the setting was not found or if setting is not a group.

`string [$setting GetString]`

top These functions return the value of the given setting … → API: tcllcconfig_LcSettingC_GetString

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.

See also: SettingGetBool, SettingGetFloat, SettingGetInt, SettingGetInt64

`string [$setting GetStringElem idx:int32]`

top These functions return the value at the specified index index in the setting setting … → API: tcllcconfig_LcSettingC_GetStringElem

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.

See also: SettingGetBoolElem, SettingGetFloatElem, SettingGetInt64Elem, SettingGetIntElem

LcSettingC IS

C-API: LcSettingC_Is_C_API - LcSettingC - various functions to check a setting …

`bool [$setting IsAggregate]`

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: tcllcconfig_LcSettingC_IsAggregate

They return CONFIG_TRUE or CONFIG_FALSE.

See also: SettingIsNumber, SettingIsScalar

`bool [$setting IsArray]`

top These convenience functions, which are implemented as macros, test if the setting setting is of a given type … → API: tcllcconfig_LcSettingC_IsArray

They return CONFIG_TRUE or CONFIG_FALSE.

See also: SettingIsGroup, SettingIsList

`bool [$setting IsGroup]`

top These convenience functions, which are implemented as macros, test if the setting setting is of a given type … → API: tcllcconfig_LcSettingC_IsGroup

They return CONFIG_TRUE or CONFIG_FALSE.

See also: SettingIsArray, SettingIsList

`bool [$setting IsList]`

top These convenience functions, which are implemented as macros, test if the setting setting is of a given type … → API: tcllcconfig_LcSettingC_IsList

They return CONFIG_TRUE or CONFIG_FALSE.

See also: SettingIsArray, SettingIsGroup

`bool [$setting IsNumber]`

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: tcllcconfig_LcSettingC_IsNumber

They return CONFIG_TRUE or CONFIG_FALSE.

See also: SettingIsAggregate, SettingIsScalar

`bool [$setting IsRoot]`

top This function returns CONFIG_TRUE if the given setting is the root setting, and CONFIG_FALSE otherwise … → API: tcllcconfig_LcSettingC_IsRoot

`bool [$setting IsScalar]`

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: tcllcconfig_LcSettingC_IsScalar

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 …

`LcSettingC [$setting Lookup path:string]`

top This function locates a setting by a path path relative to the setting setting … → API: tcllcconfig_LcSettingC_Lookup

It returns a pointer to the LcSettingC structure on success, or NULL if the setting was not found.

`MkBufferListC [$setting LookupAll]`

top addon - read an entire configuration below setting into MkBufferListC … → API: tcllcconfig_LcSettingC_LookupAll

Returns: instand of MkBufferListC owned by MkBufferListC [$setting LookupAll]

`bool [$setting LookupBool name:string]`

top These functions look up the value of the child setting named name of the setting setting … → API: tcllcconfig_LcSettingC_LookupBool

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.