# qvikconfig

qvikconfig is a parser of a simple config file syntax called the qvikconfig format. The basic syntax is 'property = value'.

qvikconfig offers two main functions: `parse` and `dump`. Use `parse` to read config files and `dump` to write them.

# Documentation

To see an example of qvikconfig config files and how to parse and dump them, see the files in the `tests/` directory of the distribution. Alternatively, these examples can be downloaded from <http://metanohi.org/projects/qvikconfig/>.

qvikconfig can be considered a dictionary that can link both single values and lists of values to named properties. Entries are line-separated. A simple example:

    # This is a comment.
    name = Example # This is also a comment.
    descriptions = This is an example, Dette er et eksempel

When parsed, this will be translated to this Python dict:

> {'name': 'Example', 'descriptions': ['This is an example', 'Dette er et eksempel']}

It is, in most cases, optional to enclose strings in quotes. Whitespace is completely optional.

## Lists

qvikconfig uses the comma character to split values, as seen in the example above. When there is only one value associated with a property, there will be no list. Otherwise there will be one. To create a list of only one value, append two commas to your value, like this:

    a-list=24,,

This returns this dict:

    {'a-list': [24]}

## Accepted data

qvikconfig accepts and understands strings, numbers, True, False, and None. Everything else normally results in unknown behavior.

Strings are represented using text, sometimes enclosed in quotes. Numbers are represented using numbers. True, False and None are represented by true, false and none.

## Using more than one line

You can spread lists across several lines like this:

    long list = A,
    B, C, D,
    E, F, G,
    H, I, J,
    K, L, M,
    N, P, O

This will, naturally, result in this dict:

    {'long list': ['A', 'B', 'C', 'D', 'E', 'F',
    'G', 'H','I', 'J', 'K', 'L', 'M', 'N', 'P', 'O']}

You can make single values take up more than one line like this:

    a value = The wall had moved away from the boundaries of the house.

..which creates this when parsed:

    {'a value': 'The wall had moved away from the boundaries of the house.'}

## Escaping text

Certain strings cannot be represented in qvikconfig config files without being enclosed in quotes. The strings 'true', 'false' and 'none' must have quotes (both "..." and '...' are accepted), for example. The same goes for, in the case of values, strings containing commas and quotes or ending with a backslash, and in the case of properties, equal signs. While spaces and tabs are just fine, newlines (and carriage returns and so on) must be enclosed in quotes. Example:

    # The equality sign is not a comma.
    '=' = 'not a ,'

..resulting in:

    {'=': 'not a ,'}

## Version information

This is version 0.1.1 of qvikconfig. New releases are made available online at the website mentioned earlier.

Copyright (C) 2010 Niels Serup License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.