Changes between Version 1 and Version 2 of TracDev/ConfigApi

Timestamp:

Jan 7, 2011, 5:08:26 PM (13 years ago)

Author:

Sebastian Krysmanski <sebastian@…>

Comment:

Reading and setting option values

TracDev/ConfigApi

@@ -11 +11 @@
 }}}
 
-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. 
+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()`:
 
-== Defining new options ==
+{{{
+#!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