Configfile format - Revision history

Timo 6: Update categories

2012-09-01T10:34:13Z

Update categories

Timo 6: Formatting style updates

2012-08-27T13:09:02Z

Formatting style updates

Timo 6: 10 revisions: Import from old wiki (on 15 May 2012)

2012-08-26T17:21:22Z

10 revisions: Import from old wiki (on 15 May 2012)

New page

Many of VDrift's text-based data and configuration files are written in a format native to the game. The format is designed to be simple and easy to read, while flexibly storing many different kinds of data. It allows settings to be categorized into sections.

This format is defined by the '''CONFIG''' class in '''include/config.h''' and '''src/config.cpp'''.

==Features==
===Encoding===
Files in this format are interpreted as plain ASCII text. UTF-8 is not yet supported.

===Include directives===
Lines that start with '''include''' will load sections and settings from another file written in the format. The file may be named using a relative path, which follows the '''include''' keyword and a single space. If the same section exists in both files, a union of the two sections will result in the file which had the include directive. Values from the including file override those in the included file. Circular includes are repressed.

===Comments and Whitespace===
Comments begin with '''#''' and can occur at any point in a line. Everything following the '''#''' is ignored until the end of the line.

Whitespace before and after an identifier, name, or value is ignored; however, all spaces are preserved inside both section and setting identifiers. Line breaks are significant -- each line may contain only one section heading, '''include''' directive, or setting.

===Sections===
Sections (categories) are defined by a heading line with an identifier only. The section identifier may be placed between optional '''[''' and ''']''' brackets. Identifiers are case-sensitive.

Sections are categorical (flat), not hierarchical (nested). It is possible to create a category hierarchy by carefully naming each section, but the format does not provide any mechanism for managing or traversing a hierarchy.

Settings included in a section are all those on lines following the section heading, until the next section heading or the end of the file.

===Settings===
Settings (data items) are defined by a line with the form '''''name'' = ''value''''', where ''name'' is the identifier for the setting and ''value'' is the data for the setting. No restrictions are placed on the type, length, or formatting of the value stored in a setting. Setting identifiers are case-sensitive.

Settings before the first section heading have no section. They are referenced by their identifiers preceded by a '''.''' character.

====Value types====
The format employs a somewhat loose typing scheme. Settings do not need to have their types explicitly defined. In the game code, an item can be queried as any type, and depending on the value of the item, certain values can be interpreted differently when requested as different types.

Values can be requested as any of the following:
* booleans
* integer numbers
* floating point numbers
* strings
* lists

For instance, the item '''2nd.now''' from the example above would have the value ''1'' if interpreted as an integer. If interpreted as a boolean, its value would be ''true''; as a string, its value would be ''"1"''; as a floating-point number, its value would be ''1.0''.

====Booleans====
The following values will equal ''true'' and ''false'', respectively, when interpreted as boolean values:
* '''true''', '''false'''
* '''yes''', '''no'''
* '''on''', '''off'''
* '''1''', '''0'''

====Lists====
List settings may be defined by writing a list of values separated by commas instead of just a single value.

==Example==
A file in this format might look like this.
name = Example

[ first ]
stuff = 567
blah = hello
radius = 0.555

[ 2nd ]
beans = on
now = 1
position = 5,6,7

In the file, there are two categories, each with three data items. These items would be referenced by the following identifier strings, respectively:
* '''.name'''
* '''first.stuff'''
* '''first.blah'''
* '''first.radius'''
* '''2nd.beans'''
* '''2nd.now'''
* '''2nd.position'''

[[Category:Files]]
[[Category:Expand]]

Venzon: /* How data items' values are typed */

2007-04-20T14:10:55Z

How data items' values are typed

Venzon at 14:10, 20 April 2007

2007-04-20T14:10:12Z

Venzon at 14:08, 20 April 2007

2007-04-20T14:08:20Z

Venzon at 14:07, 20 April 2007

2007-04-20T14:07:24Z

New page

Many of VDrift's text-based data and settings files are written in a format native to the game. In the source code it is the CONFIGFILE class.

==Format==
* This format resembles the ini-style format somewhat.
* It is not heirarchical, it is categorical.
* Whitespace is almost entirely ignored, but line breaks are important.
* Comments are lines beginning with '''#'''.
* Categories are defined by a heading line with an identifier between '''[''' and ''']''' brackets.
* Data items are defined by a line with the form '''''name'' = ''value'''''
* Spaces are not allowed in item or category identifiers.
* Data values can be almost anything.
* Case is important for category and item identifiers, as well as string values, but nothing else.
* UTF-8 is not yet supported.

==Parsing==
The files are parsed one line at a time. Any characters after a # character are discarded (this is used to allow comments in the file). Characters [ and ] are stripped from the line. If a line has no = character, then the line is interpreted as a heading. Otherwise, the line is interpreted as a setting, with the characters to the left of the = character interpreted as the name of the setting, and the characters to the right of the = character interpreted as the value of the setting. Whitespace before and after the heading, name, or setting is stripped.

==Categories and data items==
In this format, categories are defined by a heading of the form <code>[ category ]</code> where ''category'' is the name of the category. Items in the category include all the items from the category heading to the next category heading, or the end of the file.

Items before the first category heading have no category. They are referenced by their names preceded by a '''.''' character.

==Example==
A file in this format might look like this.
name = Example

[ first ]
stuff = 567
blah = hello
radius = 0.555

[ 2nd ]
beans = on
now = 1
position = 5,6,7

In the file, there are two categories, each with three data items. These items would be referenced by the following identifier strings, in the order they occur:
* '''.name'''
* '''first.stuff'''
* '''first.blah'''
* '''first.radius'''
* '''2nd.beans'''
* '''2nd.now'''
* '''2nd.position'''

==How data items' values are typed==
The format employs a somewhat loose typing scheme. That is, data items do not need to have their types explicitly defined. In the game code, an item can be queried as any type, and depending on the value of the item, certain values can be interpreted differently when requested as different types. Values can be requested as strings, integers, floating point numbers, a vector of 3 floats, or boolean types. For instance, the item '''2nd.now''' from the example above would have the value ''1'' if interpreted as an integer. If interpreted as a boolean, its value would be ''true''; as a string, its value would be ''"1"''; as a floating-point number, its value would be ''1.0''.

The following values will equal ''true'' when interpreted as boolean values:
* true
* yes
* on
* 1
The obvious opposite values are equal to ''false''.

To have a value interpreted as a vector of 3 floats simply add commas between the three floats:
* somevector = 1.0, 2.1, 15

← Older revision		Revision as of 10:34, 1 September 2012
Line 73:		Line 73:

	[[Category:Files]]		[[Category:Files]]
−	~~[[Category:Expand]]~~

← Older revision		Revision as of 14:10, 20 April 2007
Line 55:		Line 55:

	To have a value interpreted as a vector of 3 floats simply add commas between the three floats:		To have a value interpreted as a vector of 3 floats simply add commas between the three floats:
−	* somevector = 1.0, 2.1, 15	+	* somevector = 1.0, 2.1, 4

@@ Line 1: / Line 1: @@
 Many of VDrift's text-based data and configuration files are written in a format native to the game. The format is designed to be simple and easy to read, while flexibly storing many different kinds of data. It allows settings to be categorized into sections.
-This format is defined by the '''CONFIG''' class in '''include/config.h''' and '''src/config.cpp'''.
+This format is defined by the ''CONFIG'' class in '''include/config.h''' and '''src/config.cpp'''.
 ==Features==
@@ Line 48: / Line 48: @@
 ====Lists====
 List settings may be defined by writing a list of values separated by commas instead of just a single value.
 ==Example==

@@ Line 4: / Line 4: @@
 * This format resembles the ini-style format somewhat.
 * It is not heirarchical, it is categorical.
-* Whitespace is almost entirely ignored, but line breaks are important.
+* Comments begin with '''#''' and can occur at any point in a line.
 * Categories are defined by a heading line with an identifier.  The identifier is commonly placed between '''[''' and ''']''' brackets for readability, but this is not actually required.
 * Data items are defined by a line with the form '''''name'' = ''value'''''
-* Spaces are allowed in item or category identifiers.
+* Whitespace before or after an identifier, name, or value is ignored, but line breaks are important.
 * Data values can be almost anything.
 * Case is important for category and item identifiers, as well as string values, but nothing else.