Patchwork [7,of,8] exthelper: add some examples for using registrar aliases

login
register
mail settings
Submitter Matt Harbison
Date Dec. 28, 2018, 6:47 a.m.
Message ID <dae589aba13fe0327b1a.1545979641@Envy>
Download mbox | patch
Permalink /patch/37376/
State Accepted
Headers show

Comments

Matt Harbison - Dec. 28, 2018, 6:47 a.m.
# HG changeset patch
# User Matt Harbison <matt_harbison@yahoo.com>
# Date 1545976262 18000
#      Fri Dec 28 00:51:02 2018 -0500
# Node ID dae589aba13fe0327b1a975a4d5b39dfd33ef4ff
# Parent  1ff39d5b72312a9ae3c4b9fc424fed25bbdd67b6
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.

Patch

diff --git a/mercurial/exthelper.py b/mercurial/exthelper.py
--- a/mercurial/exthelper.py
+++ b/mercurial/exthelper.py
@@ -21,10 +21,57 @@  from . import (
 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):