[Scummvm-devel] Config-file system

[Nicolas Noble]

Hello

Here is a little crash course about how the config-file system works.

The object Config can store pairs of (key,value). Those pairs are stored
into domains. So if the config-file is:

[scummvm]
fullscreen=true
[tentacle]
path=C:\dott\
tempo=0x1234567

the domain 'scummvm' contains the pair (fullscreen, true)
and the domain 'tentacle' contains the pairs (path, C:\dott\) and (tempo,
0x1234567)

The flush() method ask the object to write down the config file. The
config file name is given in the constructor, and can be changer with
change_filename()

You can set a pair with the method set(key, value, domain). The domain
argument is optionnal. You can do set_domain() or get_domain() to set/get
the default domain when it is not given in the 'set' method.

You can read a value with get(key, domain), where the domain argument is
optionnal. It is the same as 'set' about the domain.


Next, the domains can be manipulated in the following ways:
  -) you can delete a domain with delete_domain. Please don't delete the
'default' domain or do a set_domain just after it.
  -) you can rename the current domain with rename_domain
But the last function can hit another domain. For example if you have

[domain1]
key1=value
key=value1

[domain2]
key2=value
key=value2

if the default domain is 'domain1' and you do rename_domain("domain2")
then there will be a collision on "key". So what will happen? The object
won't choose it randomly of course: it will keep the old value, ie the
value of the domain 'domain2', and the final config will be:

[domain2]
key1=value
key2=value
key=value2


The last but not the least:

it is possible to merge two Config objects. And it's a kind of extend of
the domain renaming: if you do:

config1->config_merge(config2)

then all the domains of config2 will be copied into config1, but it will
never overwrite any duplicate key into config1.


SO, when you look at the code into scummvm, you will be able to understand
that, when you load a config file using -l, it won't overwrite any
previous argument of the command like. For example, if 'path' for the game
tentacle in the config file another.ini is defined as 'C:\DOTT', and if
you type the command

scummvm -p D:\DOTT -l another.ini tentacle

then the path will finally be 'D:\DOTT'.


I hope I was clear =)