The Official LCONF-Standard

Unfinished Version 8 (20150808)

The source of the documentation was rewritten in markdown format.
In the documentation Key-Value-Mappings are renamed to Single-Blocks.
Breaking changes:
- The LCONF-Section indentation level was previously exact 3 spaces per level. This new version of the LCONF-Standard allows that LCONF-Section specify there own number of spaces used per indentation level. For this reason the LCONF-Section start line format changed adding the indentation space number used for the section.
- Key :: Value-Lists: leading or ending whitespace of comma separated values are now required to be stripped.

Copyrights & Licenses

The LCONF-Standard documentation and associated documentation files (the "DOCUMENTATION") is licensed under the following terms:

Copyright (c) 2014, 2015: peter1000 https://github.com/peter1000.
All rights reserved.

The DOCUMENTATION may be freely copied, published and distributed to others, provided that the above copyright notice and this Copyright License are included on all such copies or substantial portions of the DOCUMENTATION.

However, the content of this DOCUMENTATION itself may not be modified in any way, including by removing the copyright notice, except as required to translate it into languages other than English or into a different format. In the event of discrepancies between a translated version and the official English version, the official English version shall govern.

THIS DOCUMENTATION AND THE INFORMATION CONTAINED HEREIN IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE DOCUMENTATION OR THE USE OF THE INFORMATION HEREIN.

1. Introduction

LCONF The light and simple readable data serialization format for dynamic configurations and data exchange.

It is a data serialization format designed with special emphasis on being human-friendly and works well with many modern programming languages. This is a complete specification of the information needed to develop applications for processing LCONF.

LCONF was specifically designed to be useful to people working with program configuration and configuration files as well as for other common use cases such as: data exchange, interprocess messaging, log files, cross-language data sharing.

It uses Unicode printable characters, containing the data itself and Indentation to provide structure in combination with very few Ascii characters which provide structural information. This excellent combination allows the data to show itself in a human-friendly, easily readable format.

1.1. Design Goals

The design goals for LCONF are, in no priority:

LCONF is easily writeable and readable by humans.
LCONF has minmal but strict structure.
LCONF allows optional Comment lines which are not part of the actual data.
LCONF was designed from the start to expect a predefined known structure with implemented default data.

1.2. Relation to other data serialization formats

LCONF builds upon some concepts from JSON, RSON, RSONLITE, INI, and YAML but has also a few destinct features.

In many situations LCONF is a suitable replacement for any of the others mentioned above.

1.3. Design Overview

DEFAULT VALUES

A major difference in design to many other data serialization formats is that LCONF was designed from the start to expect a predefined known structure with implemented default data.

Many programs which parse human written data input have to account that some parts of the input may be optional and provide some means of checking for such and in some cases default values must be set.

LCONF takes this as the base of its design and requires a parser/emitter to implement for any LCONF-Section a complete structure with default values. (LCONF-Default-Template-Structure)

LCONF parsed data only overwrite the defaults.

READABILITY

To help to be easily writeable and readable by humans LCONF supports:

Named-Sections: which helps to identify separate parts.
Empty Lines: which are skipped but help to maintain readability.
Default Comment Lines: which are not part of the data but can be optional emitted.
Indentation: is used to visualize some of the structure od a LCONF-Document.

NAMED-SECTIONS

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

Multiple LCONF-Sections can be within one LCONF-Document.

TWO STRUCTURES WHICH HOLD DATA

Key :: Value Pairs: Associates a key with a data value.
Lists: there are three sub types of lists:
- Key :: Value-Lists: single-line lists which associates a key with a list of data values.
- Key-Value-Lists: multi-line lists which associates a key with a list of data values.
- List-Of-Tuples: multi-line lists which associates a key with Column-Names to a list of column data values. This lends itself especially well to data similar to multi-dimensional lists or tables e.g. csv data.

TWO COLLECTION STRUCTURES

Single-Blocks: are a collections of any of the four main structure types. (Key :: Value Pairs, Lists, Single-Blocks and Repeated-Blocks)
Repeated-Blocks: are similar to Single-Blocks but additionally allow the configuration of multiple such blocks within a LCONF-Section.

ORDER

LCONF-Structure is ordered so that emitting of the same LCONF-Document will result always in an identical representation. The order is based on the implemented LCONF-Default-Template-Structure.

2. LCONF-Standard Specification

2.1 Key-Value-Separator

" :: "

(one space, double colons, one space) is used as a Key-Value-Separator.

2.2 Trailing Spaces

LCONF does not allow any Trailing Space within a LCONF-Section.

2.3 LCONF's Native Data Type

Unlik JSON's basic types which are: strings, numbers, booleans, object, arrays, and nullLCONF has only one native type: strings.

String values are never quoted or escaped.

See also later the part of: Value Transformation.

2.4 Indentation

LCONF allows only spaces to be used as indentation. The number of spaces used per indentation level is set within the LCONF-Section opening line.

The example below would specify that 4 spaces are used per intentation level within the LCONF-Section named Example

___SECTION :: 4 :: Example
___END

2.5 Named-Sections

LCONF-Documents can contain multiple named LCONF-Sections. A LCONF-Section has a clear defined Start-TAGS and End-TAGS. Everything outside of these is considered additional text.

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

Section Start TAG

"___SECTION"

(three underlines, capital SECTION)

This is followed by a Key-Value-Separator and the number of spaces used per indentation level followed by a second Key-Value-Separator and the section name.

The LCONF-Section-Start-TAG must always be without any indentation.

___SECTION :: 4 :: the name can also contain spaces or unicode

Section End TAG

"___END"

(three underlines, capital END)

The LCONF-Section-End-TAG must always be without any indentation.

The most basic valid LCONF-Section is:

___SECTION :: 4 :: Example
___END

2.6 Comment-Lines

"#"

(one number sign) is used as Comment-Line-Identifier.

If the first none white character in a LCONF-Section line is # the line is considered a Comment-Line.

Comment-Lines must have the indentation level of the following line (disregarding empty lines). Comment-Lines within a LCONF-Section are always skipped when the LCONF-Section is parsed.

___SECTION :: 4 :: Example
# Comment-Line more info
- Names
    Tim
    Sandra
    # Comment-Line must have the indentation level of the following line
    Max
    Frank
___END

NOTE: Default Comment-Lines and Default-Empty-Lines which are implemented in the LCONF-Default-Template-Structure can be optionally emitted.

2.7 Two Structures Which Hold Data

Key :: Value Pairs

"Key-Name :: Value"

(one space, double colons, one space) is used as a Key-Value-Separator.

Exception: for Empty Values the last space is skipped so that there is no trailing space.

___SECTION :: 4 :: Example
Color :: Blue
FONT :: Liberation Mono
# Comment below is an Empty Value with no trailing space.
MyEmptyKeyValuePair ::
___END

Key :: Value Pairs are always single-line items where the value is everything after the Key-Value-Separator which and is always interpreted as a single string.

Lists:

"- "

(minus, one space) is used as List-Identifier for all three sub types of lists: "- List-Identifier Name"

Example of all tree LCONF-List types.

___SECTION :: 4 :: SectionName

# Key :: Value-List: a single-line list
- Names :: Tim,Sandra,Max

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

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

Key :: Value-Lists

These are ordered collections of items: a single-line list which associates a key with a list of data values which are separated by comma.

Uses a List-Identifier with a List-Name followed by a Key-Value-Separator and the values are separated by "," (comma).

IMPORTAND: leading or ending whitespace of comma separated values are stripped when a LCONF-Section is parsed.

Each List-Item is always interpreted as a single string. This implies that List-Items can not be any of the four main structure types. (Key :: Value Pairs, Lists, Single-Blocks and Repeated-Blocks)

Exception: for Empty Key :: Value-Lists the last space is skipped so that there is no trailing space.

___SECTION :: 4 :: Example
- Colors :: Black,White,Blue,Red,Green
# Comment below is an empty Empty Key :: Value-List with no trailing space.
- MyEmptyList ::
___END

Key-Value-Lists

These are ordered collections of items: a multi-line list which associates a key with a list of data values. Values are written on separate lines (List-Items) and use one indentation level based on the List-Identifier line.

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. whole sentences.

Uses a List-Identifier with a List-Name and any value is places on a new line with indentation.

Each List-Item is always interpreted as a single string. This implies that List-Items can not be any of the four main structure types. (Key :: Value Pairs, Lists, Single-Blocks and Repeated-Blocks)

Exception: for Empty Key-Value-Lists there is no new value line.

___SECTION :: 4 :: Example
- Names
    Tim
    Sandra
    Max
    Frank
# Comment below is an empty Empty Key-Value-Lists.
- MyEmptyList
___END

TIP: eventhough lists of lists are not supported one could mimice such by using for example a LCONF Key-Value-List and have as value comma separated lines which are later further proccessed.

___SECTION :: 4 :: SectionName
- Numers
    534,45
    0,1,2,3
    66
    12,4568,1,3,99,465,12
___END

The List-Item: 534,45 or 0,1,2,3 etc. are just normal string lines (item lines of an: Key-Value-List) e.g. one could use later a transformation function splitting each value line by comma.

NOTE: many of such caes might be better solved by using a List-Of-Tuples.

List-Of-Tuples

These are ordered collections of items: a multi-line list which associates a key with multiple Column-Names to a list of multiple column data values. This lends itself especially well to data similar to multi-dimensional lists or tables e.g. csv data.

Uses a List-Identifier with a List-Name followed by one space and unique Column-Names which are embraced and separated by "|" pipe sign (vertical bar).

List-Of-Tuples items value lines are written on separate lines (List-Items - rows) and use one indentation level based on the List-Identifier lin. Each lines values are separated by "," comma.

IMPORTANT: spaces around Column-Names and values are stripped which helps to write proper columns.

Exception: for Empty List-Of-Tuples there is no new value line but the Column-Names are still required.

___SECTION :: SectionName
# Comment: List-Name is "Colors RGB"
#          Columns are: "Color Name", "Red", "Green", "Blue"
- Colors RGB |Color Name| Red| Green| Blue|
    forestgreen,           34,   139,   34
    brick,                156,   102,   31
# Comment: below is an empty Empty List-Of-Tuples:
#          List-Name is "MyEmptyListOfTuples"
#          Columns are: "X", "Y", "Z"
 - MyEmptyListOfTuples |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. Any Replacement-Values must be implemented in the LCONF-Default-Template-Structure.

Example of a LCONF-List-Of-Tuples with Empty/Missing Values which will be returned as empty strings or with a defined per column Replacement-Value.

___SECTION :: SectionName
- ExcelTable |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

2.8 Two Collection Structures

Single-Blocks

". "

(dot, one space) is used as Single-Block-Identifier: ". Single-Block-Identifier Name"

These are a collections of any of the four main structure types. (Key :: Value Pairs, Lists, Single and Repeated-Blocks)

Single-Block items use one additional indentation level.

An Empty Single-Block-Identifier line 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.

In some cases this might be useful: e.g. if one wants previous comment lines.

___SECTION :: SectionName
. Single-Block whatever name
    single_block_item1_key :: single_block_item1_value
    - single_block_item2_key list
        my List-Item 1
    # Comment: Blocks can also have other (nested) Blocks
    . inner_single_block_item3_key
        inner_single_block_item1_key :: inner_single_block_item1_value
# Comment: below a permitted empty `Single-Block-Identifier` which will use all default values
. Single-Block 2
___END

Repeated-Blocks

"* "

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

These are similar to the Single-Blocks but additionally allow the configuration of multiple such blocks within a LCONF-Section.

A unique Block-Name which uses one additional indentation level defines a new Block and is written on a separate line.

Block-Name items use another additional indentation level.

An Empty Repeated-Block-Identifier line is permitted but without a Block-Name it does nothing. It is basically the same as if one does not define it at all.

In some cases this might be useful: e.g. if one wants previous comment lines.

___SECTION :: SectionName
* Color_BLK_Identifier
    Sky Blue_Blk-Name Theme
        blk_item_red :: 135
        blk_item_green :: 206
        blk_item_blue :: 235
    # Second Block-Name is an empty Block which uses all default values
    Red Theme
# Comment: below a permitted empty `Repeated-Block-Identifier` line which will do nothing because
# for Repeated-Blocks the main Structure item is a unique Block-Name.
* Color_BLK_Identifier 2
___END

NOTE: to get the Default-Values for a whole Block: only define the Block-Identifier and the Block-Name without any items.

Block-Names

Each Block of a Repeated-Block-Structure is named: Block-Names use one additional indentation level based on the Repeated-Block-Identifier line.

Empty Block-Names: if a Block-Name is defined without any items at all it is still valid using all defaults for such Block from the LCONF-Template-Default-Structure.

Any number of Block-Names can be user defined: but this can also be limited in a LCONF-Template-Default-Structure. (NUMBER_MIN_REQUIRED_BLOCKS, NUMBER_MAX_ALLOWED_BLOCKS)

3. LCONF Character Restrictions

Restriction: Section Start/End Tag

Character combinations ___SECTION, ___END are forbidden in any form except for the defined purpose. Each LCONF-Section Start-TAG must be closed by an corresponding LCONF-Section End-TAG.

LCONF does not allow nested Sections.

Restriction: Trailing Spaces

LCONF does not allow any Trailing Space within LCONF-Sections.

Restriction: FIRST none white character of a line

Some first none white character of a line are reserved as special purpose Identifiers. Any of them are permitted in the middle or end of a line.

- minus reserved only for all kind of Lists-Identifier
. dot reserved only for Single-Block-Identifier
* asterisk reserved only for Repeated-Block-Identifier
# number sign reserved only for Comment-Line-Identifier

Restriction: LAST character of a line

Key-Value-List-Identifier lines may NOT end with a 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.

List-Of-Tuples must contain as value tuples (row lines) with the same number of items as column-names specified. (empty items are allowed)

Restriction: Comment Lines indentation

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

Restriction: Unique names

LCONF requires that some of the Key-Names are unique.

all Main Keys (keys without any indentation) must be unique
within a List-Of-Tuples all Column-Names must be unique
withing a Single-Block all direct keys (keys with one additional indentation level) must be unique
within a Repeated-Block all direct keys (keys with one additional indentation level - Block-Names) must be unique
within each Named-Block of a Repeated-Block all direct keys (keys with one additional indentation level) must be unique

4. LCONF-Default-Template-Structure

LCONF requires a parser/emitter to implement for any LCONF-Section a complete structure with default values. Such LCONF-Default-Template-Structure implementation may differ from programming language and parser/emitter but there are some common requirements outlined below.

4.1 LCONF-Section Key Order

LCONF-Structure is ordered so that emitting of the same LCONF-Document will result always in an identical representation. The order is always based on the implemented LCONF-Default-Template-Structure and not on the LCONF-Section text.

Exception:

The order of Block-Names of Repeated-Blocks will always be as as in the LCONF-Section text because these are not previously known.
The order of Lists items will always be as in the LCONF-Section text because these are not previously known.

4.2 Default-Comment/Empty Lines

LCONF-Default-Template-Structure can implement Default-Comment/Empty Lines which can be optionally emitted.

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 multi-line Lists Key-Value-Lists or List-Of-Tuples there may be no Default-Comment/Empty Lines between default List-Items within the code of the LCONF-Default-Template-Structure.

4.3 Default Values

LCONF is based on the idea of a predefined LCONF-Default-Template-Structure which must fully implement any LCONF-Section.

This gives it order, default values and one knows what to expect.
This helps to emit/dump in proper order based on the implemented structure.
- inclusive any Default-Comment/Empty Lines
- Any LCONF library must implement an option to emit/dump any Repeated-Block with an optional 'Dummy-Block' with its default values.
Only a few things are not pre-known:
- Any LCONF-Section set values.
- The number of items in lists.
- The number of Block-Names in Repeated-Blocks.
- For special purposes LCONF-Template-Default-Structure Repeated-Blocks implementation can optional predefine some limitations: NUMBER_MIN_REQUIRED_BLOCKS, NUMBER_MAX_ALLOWED_BLOCKS
Because all structures must be previously implemented within the code any library which implements LCONF - The light and simple readable data serialization format should give some thoughts as how do write such LCONF-Template-Default-Structure as easily as possible.
Parsing a LCONF-Section (text/file) will just overwrite any default values.

So the simplest LCONF-Section is only a START/END TAG: which will be parsed to all implemented defaults as nothing gets overwritten.

NOTE: There won't be any Repeated-Blocks because there are no default Block-Names set.

4.4 Value Transformation

By design LCONF only supports string types for data values. However LCONF-Libraries can (and should, where appropriate) implement an easy way for value transformation using customary hook functions or some other ways to achieve such depending on the library language.