Patchwork [7,of,7,evolve-ext] exthelper: update documentation with some examples for using registrar aliases

login
register
mail settings
Submitter Matt Harbison
Date Jan. 3, 2019, 5:30 a.m.
Message ID <a0b03d4cda7acec8e544.1546493454@Envy>
Download mbox | patch
Permalink /patch/37438/
State Accepted
Headers show

Comments

Matt Harbison - Jan. 3, 2019, 5:30 a.m.
# HG changeset patch
# User Matt Harbison <matt_harbison@yahoo.com>
# Date 1546491714 18000
#      Thu Jan 03 00:01:54 2019 -0500
# Node ID a0b03d4cda7acec8e544e7c68041e876515c7dad
# Parent  0579af34a326c7a8d88aac713202bb6e90436bae
exthelper: update documentation with some examples for using registrar aliases
Matt Harbison - Jan. 3, 2019, 5:40 a.m.
On Thu, 03 Jan 2019 00:30:54 -0500, Matt Harbison <mharbison72@gmail.com>  
wrote:

> # HG changeset patch
> # User Matt Harbison <matt_harbison@yahoo.com>
> # Date 1546491714 18000
> #      Thu Jan 03 00:01:54 2019 -0500
> # Node ID a0b03d4cda7acec8e544e7c68041e876515c7dad
> # Parent  0579af34a326c7a8d88aac713202bb6e90436bae
> exthelper: update documentation with some examples for using registrar  
> aliases

This syncs up with what's currently in default in the hg repo.  The tests  
on Windows are in sad shape, so I didn't make it through all of them.  But  
hopefully any problems are trivially fixable.  It looks like the revsets  
are being registered (I manually tried):

     ../../hg/hg.exe --config extensions.evolve=../hgext3rd/evolve help  
revsets.troubled

But it looks like the templates may not be registered.  I also didn't try  
older versions of Mercurial.

I don't think there is much left to do- the only potential issues I found  
were:

   1) the inability to wrap functions in an extension like a command in an  
extension can be wrapped
   2) no simple way to skip @eh.uisetup for a non local repo.

Maybe the latter isn't that important.  And it doesn't seem like evolve  
needs either, so maybe that can be only for upstream, if needed.

Patch

diff --git a/hgext3rd/evolve/exthelper.py b/hgext3rd/evolve/exthelper.py
--- a/hgext3rd/evolve/exthelper.py
+++ b/hgext3rd/evolve/exthelper.py
@@ -19,10 +19,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):
@@ -269,9 +316,18 @@ 
         This function takes two arguments, the container and the name of the
         function to wrap. The wrapping is performed during `uisetup`.
 
+        Adding attributes to a container like this is discouraged, because the
+        container modification is visible even in repositories that do not
+        have the extension loaded.  Therefore, care must be taken that the
+        function doesn't make assumptions that the extension was loaded for the
+        current repository.  For `ui` and `repo` instances, a better option is
+        to subclass the instance in `uipopulate` and `reposetup` respectively.
+
+        https://www.mercurial-scm.org/wiki/WritingExtensions
+
         example::
 
-            @eh.function(context.changectx, 'babar')
+            @eh.addattr(context.changectx, 'babar')
             def babar(ctx):
                 return 'babar' in ctx.description
         """