LCONF: Specification Abstract

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

• in many situations LCONF is a suitable replacement for YAML
• LCONF can be used to replace JSON in many cases

Note

LCONF_Specification-7.0

LCONF Specification 7.0 should be backwards compatible with version 6.0

• adds support for setting: optional Empty-KeyValuePair-ReplacementValues in the

  LCONF-Default-Template-Structure

  • for instance: a integer value is expected but one wants for empty LCONF Key :: Value Pairs to return -1 or whatever

Designed around

• READABILITY

• NAMED SECTIONS

• FOUR MAIN STRUCTURES

• VALUE TRANSFORMATION

• ORDER

• DEFAULT VALUES

• PRETTY EMITTING/DUMPING

  • inclusive Default Comments

Readability

• Sections
• Lines
• Indentation
• Strings
• # Comments
• # Default-Comment/Empty Lines
• Only a few special Identifier Tags

Named Sections

Named Sections allow for extended text/info/explanations before or after a Section without the need of # Comment tags.

Multiple LCONF-Sections can be within one LCONF text source or file

Four Main Structures

Key :: Value Pairs

my name key :: assigned value

Lists

There are 3 sub types of lists:

Key :: Value-Lists: oneline lists

- name list :: Tim,Joe,Peter

Key-Value-Lists: multiline lists: values with indentation: basically just an different way to write/read it

- name list
   Tim
   Joe
   Peter

List-Of-Tuples: multiline list of tuples: values with indentation

• each tuple must have at least 2 values
• all tuples must have the same number of items as columns defined

- list of RGB colors |Color Name|Red|Green|Blue|
   forestgreen,   34,   139,  34
   brick,         156,  102,  31

Key-Value-Mappings

Items with indentation: each item can be any of the Four Main Structures

. my mapping key
   key :: value
   - name list :: Tim,Joe,Peter

Repeated Blocks

Block item can be any of the Four Main Structures

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

Value Transformation

LCONF implements the idea of easy item value transformation. Any Item-Value must be easily transformable using customary hook functions or some other ways to achieve such: depending on the library language. Such are implemented in the LCONF-Default-Template-Structure.

Value Transformation is mostly used for type transformation (type casting) because:

basic LCONF is on purpose only text/string based

• of course such transformation function could do also any other complex transformation

Within the LCONF-Default-Template-Structure transformation functions can only be applied to:

Key :: Value Pairs: each one can have a separate transformation function

Important

Empty values with transformation-function are returned as empty strings

SeeAlso

EXCEPTION: Empty-KeyValuePair-ReplacementValues

Empty Key :: Value Pairs`

Key :: Value-Lists and Key-Value-Lists: can have only one transformation function which will be applied to each item in the list

List-Of-Tuples:

• can have one transformation function which will be applied to each item in each tuple of the list
• or can have for each value (column) a separate transformation function which will be applied to each line (row)

Warning

Empty values with transformation-function are returned as empty strings

Order

LCONF is ordered

Important

Any order will always be based on the LCONF-Default-Template-Structure and not on the LCONF text source/file

EXCEPTIONS:

• the order of Block-Names of (Repeated-Block-Identifiers):

  will be always as in the ‘LCONF text source/file’ (as they are not previously known)

• the order of Lists items:

  will be always as in the ‘LCONF text source/file’ (as they are not previously known)

Default Values

LCONF is based on the idea of a: predefined LCONF-Default-Template-Structure.

• This gives it order, default values and one knows what to expect.

• helps to emit/dump in proper order based on the structure

  • inclusive any Default-Comment/Empty Lines
  • Any LCONF library must implement an option to emit/dump any Repeated Block with an optional ‘dummy-blk’ with default values.

• the only thing which is not pre-known are:

  • the user set values

  • the number of items in lists

  • the number of Block-Names in Repeated Blocks

    but Repeated Blocks have an option to predefine: NUMBER_MIN_REQUIRED_BLOCKS, NUMBER_MAX_ALLOWED_BLOCKS

• Because all structures must be previously implemented within the code (LCONF-Template-Default-Structure)

  any library which implements the LCONF: human-friendly, simple readable data serialization format should give some thoughts as how do write such LCONF-Template-Default-Structure in a simple form

• parsing a LCONF-Section (string/file) will just overwrite any default values

  So the simplest LCONF is only a START/END TAG:

  which will be parsed to all implemented defaults as nothing gets overwritten There won’t be any Repeated Blocks because there are no default Block-Names set.

  LCONF-Example

  ___SECTION :: DefaultLCONF
  ___END
  

Note

To get Default-Values do not define the item in the ‘LCONF text source/file’

• EXCEPTIONS:

  • for Repeated Blocks: to get the Default-Values for a whole Block: only define the Block-Identifier and the Block-Name without any items

Pretty Emitting/Dumping

LCONF actively supports pretty printing (emitting/dumping).

• By design there is a strict predefined outline of indentation, structure ect..

• For list items there are 2 option implemented:

  • oneline lists: empty lists or usually used for lists with few items

  • multiline lists with item indentation: usually used for lists with more items

    • List-Of-Tuples: are always multiline lists

• # Default-Comment/Empty Lines

  • unlike many other formats LCONF design has full support for emitting/dumping of Default-Comment/Empty Lines

    • such must be implemented in the LCONF-Template-Default-Structure

  Warning

  LCONF does not support parsing # Comment lines from the ‘LCONF text source/file’

  • Such are skipped by design

Relation To Json - Yaml

Important

REPLACEMENT

• in many situations LCONF is a suitable replacement for YAML
• LCONF can be used to replace JSON in many cases

Any base LCONF (string representation) without transformation can be dumped as a valid json obj (array) which is also a valid yaml.

BUT not every json array/object or yaml might be represented as a valid LCONF-Section

• e.g. LCONF does not support list to have nested dictionary items or other lists

Note

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

  • one can not >> just parse << a ‘LCONF text source/file’

• LCONF has some additional features e.g.:

  • there is an option to loop over all keys in order as implemented by the: LCONF-Default-Template-Structure
  • support for output of Default-Comment/Empty Lines

• LCONF supports customary transform functions: json/yaml may not be able to handle the type of such transformation

  • but the base LCONF (string representation) should be ok