= Configuration (trac.ini) API =
Most of Trac's configuration is stored in the [TracIni trac.ini] file. Trac provides an API to retrieve and set the settings in this configuration file.

For the sake of this article, here's a quick reminder of the structure of `trac.ini`:

{{{
[wiki]   ; <= section
ignore_missing_pages = false  ; <= option with option value
max_size = 262144
render_unsafe_content = false
}}}

The file consists of multiple ''sections'' (written as `[sectionname]`). Each section consists of multiple ''options'' with their ''option values'' (like `ignore_missing_pages = false` in the example above). All options that come after the beginning of a section belong to this section - until a new section begins.

'''Note:''' The following examples will use `env.config` to access the configuration API. From within a [TracDev/ComponentArchitecture component] method you can use `self.config` to access the configuration API as well.

== Retrieving arbitrary option values ==
The easiest way to retrieve the value of a certain option is to use:

{{{
#!python
value = env.config.get('wiki', 'ignore_missing_pages')
}}}

The method `get()` will return the option value as string (type `unicode`). Of course, there are also methods to retrieve the option value in several other data formats:

{{{
#!python
env.config.get()      # as string
env.config.getbool()  # as bool
env.config.getint()   # as integer
env.config.getfloat() # as float; since Trac 0.12
env.config.getlist()  # as list
env.config.getpath()  # as absolute path
}}}

''Note:'' Most options have some meta data (data type, description) associated with them. For getting those meta data, see [#listing_options Listing Options] below.

== Setting arbitrary option values ==
Setting an option value is almost as easy as retrieving one. For this purpose, you need to use the method `set()`:

{{{
#!python
# the last parameter is the new option value ("False" in this case)
env.config.set('wiki', 'ignore_missing_pages', False)
env.config.save()
}}}

You also need to call `save()` to store the changes you've made to `trac.ini`.

There's just one thing you need to be aware of: 

  ''The option value must be a string! ''

This is not a problem for most data types - except for lists. When you want to save a list, write your code like this:

{{{
#!python
my_list = [ 'test1', 'test2' ]
env.config.set('my_section', 'my_option', ', '.join(my_list))
env.config.save()
}}}

== Defining options ==

== Retrieving the value of previously defined options ==

== Listing options == #listing_options