changeset 41074:c81bb97b0cac

exthelper: add some examples for using registrar aliases Maybe it's my general lack of python knowledge, but how to use these would be way too obscure for me otherwise.
author Matt Harbison <matt_harbison@yahoo.com>
date Fri, 28 Dec 2018 00:51:02 -0500
parents 8f40e21ca842
children 72d4a1761fbc
files mercurial/exthelper.py
diffstat 1 files changed, 49 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/mercurial/exthelper.py	Thu Dec 27 23:46:35 2018 -0500
+++ b/mercurial/exthelper.py	Fri Dec 28 00:51:02 2018 -0500
@@ -21,10 +21,57 @@
 class exthelper(object):
     """Helper for modular extension setup
 
-    A single helper should be instantiated for each extension. Helper
-    methods are then used as decorators for various purpose.
+    A single helper should be instantiated for each module of an
+    extension, where a command or function needs to be wrapped, or a
+    command, extension hook, fileset, revset or template needs to be
+    registered.  Helper methods are then used as decorators for
+    these various purposes.  If an extension spans multiple modules,
+    all helper instances should be merged in the main module.
 
     All decorators return the original function and may be chained.
+
+    Aside from the helper functions with examples below, several
+    registrar method aliases are available for adding commands,
+    configitems, filesets, revsets, and templates.  Simply decorate
+    the appropriate methods, and assign the corresponding exthelper
+    variable to a module level variable of the extension.  The
+    extension loading mechanism will handle the rest.
+
+    example::
+
+        # ext.py
+        eh = exthelper.exthelper()
+
+        # As needed:
+        cmdtable = eh.cmdtable
+        configtable = eh.configtable
+        filesetpredicate = eh.filesetpredicate
+        revsetpredicate = eh.revsetpredicate
+        templatekeyword = eh.templatekeyword
+
+        @eh.command('mynewcommand',
+            [('r', 'rev', [], _('operate on these revisions'))],
+            _('-r REV...'),
+            helpcategory=command.CATEGORY_XXX)
+        def newcommand(ui, repo, *revs, **opts):
+            # implementation goes here
+
+        eh.configitem('experimental', 'foo',
+            default=False,
+        )
+
+        @eh.filesetpredicate('lfs()')
+        def filesetbabar(mctx, x):
+            return mctx.predicate(...)
+
+        @eh.revsetpredicate('hidden')
+        def revsetbabar(repo, subset, x):
+            args = revset.getargs(x, 0, 0, 'babar accept no argument')
+            return [r for r in subset if 'babar' in repo[r].description()]
+
+        @eh.templatekeyword('babar')
+        def kwbabar(ctx):
+            return 'babar'
     """
 
     def __init__(self):