mercurial/registrar.py
author Gregory Szorc <gregory.szorc@gmail.com>
Mon, 24 Sep 2018 11:16:33 -0700
changeset 39873 2ac4f3e97813
parent 39122 5d3b58472660
child 40291 170926caf44c
permissions -rw-r--r--
filelog: stop proxying flags() (API) Per-revision storage flags are kinda a revlog-centric API. (Except for the fact that changegroup uses the same integer flags as revlog does and there's minimal verification that the server's flags map to the client's storage flags - but that's another problem.) The last user of flags() was in verify.py and that code was just moved into revlog.py and is accessed behind the verifyintegrity() file storage API. Since there are no more consumers, let's drop the proxy and remove the method from the file storage interface. This commit only drops the dedicated API for reading a single revision's storage flags: we still support reading and writing flags through the bulk data retrieval and add revision APIs. And since changegroups encode revlog integer flags over the wire, we'll always need to support flags at some level. The removal of individual storage flags may be too premature. But since flags() is now unused, I'd like to see how far we can get without that dedicated API - especially since it uses revision numbers instead of nodes. Differential Revision: https://phab.mercurial-scm.org/D4746
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}