The OpenBlox configuration system

New in version 0.6.

Changed in version 0.7: Removed required and optional sections; added the following sections:

  • core
  • core.gfx
  • core.hardware

History

This configuration format came into existence due to the fact that OpenBlox needed a way to let non-programmers easily modify the performance and (to a lesser extent) the behavior of OpenBlox.

So, the OpenBlox configuration format was created, with syntax borrowed from the familiar Windows .ini configuration format.

How the average config file looks

To give you a taste of the simplicity of the OpenBlox configuration format (hereon referred to as “the obconf.cfg format”, as that is the customary name for the configuration file), here is the default configuration file that ships with OpenBlox:

[core]

log-level = debug
log-file = oblog.txt

[core.gfx]

frame-rate = 45
show-frame-rate = yes
use-shadows = no
resolution = 1024x768

[core.hardware]

a_key = a
b_key = s
x_key = x
y_key = c

You can probably understand most (if not all) of this already, without any explanation whatsoever.

Main options

Basic syntax

The obconf.cfg file format basically looks like this:

# This is a comment, to help others understand what you're doing

[a section]

# You can have a comment basically anywhere, because
# anything after the pound symbol is ignored.
# Though, this means you can't have a line that starts
# with a comment and ends with a variable assignment, for example.

# Set "variable" in "a section" to have a value of "value"
variable = value

[another section]

# This doesn't change the value of "variable" in "a section"; this
# is a completely different variable!
# This is because it is defined in a different section ("another section")

variable = value2

Common gotchas

  • Variable names cannot have spaces
  • Section names cannot include either [ or ]

API Reference

exception obengine.cfg.NoSuchOptionError
Raised when a requested configuration variable isn’t found.
exception obengine.cfg.NoSuchSectionError
Raised when a requested section isn’t found.
class obengine.cfg.Config

A Borg [2] class.

load(filename)

Loads all the configuration variables located in filename.

Parameter:filename (str) – The name of the configuration file to load
get_var(name[, section='core', default=None])

Retrieves configuration variable name out of section.

Parameters:
  • name (str) – The configuration variable to retrieve
  • section (str) – The section the configuration variable is stored in
  • default – The default value to return, if the requested variable doesn’t exist.
Returns:

The value of the configuration variable named name

Raises:

NoSuchOptionError if the given section exists, but the variable doesn’t; NoSuchSectionError if the given section doesn’t exist.

Note

If default is not None, then default is returned, instead of an exception being raised.

add_var(name, val[, section='core'])

Adds a configuration variable named name, with a value of val under section.

Parameters:
  • name (str) – The name of the configuration variable to add
  • val – The value of the new configuration variable
  • section (str) – The section to put the new configuration variable under

Footnotes

[1]A virtual key is a facility OpenBlox provides so games can receive keyboard-like input on many different operating systems (including iOS and Android), without having to know which keys each gamer prefers to use (or if the device they’re playing on has any real keys at all!)
[2]http://code.activestate.com/recipes/66531-singleton-we-dont-need-no-stinkin-singleton-the-bo/