Mercurial > hg > mercurial-source
changeset 35715: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.
author | Boris Feld <boris.feld@octobus.net> |
---|---|
date | Fri, 27 Oct 2017 18:19:07 +0200 |
parents | 3f8273172636 |
children | 0217f75b6e59 |
files | contrib/wix/help.wxs mercurial/help.py mercurial/help/internals/config.txt tests/test-help.t |
diffstat | 4 files changed, 119 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/contrib/wix/help.wxs +++ b/contrib/wix/help.wxs @@ -42,6 +42,7 @@ <File Id="internals.bundles.txt" Name="bundles.txt" KeyPath="yes" /> <File Id="internals.censor.txt" Name="censor.txt" /> <File Id="internals.changegroups.txt" Name="changegroups.txt" /> + <File Id="internals.config.txt" Name="config.txt" /> <File Id="internals.requirements.txt" Name="requirements.txt" /> <File Id="internals.revlogs.txt" Name="revlogs.txt" /> <File Id="internals.wireprotocol.txt" Name="wireprotocol.txt" />
--- a/mercurial/help.py +++ b/mercurial/help.py @@ -202,6 +202,8 @@ loaddoc('censor', subdir='internals')), (['changegroups'], _('Changegroups'), loaddoc('changegroups', subdir='internals')), + (['config'], _('Config Register'), + loaddoc('config', subdir='internals')), (['requirements'], _('Repository Requirements'), loaddoc('requirements', subdir='internals')), (['revlogs'], _('Revision Logs'),
new file mode 100644 --- /dev/null +++ b/mercurial/help/internals/config.txt @@ -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
--- a/tests/test-help.t +++ b/tests/test-help.t @@ -980,6 +980,7 @@ bundles Bundles censor Censor changegroups Changegroups + config Config Register requirements Repository Requirements revlogs Revision Logs wireprotocol Wire Protocol @@ -3054,6 +3055,13 @@ Changegroups </td></tr> <tr><td> + <a href="/help/internals.config"> + config + </a> + </td><td> + Config Register + </td></tr> + <tr><td> <a href="/help/internals.requirements"> requirements </a>