LCONF: Specification 7.0¶

LCONF is a light - human-friendly, simple readable data serialization format for dynamic configuration.

Specification¶

Indentation¶

LCONF Indentation is exact 3 spaces per level

LCONF-Default-Template-Structure¶

LCONF does require a predefined implemented LCONF-Default-Template-Structure.

REASON:

LCONF is based on the idea of defaults and order which must be implemented previously - parsing a ‘LCONF text source/file’ will only overwrites such defaults with the user set values

Depending on the library and coding language such LCONF-Default-Template-Structure can be implemented in different ways but must have some common features:

should be quite easily to implement
must support options for easily defining value transformation: Value Transformation
must support option to define: default comment lines, default empty lines which can be emitted/dumped: Default-Comment/Empty Lines
must support option to define: order and default values of all LCONF items, keys, values, blocks ect..: Order, Default Values, Default-Comment/Empty Lines
must support option to define: Empty-KeyValuePair-ReplacementValues Empty Key :: Value Pairs`

Default-Comment/Empty Lines¶

The LCONF-Default-Template-Structure can define Default-Comment/Empty Lines which can be emitted/dumped.

Warning

before the Block-Name (dummy_blk) there may be no Default-Comment/Empty Lines
within default list items there may be also no Default-Comment/Empty Lines

Note

This does not apply to the ‘LCONF text source/file’ as such Comments are always skipped when the source text gets parsed.

Strings¶

LCONF uses mainly one native type: strings. Unlike many other formats: LCONF does not use quotation for strings.

Additionally it supports:

empty string values: for Key :: Value Pairs and empty Key :: Value-Lists are supported:

where the value is left out and the last space after the double colon is skipped

Warning

LCONF does not at all support trailing spaces
optional casting to different data types

Comment-Line Identifier¶

one number sign is used as Comment-Line Identifier: “# Comment-Line more info”

If the first none space character in a line is # the line is considered a Comment-Line

Comment-Line must have the indentation level of the following line (disregarding empty lines) User defined comment lines (LCONF source) are always skipped when the LCONF source is parsed.

LCONF-Example

LCONF with Comment-Line

___SECTION :: SectionName

# Comment-Line: must have the indentation level of the following line (disregarding empty lines)
first :: Tim
last :: Doe
age :: 39
___END

SeeAlso

related Default-Comment/Empty Lines which are implemented in the code’s LCONF-Default-Template-Structure

Key :: Value Separator¶

one space, double colons, one space is used as a: Key Value Separator: “Key Name :: Value”

Exception for empty string values: the last space is skipped so that there is no trailing space.

Key :: Value Pair¶

Uses the Key :: Value Separator

Each value is always interpreted as a: single string

to transform it use one Value Transformation function

LCONF-Example

LCONF with Key :: Value Pair

___SECTION :: SectionName
Color :: Blue
mykey :: a long sentence ...
___END

Empty Key :: Value Pairs¶

LCONF-Example

LCONF with empty Key :: Value Pair

___SECTION :: SectionName
MyEmptyKeyValuePair ::
___END

Empty Key :: Value Pair: for empty values the last space of the Key :: Value Separator is skipped

Warning

Empty values with transformation-function are returned as:

empty strings
or a predefined: Empty-KeyValuePair-ReplacementValue

Empty-KeyValuePair-ReplacementValue is optional and must be implemented within the code of a LCONF-Default-Template-Structure

Lists¶

There are 3 sub types of lists and all of them use the List Identifier and support empty lists.

For an empty list only define the List Identifier line without any items / item lines.

This will overwrite any default values
To keep all default values do not define the List at all

List Identifier¶

minus, one space is used as List Identifier for all 3 sub types of lists: “- List Identifier Name”

LCONF-Example

LCONF with List Identifiers for all 3 sub types of lists

___SECTION :: SectionName

# Key :: Value-List: one line
- Names :: Tim,Sandra,Max

# Key-Value-List: multi line with indentation
- Names
   Tim
   Sandra
   Max

# List-Of-Tuples: multi line with indentation
- Colors RGB |Color Name|Red|Green|Blue|
   forestgreen,34,139,34
   brick,156,102,31
___END

Key :: Value-List¶

Ordered collection of items: oneline list

Uses the List Identifier and also the Key :: Value Separator and as value a collection of ordered items separated by comma ,

Important

spaces are not stripped

Each list item is always interpreted as a: single string within a list obj.

This implies that list items can not be an other list or dict.
to transform it use one Value Transformation function which is applied to each item in the list

LCONF-Example

LCONF Key :: Value-List

___SECTION :: SectionName
- Names :: Tim,Sandra,Max
___END

LCONF empty Key :: Value-List

___SECTION :: SectionName
- MyEmptyList ::
___END

Key-Value-List¶

Ordered collection of items: multiline list

Uses the List Identifier and the value lines (list items) uses one indentation level (3 additional spaces).

Basically the same as Key :: Value-List just uses a different notation for readability and is mostly useful for longer lists (or when the items are long e.g. sentences).

Each list item line is always interpreted as a: single string within a list obj.

This implies that list items can not be an other list or dict.

to transform it use one Value Transformation function

LCONF-Example

LCONF Key-Value-List

___SECTION :: SectionName
- Names
   Tim
   Sandra
   Max
   Frank
___END

LCONF empty Key-Value-List

___SECTION :: SectionName
- Names
___END

Warning

Key-Value-List Identifier lines may NOT end with an pipe sign (vertical bar) |

WRONG LCONF Key-Value-List

___SECTION :: SectionName
- My List |
   VALUE list item1
   VALUE list item2
___END

Tip

LCONF Key-Value-List can have comma separated lines
___SECTION :: SectionName
- list_
   534,45
   0,1,2,3
___END

This is neither a multidimensional List-Of-Tuples because there was no last char: pipe sign |

The list item: 534,45 or 0,1,2,3 are a normal string lines (item lines of an: Key-Value-List) e.g. one could use a transformation function to simulate a kind of list within a list with different number of values (in case List-Of-Tuples can not fit the purpose)

splitting it be comma

List-Of-Tuples¶

Ordered collection of items: multi-line list of multiple values

Uses the List Identifier and additionally adds at the end a space followed by column names

The Value lines (tuple item rows) use one additional indentation level (3 additional spaces).

all item lines must have the same number of values (as defined in the column names)

List-Of-Tuples are useful for multidimensional lists or tables e.g. csv data.

Column Names are embraced and separated by pipe sign (vertical bar) and must be unique
List-Of-Tuples item lines: Values are separated by comma ,

Important

spaces around values are stripped

LCONF-Example

LCONF List-Of-Tuples with 3 expected items (columns) per line (row)

___SECTION :: SectionName
- My List of lists |X|Y|Z|
   value1, value2, value3
   value1, value2, value3
___END

LCONF empty List-Of-Tuples

___SECTION :: SectionName
- My empty List of lists |X|Y|Z|
___END

List-Of-Tuples can have empty (missing) values: Empty/Missing Values are returned as empty strings or if defined per column replacement values. Replacement-Values must be implemented in the LCONF-Default-Template-Structure.

Important

Defined Empty/Missing Replacement-Values must be defined as strings as they run also through any transformation functions

LCONF-Example

LCONF List-Of-Tuples with Empty/Missing Values which will be returned as empty strings or with a Replacement-Values if implemented in the LCONF-Default-Template-Structure

___SECTION :: SectionName
- My List of lists |X|Y|Z|
   # COMMENT: the 2. item is empty or missing
   value1,       , value3
   value1, value2, value3
   # COMMENT: all items are empty or missing: the indentation level must be kept
   ,             ,
   # COMMENT: spaces are not important
   ,,
___END

Each single item value is always interpreted as a: single string within a tuple obj.

This implies that items in any of the tuples (rows) can not be an other list or dict.

have one transformation function which will be applied to each single item in each tuple

or have for each `column` a separate transformation function which will be applied to each line (row)

in the example above this would be 3 transformation functions: X,Y,Z Columns

Warning

Empty values with transformation-function are returned as empty strings
Any Replacement-Value runs also through the transformation-function like any normally set value and is returned

Key-Value-Mapping¶

dot, one space is used as Key-Value-Mapping Identifier: ”. Key-Value-Mapping Identifier Name”

A collection of items depending on the implementation this can be ordered or unordered

Note

any LCONF library must implement an option to loop over it in order as defined in a LCONF-Template-Default-Structure

Mapping items use one additional indentation level (3 additional spaces).: Each mapping item can be any of can be any of the Four Main Structures

An Empty Key-Value-Mapping Identifier is permitted: which will use all default values as implemented by a LCONF-Template-Default-Structure. It is basically the same as if one does not define it at all.

use it as a placeholder: e.g. if one wants previous comment lines

LCONF-Example

LCONF Key-Value-Mapping

___SECTION :: SectionName
. Mapping KEY
   mapping_item1_key :: mapping_item1_value
   - mapping_item2_key list
      my list item 1
   . mapping_item3_key nested key-value-mapping
      inner_mapping_item1_key :: inner_mapping_item1_value

   * mapping_item1_key Nested_BLK_Identifier
      Tim_Blk_Name
___END

LCONF empty Key-Value-Mapping

___SECTION :: SectionName
. Mapping KEY
   mapping_item1_key :: mapping_item1_value
   - mapping_item2_key list
      my list item 1
   # Comment: below a permitted empty `Key-Value-Mapping Identifier` which will use all default values
   . mapping_item3_key nested key-value-mapping

   * mapping_item1_key Nested_BLK_Identifier
      Tim_Blk_Name
___END

Key-Value-Mapping lines can not have any transformation function

but each item can (depending on the item)

Important

Do get all default values for each item key

do not define the Key-Value-Mapping in the LCONF

OR define only the Key-Value-Mapping Identifier line in the LCONF which is permitted too

Repeated-Block¶

Repeated Blocks allows to configure any number of such blocks within the ‘LCONF text source/file’.

Repeated-Block-Identifier and Block-Name lines can not have any transformation function

but each block item of a Block-Name can (depending on the item)

Any number of Block-Names can be defined: this can also be limited in a LCONF-Template-Default-Structure

Repeated Blocks have two options to predefine:

NUMBER_MIN_REQUIRED_BLOCKS in a LCONF-Template-Default-Structure

0 or greater

to not define it: set it to -1

NUMBER_MAX_ALLOWED_BLOCKS in a LCONF-Template-Default-Structure

1 or greater

to not define it: set it to -1

Block item can be any of the Four Main Structures.

Repeated-Block-Identifier¶

asterisk, one space is used as Repeated-Block-Identifier: “* Repeated-Block-Identifier Name”

An Empty Repeated Block Identifier is permitted: but without a Block-Name it does nothing

use it as a placeholder: e.g. if one wants previous comment lines

Repeated-Block-Identifier lines can not have any transformation function

LCONF-Example

LCONF Repeated-Block

___SECTION :: SectionName
* Color_BLK_Identifier
   Sky Blue_Blk-Name
      blk_item_red :: 135
      blk_item_green :: 206
      blk_item_blue :: 235
___END

LCONF empty Repeated-Block only define the Repeated Block Identifier line: it does nothing

___SECTION :: SectionName
* Color_BLK_Identifier
___END

Block-Names¶

Each Block is named: Block-Names use one additional indentation level (3 additional spaces) from the Repeated-Block-Identifier.

Any number of Block-Names can be defined: this can also be limited in a LCONF-Template-Default-Structure.

Repeated Blocks have two options to predefine: NUMBER_MIN_REQUIRED_BLOCKS, NUMBER_MAX_ALLOWED_BLOCKS

Todo

change NUMBER_MAX_ALLOWED_BLOCKS to NUMBER_MAX_ALLOWED_BLOCKS

Note

if a Block-Name is defined without any items at all: it is still valid using all defaults

LCONF Repeated-Block with an empty Block-Name which will using all defaults implemented in a LCONF-Template-Default-Structure

___SECTION :: SectionName
* Color_BLK_Identifier
   Sky Blue_Blk-Name
___END

Block-Name Items¶

Block-Name Items use one additional indentation level (3 additional spaces) from the Block-Name.

Each Block-Name Item can be any of the Four Main Structures.

Block-Name Items lines can have transformation function/s (depending on the item type)

Section Start/End Tags¶

___SECTION, ___END are reserved for the purpose of SECTION START/END TAGS.

LCONF-Example

LCONF Section Start/End TAGS-Block LCONF-Section called: MyExample

___SECTION :: MyExample
___END

Warning

Section Start/End TAGS are forbidden in any form except for the defined purpose.

Section Start TAG¶

three underlines, capital SECTION

This is followed by a Key :: Value Separator and the Section Name which is required: it can not be an empty string value.

It must always be without indentation.

Section End TAG¶

three underlines, capital END

It must always be without indentation.

Restrictions¶

A library does not have to validate these restrictions: validation is optional.

Restrictions Summary¶

GENERAL RESERVED: ___SECTION, ___END, ::
FIRST NONE WHITE character of a line RESERVED:
- * asterisk Except for Repeated-Block-Identifier
- - minus Except for all kind of Lists-Identifier
- . dot Except for all kind of Key-Value-Mapping
- # number sign Except for Comment lines
LAST character of a line RESERVED:
- Key-Value-List Identifier lines may NOT end with an pipe sign (vertical bar) |
- List-Of-Tuples Identifier lines: must end with a pipe sign (vertical bar) |
  
  List-Of-Tuples Identifier can not contain any pipe sign (vertical bar) except for the purpose of separating column names
Item types in lists:
- Key-Value-List and Key :: Value-List: may be only basic types: not another list, tuple, dict ect..
  Tip
  
  LCONF Key-Value-List can have comma separated lines
  
  ___SECTION :: SectionName - list_ 534,45 0,1,2,3 ___END
  
  This is neither a multidimensional List-Of-Tuples because there was no last char: pipe sign |
  
  The list item: 534,45 or 0,1,2,3 are a normal string lines (item lines of an: Key-Value-List) e.g. one could use a transformation function to simulate a kind of list within a list with different number of values (in case List-Of-Tuples can not fit the purpose)
  
  splitting it be comma
- List-Of-Tuples: can contain tuples with the same number of items as column-names specified. (empty items are allowed)
  items within the tuples: may be only basic types: not another list, tuple, dict ect..

Restrictions: Section Start/End Tag¶

Warning

Section Start/End Tag are forbidden in any form except for the defined purpose. Section Start/End Tags

Restrictions: Unique names¶

all Main Keys and Repeated-Block-Identifiers: must be unique
withing a `Key-Value-Mapping: the keys must be unique
within a `List-Of-Tuples: the column names must be unique
Block-Names: must be unique within one Repeated-Block-Identifier
Block-Keys: must be unique within one Block

Restrictions: Item Types in Lists¶

Key-Value-List and Key :: Value-List: may be only basic types: not another list, tuple, dict ect..
Note

LCONF Key-Value-List can have comma separated lines
- list_ 0,1,2,3
- This is neither a multidimensional List-Of-Tuples because there was no last char: pipe sign |
- It is also not a oneline Key :: Value-List
The list item: 0,1,2,3 is a normal string line (item line of an: Key-Value-List) e.g. one could use a transformation function to simulate a kind of list within a list.
splitting it be comma
WRONG LCONF Key-Value-List can have as items only basic types
- mylist item1 # wrong to have a nested list within a list - another_list ::
List-Of-Tuples: may only contain tuples (row lines) with the same number of items as column-names specified.
- items within the tuples: may be only basic types: not another list, tuple, dict ect.. (empty items are supported)

Restrictions: No Trailing Spaces¶

Lines may not have any trailing spaces

Restrictions: Comments¶

Comment lines # within a LCONF-Section are required to have the indentation of the next none empty line.

Restrictions: Default-Comment/Empty Lines¶

before Block-Names (dummy_blk) there may be no Default-Comment/Empty Lines within the code of the

LCONF-Default-Template-Structure.
within Lists (between default list items) there may be no Default-Comment/Empty Lines within the code of the

LCONF-Default-Template-Structure.

LCONF is distributed under the terms of the BSD 3-clause license. Consult LICENSE.rst or http://opensource.org/licenses/BSD-3-Clause.

LCONF: Specification 7.0¶

Specification¶

Indentation¶

LCONF-Default-Template-Structure¶

Default-Comment/Empty Lines¶

Strings¶

Comment-Line Identifier¶

Key :: Value Separator¶

Key :: Value Pair¶

Empty Key :: Value Pairs¶

Lists¶

List Identifier¶

Key :: Value-List¶

Key-Value-List¶

List-Of-Tuples¶

Key-Value-Mapping¶

Repeated-Block¶

Repeated-Block-Identifier¶

Block-Names¶

Block-Name Items¶

Section Start/End Tags¶

Section Start TAG¶

Section End TAG¶

Restrictions¶

Restrictions Summary¶

Restrictions: Section Start/End Tag¶

Restrictions: Unique names¶

Restrictions: Item Types in Lists¶

Restrictions: No Trailing Spaces¶

Restrictions: Comments¶

Restrictions: Default-Comment/Empty Lines¶

Page contents

This Page

Navigation

LCONF: Specification 7.0¶

Specification¶

Indentation¶

LCONF-Default-Template-Structure¶

Default-Comment/Empty Lines¶

Strings¶

Comment-Line Identifier¶

Key :: Value Separator¶

Key :: Value Pair¶

Empty Key :: Value Pairs¶

Lists¶

List Identifier¶

Key :: Value-List¶

Key-Value-List¶

List-Of-Tuples¶

Key-Value-Mapping¶

Repeated-Block¶

Repeated-Block-Identifier¶

Block-Names¶

Block-Name Items¶

Section Start/End Tags¶

Section Start TAG¶

Section End TAG¶

Restrictions¶

Restrictions Summary¶

Restrictions: Section Start/End Tag¶

Restrictions: Unique names¶

Restrictions: Item Types in Lists¶

Restrictions: No Trailing Spaces¶

Restrictions: Comments¶

Restrictions: Default-Comment/Empty Lines¶

Page contents

This Page

Quick search

Navigation