Rev 5772: Add doc for the section matchers. in file:///home/vila/src/bzr/experimental/config/

[Vincent Ladeuil]

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

------------------------------------------------------------
revno: 5772
revision-id: v.ladeuil+lp at free.fr-20110408161323-42psi0xivm82gmt3
parent: v.ladeuil+lp at free.fr-20110408160549-qzi8b5sjrtzod9u5
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: config-section-matchers
timestamp: Fri 2011-04-08 18:13:23 +0200
message:
  Add doc for the section matchers.
-------------- next part --------------
=== modified file 'bzrlib/config.py'
--- a/bzrlib/config.py	2011-04-08 16:05:49 +0000
+++ b/bzrlib/config.py	2011-04-08 16:13:23 +0000
@@ -2341,7 +2341,7 @@
         self.store = store
 
     def get_sections(self):
-        # This is where we requires loading the store so we can see all defined
+        # This is where we require loading the store so we can see all defined
         # sections.
         sections = self.store.get_sections()
         # Walk the revisions in the order provided

=== modified file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt	2011-04-08 15:59:11 +0000
+++ b/doc/developers/configuration.txt	2011-04-08 16:13:23 +0000
@@ -48,3 +48,21 @@
 basis for new classes which only need to register themselves in the right
 places to inherit from the existing basic tests and add their own specific
 ones.
+
+Filtering sections
+------------------
+
+For some contexts, only some sections from a given store will apply. Defining
+which is what the ``SectionMatcher`` are about.
+
+The main constraint here is that a ``SectionMatcher`` should delay the loading
+of the associated store as long as possible. The constructor should collect
+all data needed for the selection and uses it while processing the sections in
+``get_sections``.
+
+Only ``ReadOnlySection`` objects are manipulated here but a ``SectionMatcher``
+can return dedicated ``Section`` to provide additional context (the
+``LocationSection`` add an ``extra_path`` attribute to implement the
+``appendpath`` policy for example).
+
+.. FIXME: Replace the appendpath example if/when it's deprecated ;)