mercurial/registrar.py
author Matt Harbison <matt_harbison@yahoo.com>
Wed, 12 Sep 2018 23:10:59 -0400
changeset 39593 c8514f858788
parent 39122 5d3b58472660
child 40291 170926caf44c
permissions -rw-r--r--
tests: stabilize change for handling not quoting non-empty-directory The change originated in cb1329738d64. I suspect the problem is with the combination of (re) and the '\' to '/' retry on Windows. I've no idea if py3 on Windows needs the quoting, since it can't even run `hg` with no arguments. (It's dying somewhere on the ctype declarations when win32.py is imported.)
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
27583
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
     1
# registrar.py - utilities to register function for specific purpose
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
     2
#
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
     3
#  Copyright FUJIWARA Katsunori <foozy@lares.dti.ne.jp> and others
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
     4
#
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
     5
# This software may be used and distributed according to the terms of the
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
     6
# GNU General Public License version 2 or any later version.
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
     7
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
     8
from __future__ import absolute_import
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
     9
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
    10
from . import (
33132
c467d13334ee configitems: add an official API for extensions to register config item
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 32339
diff changeset
    11
    configitems,
30608
b52e8a4f4c0f registrar: raise a programming error on duplicated registering
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 30332
diff changeset
    12
    error,
30059
6ffb7e0249f4 registrar: make format strings unicodes and not bytes
Augie Fackler <augie@google.com>
parents: 29933
diff changeset
    13
    pycompat,
27583
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
    14
    util,
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
    15
)
37d50250b696 registrar: add funcregistrar class to register function for specific purpose
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
diff changeset
    16
33132
c467d13334ee configitems: add an official API for extensions to register config item
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 32339
diff changeset
    17
# unlike the other registered items, config options are neither functions or
c467d13334ee configitems: add an official API for extensions to register config item
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 32339
diff changeset
    18
# classes. Registering the option is just small function call.
c467d13334ee configitems: add an official API for extensions to register config item
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 32339
diff changeset
    19
#
c467d13334ee configitems: add an official API for extensions to register config item
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 32339
diff changeset
    20
# We still add the official API to the registrar module for consistency with
c467d13334ee configitems: add an official API for extensions to register config item
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 32339
diff changeset
    21
# the other items extensions want might to register.
c467d13334ee configitems: add an official API for extensions to register config item
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 32339
diff changeset
    22
configitem = configitems.getitemregister
c467d13334ee configitems: add an official API for extensions to register config item
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 32339
diff changeset
    23
28392
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    24
class _funcregistrarbase(object):
30332
318a24b52eeb spelling: fixes of non-dictionary words
Mads Kiilerich <madski@unity3d.com>
parents: 30059
diff changeset
    25
    """Base of decorator to register a function for specific purpose
28392
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    26
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    27
    This decorator stores decorated functions into own dict 'table'.
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    28
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    29
    The least derived class can be defined by overriding 'formatdoc',
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    30
    for example::
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    31
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    32
        class keyword(_funcregistrarbase):
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    33
            _docformat = ":%s: %s"
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    34
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    35
    This should be used as below:
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    36
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    37
        keyword = registrar.keyword()
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    38
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    39
        @keyword('bar')
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    40
        def barfunc(*args, **kwargs):
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    41
            '''Explanation of bar keyword ....
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    42
            '''
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    43
            pass
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    44
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    45
    In this case:
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    46
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    47
    - 'barfunc' is stored as 'bar' in '_table' of an instance 'keyword' above
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    48
    - 'barfunc.__doc__' becomes ":bar: Explanation of bar keyword"
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    49
    """
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    50
    def __init__(self, table=None):
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    51
        if table is None:
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    52
            self._table = {}
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    53
        else:
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    54
            self._table = table
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    55
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    56
    def __call__(self, decl, *args, **kwargs):
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    57
        return lambda func: self._doregister(func, decl, *args, **kwargs)
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    58
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    59
    def _doregister(self, func, decl, *args, **kwargs):
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    60
        name = self._getname(decl)
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    61
30608
b52e8a4f4c0f registrar: raise a programming error on duplicated registering
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 30332
diff changeset
    62
        if name in self._table:
b52e8a4f4c0f registrar: raise a programming error on duplicated registering
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 30332
diff changeset
    63
            msg = 'duplicate registration for name: "%s"' % name
b52e8a4f4c0f registrar: raise a programming error on duplicated registering
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 30332
diff changeset
    64
            raise error.ProgrammingError(msg)
b52e8a4f4c0f registrar: raise a programming error on duplicated registering
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 30332
diff changeset
    65
28392
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    66
        if func.__doc__ and not util.safehasattr(func, '_origdoc'):
31820
45761ef1bc93 py3: have registrar process docstrings in bytes
Yuya Nishihara <yuya@tcha.org>
parents: 30608
diff changeset
    67
            doc = pycompat.sysbytes(func.__doc__).strip()
28392
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    68
            func._origdoc = doc
31820
45761ef1bc93 py3: have registrar process docstrings in bytes
Yuya Nishihara <yuya@tcha.org>
parents: 30608
diff changeset
    69
            func.__doc__ = pycompat.sysstr(self._formatdoc(decl, doc))
28392
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    70
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    71
        self._table[name] = func
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    72
        self._extrasetup(name, func, *args, **kwargs)
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    73
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    74
        return func
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    75
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    76
    def _parsefuncdecl(self, decl):
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    77
        """Parse function declaration and return the name of function in it
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    78
        """
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    79
        i = decl.find('(')
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    80
        if i >= 0:
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    81
            return decl[:i]
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    82
        else:
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    83
            return decl
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    84
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    85
    def _getname(self, decl):
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    86
        """Return the name of the registered function from decl
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    87
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    88
        Derived class should override this, if it allows more
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    89
        descriptive 'decl' string than just a name.
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    90
        """
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    91
        return decl
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    92
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    93
    _docformat = None
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    94
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    95
    def _formatdoc(self, decl, doc):
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    96
        """Return formatted document of the registered function for help
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    97
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    98
        'doc' is '__doc__.strip()' of the registered function.
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
    99
        """
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
   100
        return self._docformat % (decl, doc)
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
   101
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
   102
    def _extrasetup(self, name, func):
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
   103
        """Execute exra setup for registered function, if needed
b983a2f04987 registrar: introduce new class for registration to replace funcregistrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 27585
diff changeset
   104
        """
28393
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   105
32338
ec84db232fc2 registrar: switch @command decorator to class
Yuya Nishihara <yuya@tcha.org>
parents: 32337
diff changeset
   106
class command(_funcregistrarbase):
ec84db232fc2 registrar: switch @command decorator to class
Yuya Nishihara <yuya@tcha.org>
parents: 32337
diff changeset
   107
    """Decorator to register a command function to table
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   108
32338
ec84db232fc2 registrar: switch @command decorator to class
Yuya Nishihara <yuya@tcha.org>
parents: 32337
diff changeset
   109
    This class receives a command table as its argument. The table should
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   110
    be a dict.
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   111
32338
ec84db232fc2 registrar: switch @command decorator to class
Yuya Nishihara <yuya@tcha.org>
parents: 32337
diff changeset
   112
    The created object can be used as a decorator for adding commands to
ec84db232fc2 registrar: switch @command decorator to class
Yuya Nishihara <yuya@tcha.org>
parents: 32337
diff changeset
   113
    that command table. This accepts multiple arguments to define a command.
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   114
35107
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   115
    The first argument is the command name (as bytes).
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   116
35107
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   117
    The `options` keyword argument is an iterable of tuples defining command
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   118
    arguments. See ``mercurial.fancyopts.fancyopts()`` for the format of each
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   119
    tuple.
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   120
35107
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   121
    The `synopsis` argument defines a short, one line summary of how to use the
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   122
    command. This shows up in the help output.
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   123
35107
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   124
    There are three arguments that control what repository (if any) is found
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   125
    and passed to the decorated function: `norepo`, `optionalrepo`, and
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   126
    `inferrepo`.
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   127
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   128
    The `norepo` argument defines whether the command does not require a
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   129
    local repository. Most commands operate against a repository, thus the
35107
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   130
    default is False. When True, no repository will be passed.
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   131
35107
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   132
    The `optionalrepo` argument defines whether the command optionally requires
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   133
    a local repository. If no repository can be found, None will be passed
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   134
    to the decorated function.
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   135
35107
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   136
    The `inferrepo` argument defines whether to try to find a repository from
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   137
    the command line arguments. If True, arguments will be examined for
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   138
    potential repository locations. See ``findrepo()``. If a repository is
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   139
    found, it will be used and passed to the decorated function.
34781
fe987d0b9e1e registrar: add support for storing the type of command in func object
Pulkit Goyal <7895pulkit@gmail.com>
parents: 34436
diff changeset
   140
37716
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   141
    The `intents` argument defines a set of intended actions or capabilities
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   142
    the command is taking. These intents can be used to affect the construction
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   143
    of the repository object passed to the command. For example, commands
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   144
    declaring that they are read-only could receive a repository that doesn't
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   145
    have any methods allowing repository mutation. Other intents could be used
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   146
    to prevent the command from running if the requested intent could not be
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   147
    fulfilled.
34781
fe987d0b9e1e registrar: add support for storing the type of command in func object
Pulkit Goyal <7895pulkit@gmail.com>
parents: 34436
diff changeset
   148
37716
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   149
    The following intents are defined:
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   150
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   151
    readonly
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   152
       The command is read-only
35107
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   153
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   154
    The signature of the decorated function looks like this:
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   155
        def cmd(ui[, repo] [, <args>] [, <options>])
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   156
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   157
      `repo` is required if `norepo` is False.
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   158
      `<args>` are positional args (or `*args`) arguments, of non-option
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   159
      arguments from the command line.
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   160
      `<options>` are keyword arguments (or `**options`) of option arguments
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   161
      from the command line.
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   162
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   163
    See the WritingExtensions and MercurialApi documentation for more exhaustive
b22a0d9e0a83 docs: add args/returns docs for some cmdutil, context, and registrar functions
rlevasseur@google.com
parents: 34896
diff changeset
   164
    descriptions and examples.
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   165
    """
32338
ec84db232fc2 registrar: switch @command decorator to class
Yuya Nishihara <yuya@tcha.org>
parents: 32337
diff changeset
   166
ec84db232fc2 registrar: switch @command decorator to class
Yuya Nishihara <yuya@tcha.org>
parents: 32337
diff changeset
   167
    def _doregister(self, func, name, options=(), synopsis=None,
34781
fe987d0b9e1e registrar: add support for storing the type of command in func object
Pulkit Goyal <7895pulkit@gmail.com>
parents: 34436
diff changeset
   168
                    norepo=False, optionalrepo=False, inferrepo=False,
37716
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   169
                    intents=None):
34781
fe987d0b9e1e registrar: add support for storing the type of command in func object
Pulkit Goyal <7895pulkit@gmail.com>
parents: 34436
diff changeset
   170
32339
92de09a05d7f registrar: unindent superfluous "if True" block
Yuya Nishihara <yuya@tcha.org>
parents: 32338
diff changeset
   171
        func.norepo = norepo
92de09a05d7f registrar: unindent superfluous "if True" block
Yuya Nishihara <yuya@tcha.org>
parents: 32338
diff changeset
   172
        func.optionalrepo = optionalrepo
92de09a05d7f registrar: unindent superfluous "if True" block
Yuya Nishihara <yuya@tcha.org>
parents: 32338
diff changeset
   173
        func.inferrepo = inferrepo
37716
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   174
        func.intents = intents or set()
32339
92de09a05d7f registrar: unindent superfluous "if True" block
Yuya Nishihara <yuya@tcha.org>
parents: 32338
diff changeset
   175
        if synopsis:
92de09a05d7f registrar: unindent superfluous "if True" block
Yuya Nishihara <yuya@tcha.org>
parents: 32338
diff changeset
   176
            self._table[name] = func, list(options), synopsis
92de09a05d7f registrar: unindent superfluous "if True" block
Yuya Nishihara <yuya@tcha.org>
parents: 32338
diff changeset
   177
        else:
92de09a05d7f registrar: unindent superfluous "if True" block
Yuya Nishihara <yuya@tcha.org>
parents: 32338
diff changeset
   178
            self._table[name] = func, list(options)
92de09a05d7f registrar: unindent superfluous "if True" block
Yuya Nishihara <yuya@tcha.org>
parents: 32338
diff changeset
   179
        return func
32337
46ba2cdda476 registrar: move cmdutil.command to registrar module (API)
Yuya Nishihara <yuya@tcha.org>
parents: 31886
diff changeset
   180
37716
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   181
INTENT_READONLY = b'readonly'
dfc51a482031 registrar: replace "cmdtype" with an intent-based mechanism (API)
Gregory Szorc <gregory.szorc@gmail.com>
parents: 37227
diff changeset
   182
28393
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   183
class revsetpredicate(_funcregistrarbase):
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   184
    """Decorator to register revset predicate
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   185
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   186
    Usage::
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   187
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   188
        revsetpredicate = registrar.revsetpredicate()
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   189
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   190
        @revsetpredicate('mypredicate(arg1, arg2[, arg3])')
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   191
        def mypredicatefunc(repo, subset, x):
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   192
            '''Explanation of this revset predicate ....
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   193
            '''
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   194
            pass
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   195
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   196
    The first string argument is used also in online help.
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   197
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   198
    Optional argument 'safe' indicates whether a predicate is safe for
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   199
    DoS attack (False by default).
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   200
29933
91a95ad985d8 revset: add 'takeorder' attribute to mark functions that need ordering flag
Yuya Nishihara <yuya@tcha.org>
parents: 28695
diff changeset
   201
    Optional argument 'takeorder' indicates whether a predicate function
91a95ad985d8 revset: add 'takeorder' attribute to mark functions that need ordering flag
Yuya Nishihara <yuya@tcha.org>
parents: 28695
diff changeset
   202
    takes ordering policy as the last argument.
91a95ad985d8 revset: add 'takeorder' attribute to mark functions that need ordering flag
Yuya Nishihara <yuya@tcha.org>
parents: 28695
diff changeset
   203
34273
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   204
    Optional argument 'weight' indicates the estimated run-time cost, useful
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   205
    for static optimization, default is 1. Higher weight means more expensive.
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   206
    Usually, revsets that are fast and return only one revision has a weight of
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   207
    0.5 (ex. a symbol); revsets with O(changelog) complexity and read only the
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   208
    changelog have weight 10 (ex. author); revsets reading manifest deltas have
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   209
    weight 30 (ex. adds); revset reading manifest contents have weight 100
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   210
    (ex. contains). Note: those values are flexible. If the revset has a
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   211
    same big-O time complexity as 'contains', but with a smaller constant, it
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   212
    might have a weight of 90.
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   213
28393
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   214
    'revsetpredicate' instance in example above can be used to
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   215
    decorate multiple functions.
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   216
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   217
    Decorated functions are registered automatically at loading
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   218
    extension, if an instance named as 'revsetpredicate' is used for
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   219
    decorating in extension.
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   220
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   221
    Otherwise, explicit 'revset.loadpredicate()' is needed.
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   222
    """
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   223
    _getname = _funcregistrarbase._parsefuncdecl
31820
45761ef1bc93 py3: have registrar process docstrings in bytes
Yuya Nishihara <yuya@tcha.org>
parents: 30608
diff changeset
   224
    _docformat = "``%s``\n    %s"
28393
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   225
34273
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   226
    def _extrasetup(self, name, func, safe=False, takeorder=False, weight=1):
28393
ac11ba7c2e56 registrar: define revsetpredicate to decorate revset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28392
diff changeset
   227
        func._safe = safe
29933
91a95ad985d8 revset: add 'takeorder' attribute to mark functions that need ordering flag
Yuya Nishihara <yuya@tcha.org>
parents: 28695
diff changeset
   228
        func._takeorder = takeorder
34273
b0790bebfcf8 revset: move weight information to predicate
Jun Wu <quark@fb.com>
parents: 33699
diff changeset
   229
        func._weight = weight
28447
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   230
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   231
class filesetpredicate(_funcregistrarbase):
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   232
    """Decorator to register fileset predicate
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   233
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   234
    Usage::
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   235
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   236
        filesetpredicate = registrar.filesetpredicate()
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   237
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   238
        @filesetpredicate('mypredicate()')
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   239
        def mypredicatefunc(mctx, x):
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   240
            '''Explanation of this fileset predicate ....
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   241
            '''
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   242
            pass
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   243
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   244
    The first string argument is used also in online help.
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   245
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   246
    Optional argument 'callstatus' indicates whether a predicate
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   247
     implies 'matchctx.status()' at runtime or not (False, by
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   248
     default).
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   249
38829
7e7e2b2ff284 fileset: add stub for weight-based optimization
Yuya Nishihara <yuya@tcha.org>
parents: 38690
diff changeset
   250
    Optional argument 'weight' indicates the estimated run-time cost, useful
7e7e2b2ff284 fileset: add stub for weight-based optimization
Yuya Nishihara <yuya@tcha.org>
parents: 38690
diff changeset
   251
    for static optimization, default is 1. Higher weight means more expensive.
38863
61ab546b71c3 fileset: introduce weight constants for readability
Yuya Nishihara <yuya@tcha.org>
parents: 38830
diff changeset
   252
    There are predefined weights in the 'filesetlang' module.
38829
7e7e2b2ff284 fileset: add stub for weight-based optimization
Yuya Nishihara <yuya@tcha.org>
parents: 38690
diff changeset
   253
38830
bfd5def3fe02 fileset: roughly adjust weights of functions
Yuya Nishihara <yuya@tcha.org>
parents: 38829
diff changeset
   254
    ====== =============================================================
bfd5def3fe02 fileset: roughly adjust weights of functions
Yuya Nishihara <yuya@tcha.org>
parents: 38829
diff changeset
   255
    Weight Description and examples
bfd5def3fe02 fileset: roughly adjust weights of functions
Yuya Nishihara <yuya@tcha.org>
parents: 38829
diff changeset
   256
    ====== =============================================================
bfd5def3fe02 fileset: roughly adjust weights of functions
Yuya Nishihara <yuya@tcha.org>
parents: 38829
diff changeset
   257
    0.5    basic match patterns (e.g. a symbol)
bfd5def3fe02 fileset: roughly adjust weights of functions
Yuya Nishihara <yuya@tcha.org>
parents: 38829
diff changeset
   258
    10     computing status (e.g. added()) or accessing a few files
bfd5def3fe02 fileset: roughly adjust weights of functions
Yuya Nishihara <yuya@tcha.org>
parents: 38829
diff changeset
   259
    30     reading file content for each (e.g. grep())
bfd5def3fe02 fileset: roughly adjust weights of functions
Yuya Nishihara <yuya@tcha.org>
parents: 38829
diff changeset
   260
    50     scanning working directory (ignored())
bfd5def3fe02 fileset: roughly adjust weights of functions
Yuya Nishihara <yuya@tcha.org>
parents: 38829
diff changeset
   261
    ====== =============================================================
bfd5def3fe02 fileset: roughly adjust weights of functions
Yuya Nishihara <yuya@tcha.org>
parents: 38829
diff changeset
   262
28447
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   263
    'filesetpredicate' instance in example above can be used to
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   264
    decorate multiple functions.
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   265
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   266
    Decorated functions are registered automatically at loading
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   267
    extension, if an instance named as 'filesetpredicate' is used for
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   268
    decorating in extension.
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   269
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   270
    Otherwise, explicit 'fileset.loadpredicate()' is needed.
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   271
    """
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   272
    _getname = _funcregistrarbase._parsefuncdecl
31820
45761ef1bc93 py3: have registrar process docstrings in bytes
Yuya Nishihara <yuya@tcha.org>
parents: 30608
diff changeset
   273
    _docformat = "``%s``\n    %s"
28447
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   274
38829
7e7e2b2ff284 fileset: add stub for weight-based optimization
Yuya Nishihara <yuya@tcha.org>
parents: 38690
diff changeset
   275
    def _extrasetup(self, name, func, callstatus=False, weight=1):
28447
4eb5496c2bd4 registrar: add filesetpredicate to mark a function as fileset predicate
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28446
diff changeset
   276
        func._callstatus = callstatus
38829
7e7e2b2ff284 fileset: add stub for weight-based optimization
Yuya Nishihara <yuya@tcha.org>
parents: 38690
diff changeset
   277
        func._weight = weight
28538
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   278
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   279
class _templateregistrarbase(_funcregistrarbase):
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   280
    """Base of decorator to register functions as template specific one
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   281
    """
31820
45761ef1bc93 py3: have registrar process docstrings in bytes
Yuya Nishihara <yuya@tcha.org>
parents: 30608
diff changeset
   282
    _docformat = ":%s: %s"
28538
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   283
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   284
class templatekeyword(_templateregistrarbase):
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   285
    """Decorator to register template keyword
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   286
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   287
    Usage::
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   288
30332
318a24b52eeb spelling: fixes of non-dictionary words
Mads Kiilerich <madski@unity3d.com>
parents: 30059
diff changeset
   289
        templatekeyword = registrar.templatekeyword()
28538
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   290
36445
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   291
        # new API (since Mercurial 4.6)
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   292
        @templatekeyword('mykeyword', requires={'repo', 'ctx'})
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   293
        def mykeywordfunc(context, mapping):
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   294
            '''Explanation of this template keyword ....
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   295
            '''
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   296
            pass
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   297
38930
382b055cc358 templatekw: deprecate old-style template keyword function (API)
Yuya Nishihara <yuya@tcha.org>
parents: 38863
diff changeset
   298
        # old API (DEPRECATED)
28538
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   299
        @templatekeyword('mykeyword')
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   300
        def mykeywordfunc(repo, ctx, templ, cache, revcache, **args):
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   301
            '''Explanation of this template keyword ....
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   302
            '''
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   303
            pass
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   304
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   305
    The first string argument is used also in online help.
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   306
36445
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   307
    Optional argument 'requires' should be a collection of resource names
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   308
    which the template keyword depends on. This also serves as a flag to
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   309
    switch to the new API. If 'requires' is unspecified, all template
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   310
    keywords and resources are expanded to the function arguments.
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   311
28538
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   312
    'templatekeyword' instance in example above can be used to
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   313
    decorate multiple functions.
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   314
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   315
    Decorated functions are registered automatically at loading
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   316
    extension, if an instance named as 'templatekeyword' is used for
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   317
    decorating in extension.
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   318
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   319
    Otherwise, explicit 'templatekw.loadkeyword()' is needed.
009f58f1ea75 registrar: add templatekeyword to mark a function as template keyword (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28447
diff changeset
   320
    """
28692
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   321
36445
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   322
    def _extrasetup(self, name, func, requires=None):
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   323
        func._requires = requires
e8d37838f5df templatekw: add 'requires' flag to switch to exception-safe interface
Yuya Nishihara <yuya@tcha.org>
parents: 35107
diff changeset
   324
28692
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   325
class templatefilter(_templateregistrarbase):
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   326
    """Decorator to register template filer
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   327
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   328
    Usage::
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   329
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   330
        templatefilter = registrar.templatefilter()
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   331
37222
54355c243042 templatefilters: allow declaration of input data type
Yuya Nishihara <yuya@tcha.org>
parents: 36922
diff changeset
   332
        @templatefilter('myfilter', intype=bytes)
28692
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   333
        def myfilterfunc(text):
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   334
            '''Explanation of this template filter ....
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   335
            '''
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   336
            pass
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   337
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   338
    The first string argument is used also in online help.
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   339
37222
54355c243042 templatefilters: allow declaration of input data type
Yuya Nishihara <yuya@tcha.org>
parents: 36922
diff changeset
   340
    Optional argument 'intype' defines the type of the input argument,
37227
9bcf096a2da2 templatefilters: declare input type as date where appropriate
Yuya Nishihara <yuya@tcha.org>
parents: 37222
diff changeset
   341
    which should be (bytes, int, templateutil.date, or None for any.)
37222
54355c243042 templatefilters: allow declaration of input data type
Yuya Nishihara <yuya@tcha.org>
parents: 36922
diff changeset
   342
28692
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   343
    'templatefilter' instance in example above can be used to
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   344
    decorate multiple functions.
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   345
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   346
    Decorated functions are registered automatically at loading
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   347
    extension, if an instance named as 'templatefilter' is used for
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   348
    decorating in extension.
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   349
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   350
    Otherwise, explicit 'templatefilters.loadkeyword()' is needed.
6b3b958daf03 registrar: add templatefilter to mark a function as template filter (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28538
diff changeset
   351
    """
28695
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   352
37222
54355c243042 templatefilters: allow declaration of input data type
Yuya Nishihara <yuya@tcha.org>
parents: 36922
diff changeset
   353
    def _extrasetup(self, name, func, intype=None):
54355c243042 templatefilters: allow declaration of input data type
Yuya Nishihara <yuya@tcha.org>
parents: 36922
diff changeset
   354
        func._intype = intype
54355c243042 templatefilters: allow declaration of input data type
Yuya Nishihara <yuya@tcha.org>
parents: 36922
diff changeset
   355
28695
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   356
class templatefunc(_templateregistrarbase):
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   357
    """Decorator to register template function
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   358
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   359
    Usage::
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   360
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   361
        templatefunc = registrar.templatefunc()
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   362
38428
aa98392eb5b0 templatefuncs: declare resource requirements for future use
Yuya Nishihara <yuya@tcha.org>
parents: 37716
diff changeset
   363
        @templatefunc('myfunc(arg1, arg2[, arg3])', argspec='arg1 arg2 arg3',
aa98392eb5b0 templatefuncs: declare resource requirements for future use
Yuya Nishihara <yuya@tcha.org>
parents: 37716
diff changeset
   364
                      requires={'ctx'})
28695
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   365
        def myfuncfunc(context, mapping, args):
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   366
            '''Explanation of this template function ....
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   367
            '''
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   368
            pass
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   369
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   370
    The first string argument is used also in online help.
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   371
31886
bdda942f4b9c templater: add support for keyword arguments
Yuya Nishihara <yuya@tcha.org>
parents: 31820
diff changeset
   372
    If optional 'argspec' is defined, the function will receive 'args' as
bdda942f4b9c templater: add support for keyword arguments
Yuya Nishihara <yuya@tcha.org>
parents: 31820
diff changeset
   373
    a dict of named arguments. Otherwise 'args' is a list of positional
bdda942f4b9c templater: add support for keyword arguments
Yuya Nishihara <yuya@tcha.org>
parents: 31820
diff changeset
   374
    arguments.
bdda942f4b9c templater: add support for keyword arguments
Yuya Nishihara <yuya@tcha.org>
parents: 31820
diff changeset
   375
38428
aa98392eb5b0 templatefuncs: declare resource requirements for future use
Yuya Nishihara <yuya@tcha.org>
parents: 37716
diff changeset
   376
    Optional argument 'requires' should be a collection of resource names
aa98392eb5b0 templatefuncs: declare resource requirements for future use
Yuya Nishihara <yuya@tcha.org>
parents: 37716
diff changeset
   377
    which the template function depends on.
aa98392eb5b0 templatefuncs: declare resource requirements for future use
Yuya Nishihara <yuya@tcha.org>
parents: 37716
diff changeset
   378
28695
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   379
    'templatefunc' instance in example above can be used to
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   380
    decorate multiple functions.
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   381
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   382
    Decorated functions are registered automatically at loading
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   383
    extension, if an instance named as 'templatefunc' is used for
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   384
    decorating in extension.
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   385
36922
521f6c7e1756 templater: split template functions to new module
Yuya Nishihara <yuya@tcha.org>
parents: 36445
diff changeset
   386
    Otherwise, explicit 'templatefuncs.loadfunction()' is needed.
28695
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   387
    """
cc103bd0dbf9 registrar: add templatefunc to mark a function as template function (API)
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 28692
diff changeset
   388
    _getname = _funcregistrarbase._parsefuncdecl
31886
bdda942f4b9c templater: add support for keyword arguments
Yuya Nishihara <yuya@tcha.org>
parents: 31820
diff changeset
   389
38428
aa98392eb5b0 templatefuncs: declare resource requirements for future use
Yuya Nishihara <yuya@tcha.org>
parents: 37716
diff changeset
   390
    def _extrasetup(self, name, func, argspec=None, requires=()):
31886
bdda942f4b9c templater: add support for keyword arguments
Yuya Nishihara <yuya@tcha.org>
parents: 31820
diff changeset
   391
        func._argspec = argspec
38428
aa98392eb5b0 templatefuncs: declare resource requirements for future use
Yuya Nishihara <yuya@tcha.org>
parents: 37716
diff changeset
   392
        func._requires = requires
33699
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   393
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   394
class internalmerge(_funcregistrarbase):
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   395
    """Decorator to register in-process merge tool
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   396
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   397
    Usage::
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   398
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   399
        internalmerge = registrar.internalmerge()
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   400
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   401
        @internalmerge('mymerge', internalmerge.mergeonly,
39122
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   402
                       onfailure=None, precheck=None,
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   403
                       binary=False, symlink=False):
33699
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   404
        def mymergefunc(repo, mynode, orig, fcd, fco, fca,
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   405
                        toolconf, files, labels=None):
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   406
            '''Explanation of this internal merge tool ....
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   407
            '''
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   408
            return 1, False # means "conflicted", "no deletion needed"
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   409
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   410
    The first string argument is used to compose actual merge tool name,
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   411
    ":name" and "internal:name" (the latter is historical one).
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   412
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   413
    The second argument is one of merge types below:
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   414
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   415
    ========== ======== ======== =========
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   416
    merge type precheck premerge fullmerge
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   417
    ========== ======== ======== =========
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   418
    nomerge     x        x        x
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   419
    mergeonly   o        x        o
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   420
    fullmerge   o        o        o
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   421
    ========== ======== ======== =========
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   422
34436
c1fe66e89f57 registrar: fixing typo in comment
Saurabh Singh <singhsrb@fb.com>
parents: 34381
diff changeset
   423
    Optional argument 'onfailure' is the format of warning message
33699
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   424
    to be used at failure of merging (target filename is specified
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   425
    at formatting). Or, None or so, if warning message should be
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   426
    suppressed.
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   427
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   428
    Optional argument 'precheck' is the function to be used
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   429
    before actual invocation of internal merge tool itself.
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   430
    It takes as same arguments as internal merge tool does, other than
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   431
    'files' and 'labels'. If it returns false value, merging is aborted
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   432
    immediately (and file is marked as "unresolved").
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   433
39122
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   434
    Optional argument 'binary' is a binary files capability of internal
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   435
    merge tool. 'nomerge' merge type implies binary=True.
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   436
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   437
    Optional argument 'symlink' is a symlinks capability of inetrnal
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   438
    merge function. 'nomerge' merge type implies symlink=True.
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   439
33699
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   440
    'internalmerge' instance in example above can be used to
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   441
    decorate multiple functions.
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   442
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   443
    Decorated functions are registered automatically at loading
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   444
    extension, if an instance named as 'internalmerge' is used for
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   445
    decorating in extension.
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   446
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   447
    Otherwise, explicit 'filemerge.loadinternalmerge()' is needed.
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   448
    """
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   449
    _docformat = "``:%s``\n    %s"
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   450
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   451
    # merge type definitions:
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   452
    nomerge = None
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   453
    mergeonly = 'mergeonly'  # just the full merge, no premerge
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   454
    fullmerge = 'fullmerge'  # both premerge and merge
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   455
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   456
    def _extrasetup(self, name, func, mergetype,
39122
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   457
                    onfailure=None, precheck=None,
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   458
                    binary=False, symlink=False):
33699
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   459
        func.mergetype = mergetype
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   460
        func.onfailure = onfailure
50c44dee741a filemerge: move decorator definition for internal merge tools to registrar
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 33132
diff changeset
   461
        func.precheck = precheck
39122
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   462
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   463
        binarycap = binary or mergetype == self.nomerge
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   464
        symlinkcap = symlink or mergetype == self.nomerge
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   465
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   466
        # actual capabilities, which this internal merge tool has
5d3b58472660 filemerge: set actual capabilities of internal merge tools
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 38930
diff changeset
   467
        func.capabilities = {"binary": binarycap, "symlink": symlinkcap}