Changes between Version 3 and Version 4 of TracDev/ConfigApi

Timestamp:

Jan 7, 2011, 6:46:26 PM (13 years ago)

Author:

Sebastian Krysmanski <sebastian@…>

Comment:

listing known options

TracDev/ConfigApi

@@ -62 +62 @@
 }}}
 
-== Defining options ==
+== Defining options == #defining_options
 While you can use `config.set()` to store values for arbitrary options, there's also a way to tell Trac which options are available. To do this, create a component and specify the option like this:
 
@@ -165 +165 @@
 }}}
 
-== Listing available options == #listing_options
+== Listing known options == #listing_options
+Beside retrieving the value of a certain option, there are also methods for listing all known options.
+
+ * `config.sections()`: Returns a list of the names of all known sections.
+ * `config.options(section_name)`: Returns a list of `(name, value)` tuples for all known options in the specified section.
+ * `config.defaults()`: Returns a dict with the default values of all known options (that have one) in all known sections.
+
+A "known option" in this context is an option that
+
+ * is defined like described in the section [#defining_options Defining Options] above
+ * and/or has value assigned to it.
+
+Furthermore, there is a way to list all ''defined'' options. This is done by using `Option.registry` which is a dict with `(section_name, option_name)` keys. The value for each key is the `Option` object that defines the option (not its current value). The following example will list the descriptions of all defined options:
+
+{{{
+#!python
+for (section_name, option_name), option in Option.registry.items():
+    print option.__doc__
+}}}