Rev 5533: Layout the new design a bit more. in file:///home/vila/src/bzr/experimental/config/

[Vincent Ladeuil]

At file:///home/vila/src/bzr/experimental/config/

------------------------------------------------------------
revno: 5533
revision-id: v.ladeuil+lp at free.fr-20110330130702-3fpded26cxyr4bk1
parent: v.ladeuil+lp at free.fr-20110329081421-kstkris4oc3bz8em
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: doc-new-config
timestamp: Wed 2011-03-30 15:07:02 +0200
message:
  Layout the new design a bit more.
-------------- next part --------------
=== modified file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt	2011-03-11 17:00:23 +0000
+++ b/doc/developers/configuration.txt	2011-03-30 13:07:02 +0000
@@ -179,7 +179,7 @@
 be ready to handle *invalid* values by warning the user and fallback to a
 default value. Likely, if an option is not defined in any configuration
 file, the code should fallback to a default value (helpers should be
-provided by the API to handle common cases, warning the user, getting a
+provided by the API to handle common cases: warning the user, getting a
 particular type of value, returning a default value).
 
 This also ensures compatibility with values provided via environment
@@ -220,7 +220,7 @@
 Another implementation could be envisioned though: when a loop is
 encountered, we can fall back to the less specific configurations. This
 allows list values to refer to the definition in the less specific
-configurations allowing::
+configurations::
 
   bazaar.conf:
     debug_flags = hpss
@@ -442,15 +442,18 @@
 --------------------
 
 An option can be:
-* read
+* read (from a stack of 
 * created
 * modified
 * deleted
 
 A config file can define:
-* one or several sections
+
+* one or several sections. A unique section identifier is required if more
+  than one section is defined.
 * each section can contain one or several option definitions
 
+
 Developer facing concepts
 -------------------------
 
@@ -458,30 +461,91 @@
 ~~~~~~
 * name
 * help
-* default value (optional) ?
+* default value (optional)
 * list of allowed Config IDs (this allows a list of possible
   config files in bazaar.conf only option and use it while
   bootstrapping the config creations)
+* blacklist of config IDs (some options *can't* be stored (modified) by the
+  user)
+
+OptionRegistry
+~~~~~~~~~~~~~~
+* ensures that an option ID is a unique name
 
 Section
 ~~~~~~~
-* name (DEFAULT is a synonym for None somehow)
-* dict of (name, value) pair defining options
-* dict of (name, value) pairs for section specific options
-  (relpath) this can't be changed by the user
-
-
-Config
-~~~~~~
-* ID
-* list of Sections in priority order
-* dict of (name, value) pairs for config specific options
-  (path) this can't be changed by the user
-
-ConfigFile
-~~~~~~~~~~
+* section ID (for a given Store)
+* dict of (name, value) pairs defining options
+
+* dict of (name, original_value) pairs used to detect conflicting
+  modifications
+
+Stack
+~~~~~
+* A list of read-only Section/Stack objects
+
+* A single mutable Section object and its associated Store (defined only if
+  the stack support modification)
+
+* a lazy cache for the option values (should be reset on modifications as
+  interpolations will make it tricky to update incrementally).
+
+* ensures that the Stores involved generate as less IOs as possible
+
+* ensures that the transaction is the object life time (i.e. modifications
+  will be taken into account *iff* they are comitted explicitly).
+
+ConfigRegistry
+~~~~~~~~~~~~~~
+
+* ensures that a config ID is a unique identifier
+* register Stacks
+
+Store
+~~~~~
+
 * url
-* list of Sections
-
-
-relationship between Config and ConfigFile still unclear. an config specific env is needed intuitively, but do we need to make ConfigFile to inherit from Config and make Config use a list of Configs instead of a list of Sections ?
+* config ID
+* can serialize/deserialize a dict of Sections
+* can cache reads and writes
+* ensures that the transaction is the object life time (i.e. modifications
+  will be taken into account *iff* they are comitted explicitly).
+* can be read-only or read/write at build time
+* can provide an ordered list of Section for a given context
+
+Examples
+--------
+
+section examples
+~~~~~~~~~~~~~~~~
+
+* os.environ
+* options provided on the command-line
+* actual branch.conf
+* any section in a Store
+* a dict for section or store specific options ('relpath', 'nick', etc)
+
+store examples:
+~~~~~~~~~~~~~~~
+
+* ConfigObj (bazaar.conf)
+
+* DB (<scheme>://bazaar.launchpad.net/bazaar.conf)
+
+stack examples
+~~~~~~~~~~~~~~
+
+The actual GlobalConfig will become a stack with:
+* options from the command-line
+* os.environ
+* the default section from bazaar.conf
+
+The actual BranchConfig will become a stack with:
+* options from the command-line
+* os.environ
+* a stack for the matching sections in locations.conf
+* a stack for the matching sections in branch.conf
+* a stack for the matching sections in bazaar.conf
+
+The modifications will be made to the section in branch.conf specified when
+building the branch config object (generally the default section).