diff mercurial/help/internals/config.txt @ 34932:fd78276948b4 stable

internal-doc: document the config register mechanism

This explains the various usage and feature of the config register introduced
in Mercurial 4.3 and 4.4.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/help/internals/config.txt	Fri Oct 27 18:19:07 2017 +0200
@@ -0,0 +1,108 @@
+All config options used within Mercurial should be registered.
+
+Config Option in Core
+=====================
+
+Config options used by Mercurial core are registered in the
+``mercurial.configitems`` module.
+
+Simple entry
+------------
+
+A registration entry typically looks like::
+
+    coreconfigitem('section', 'option',
+        default=MyDefaultValue,
+    )
+
+Once registered, Mercurial will know that ``section.option`` is a legitimate
+config option and that ``MyDefaultValue`` should be used if no other values are
+defined in configuration files.
+
+Complex default value
+---------------------
+
+If the default provided is a callable, it is called to retrieve the default
+value when accessing the config option. This is useful for default value that
+are mutable like the empty list::
+
+    coreconfigitem('pager', 'ignore',
+        default=list,
+    )
+
+In addition, there are cases where the default is not fixed, but computed from
+other properties. In this case, use the ``dynamicdefault`` object as value for
+the ``default`` parameters. A default value is then explicitly required when
+reading the option::
+
+    # registration
+    coreconfigitem('web', 'name',
+        default=dynamicdefault,
+    )
+
+    # usage
+    ui.config('web', 'name', dirnam)
+
+Free form options
+-----------------
+
+Some config sections use free form options (e.g. ``paths``). You can register
+them using the ``generic`` parameters::
+
+    coreconfigitem('paths', '.*',
+        default=None,
+        generic=True,
+    )
+
+When ``generic=True`` is set, the option name is matched as a regular expression
+(rooted to string start). It can be used to select specific sub parameters::
+
+    coreconfigitem('merge-tools', br'.*\.args$',
+        default="$local $base $other",
+        generic=True,
+        priority=-1,
+    )
+
+The ``priority`` parameter control the order used to match the generic pattern
+(lower first).
+
+Config Option in Extensions
+===========================
+
+General case
+------------
+
+Extensions should register config items through the ``registrar`` API (also used
+for commands and others)::
+
+    configtable = {}
+    configitem = registrar.configitem(configtable)
+
+    configitem('blackbox', 'dirty',
+        default=False,
+    )
+
+The ``dynamicdefault`` object is then available as
+``configitem.dynamicdefault``.
+
+Supporting older version
+------------------------
+
+The register was introduced in Mercurial 4.3, the ``generic`` parameter was
+introduced in 4.4. Starting with Mercurial 4.4, all core options were registered
+and developer warnings are emitted when accessing unregistered option.
+
+Extensions supporting version older than Mercurial-4.3 cannot rely on the
+default value registered. The simplest way to register option while still
+supporting older version is to use ``dynamicdefault`` for option requiring a
+default value. The existing code passing an explicit default can then stay in
+use until compatibility to Mercurial 4.2 is dropped.
+
+As reminder here are the default value for each config types:
+- config:      None
+- configbool:  False
+- configbytes: 0
+- configdate:  None
+- configint:   None
+- configlist:  []
+- configpath: None