registrar.py
371 lines
| 11.8 KiB
| text/x-python
|
PythonLexer
/ mercurial / registrar.py
|
r27583 | # registrar.py - utilities to register function for specific purpose | ||
# | ||||
# Copyright FUJIWARA Katsunori <foozy@lares.dti.ne.jp> and others | ||||
# | ||||
# This software may be used and distributed according to the terms of the | ||||
# GNU General Public License version 2 or any later version. | ||||
from __future__ import absolute_import | ||||
from . import ( | ||||
r33127 | configitems, | |||
|
r30608 | error, | ||
|
r30059 | pycompat, | ||
|
r27583 | util, | ||
) | ||||
r33127 | # unlike the other registered items, config options are neither functions or | |||
# classes. Registering the option is just small function call. | ||||
# | ||||
# We still add the official API to the registrar module for consistency with | ||||
# the other items extensions want might to register. | ||||
configitem = configitems.getitemregister | ||||
|
r28392 | class _funcregistrarbase(object): | ||
|
r30332 | """Base of decorator to register a function for specific purpose | ||
|
r28392 | |||
This decorator stores decorated functions into own dict 'table'. | ||||
The least derived class can be defined by overriding 'formatdoc', | ||||
for example:: | ||||
class keyword(_funcregistrarbase): | ||||
_docformat = ":%s: %s" | ||||
This should be used as below: | ||||
keyword = registrar.keyword() | ||||
@keyword('bar') | ||||
def barfunc(*args, **kwargs): | ||||
'''Explanation of bar keyword .... | ||||
''' | ||||
pass | ||||
In this case: | ||||
- 'barfunc' is stored as 'bar' in '_table' of an instance 'keyword' above | ||||
- 'barfunc.__doc__' becomes ":bar: Explanation of bar keyword" | ||||
""" | ||||
def __init__(self, table=None): | ||||
if table is None: | ||||
self._table = {} | ||||
else: | ||||
self._table = table | ||||
def __call__(self, decl, *args, **kwargs): | ||||
return lambda func: self._doregister(func, decl, *args, **kwargs) | ||||
def _doregister(self, func, decl, *args, **kwargs): | ||||
name = self._getname(decl) | ||||
|
r30608 | if name in self._table: | ||
msg = 'duplicate registration for name: "%s"' % name | ||||
raise error.ProgrammingError(msg) | ||||
|
r28392 | if func.__doc__ and not util.safehasattr(func, '_origdoc'): | ||
|
r31820 | doc = pycompat.sysbytes(func.__doc__).strip() | ||
|
r28392 | func._origdoc = doc | ||
|
r31820 | func.__doc__ = pycompat.sysstr(self._formatdoc(decl, doc)) | ||
|
r28392 | |||
self._table[name] = func | ||||
self._extrasetup(name, func, *args, **kwargs) | ||||
return func | ||||
def _parsefuncdecl(self, decl): | ||||
"""Parse function declaration and return the name of function in it | ||||
""" | ||||
i = decl.find('(') | ||||
if i >= 0: | ||||
return decl[:i] | ||||
else: | ||||
return decl | ||||
def _getname(self, decl): | ||||
"""Return the name of the registered function from decl | ||||
Derived class should override this, if it allows more | ||||
descriptive 'decl' string than just a name. | ||||
""" | ||||
return decl | ||||
_docformat = None | ||||
def _formatdoc(self, decl, doc): | ||||
"""Return formatted document of the registered function for help | ||||
'doc' is '__doc__.strip()' of the registered function. | ||||
""" | ||||
return self._docformat % (decl, doc) | ||||
def _extrasetup(self, name, func): | ||||
"""Execute exra setup for registered function, if needed | ||||
""" | ||||
pass | ||||
|
r28393 | |||
|
r32338 | class command(_funcregistrarbase): | ||
"""Decorator to register a command function to table | ||||
|
r32337 | |||
|
r32338 | This class receives a command table as its argument. The table should | ||
|
r32337 | be a dict. | ||
|
r32338 | The created object can be used as a decorator for adding commands to | ||
that command table. This accepts multiple arguments to define a command. | ||||
|
r32337 | |||
The first argument is the command name. | ||||
The options argument is an iterable of tuples defining command arguments. | ||||
See ``mercurial.fancyopts.fancyopts()`` for the format of each tuple. | ||||
The synopsis argument defines a short, one line summary of how to use the | ||||
command. This shows up in the help output. | ||||
The norepo argument defines whether the command does not require a | ||||
local repository. Most commands operate against a repository, thus the | ||||
default is False. | ||||
The optionalrepo argument defines whether the command optionally requires | ||||
a local repository. | ||||
The inferrepo argument defines whether to try to find a repository from the | ||||
command line arguments. If True, arguments will be examined for potential | ||||
repository locations. See ``findrepo()``. If a repository is found, it | ||||
will be used. | ||||
""" | ||||
|
r32338 | |||
def _doregister(self, func, name, options=(), synopsis=None, | ||||
norepo=False, optionalrepo=False, inferrepo=False): | ||||
|
r32339 | func.norepo = norepo | ||
func.optionalrepo = optionalrepo | ||||
func.inferrepo = inferrepo | ||||
if synopsis: | ||||
self._table[name] = func, list(options), synopsis | ||||
else: | ||||
self._table[name] = func, list(options) | ||||
return func | ||||
|
r32337 | |||
|
r28393 | class revsetpredicate(_funcregistrarbase): | ||
"""Decorator to register revset predicate | ||||
Usage:: | ||||
revsetpredicate = registrar.revsetpredicate() | ||||
@revsetpredicate('mypredicate(arg1, arg2[, arg3])') | ||||
def mypredicatefunc(repo, subset, x): | ||||
'''Explanation of this revset predicate .... | ||||
''' | ||||
pass | ||||
The first string argument is used also in online help. | ||||
Optional argument 'safe' indicates whether a predicate is safe for | ||||
DoS attack (False by default). | ||||
|
r29933 | Optional argument 'takeorder' indicates whether a predicate function | ||
takes ordering policy as the last argument. | ||||
|
r28393 | 'revsetpredicate' instance in example above can be used to | ||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'revsetpredicate' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'revset.loadpredicate()' is needed. | ||||
""" | ||||
_getname = _funcregistrarbase._parsefuncdecl | ||||
|
r31820 | _docformat = "``%s``\n %s" | ||
|
r28393 | |||
|
r29933 | def _extrasetup(self, name, func, safe=False, takeorder=False): | ||
|
r28393 | func._safe = safe | ||
|
r29933 | func._takeorder = takeorder | ||
|
r28447 | |||
class filesetpredicate(_funcregistrarbase): | ||||
"""Decorator to register fileset predicate | ||||
Usage:: | ||||
filesetpredicate = registrar.filesetpredicate() | ||||
@filesetpredicate('mypredicate()') | ||||
def mypredicatefunc(mctx, x): | ||||
'''Explanation of this fileset predicate .... | ||||
''' | ||||
pass | ||||
The first string argument is used also in online help. | ||||
Optional argument 'callstatus' indicates whether a predicate | ||||
implies 'matchctx.status()' at runtime or not (False, by | ||||
default). | ||||
Optional argument 'callexisting' indicates whether a predicate | ||||
implies 'matchctx.existing()' at runtime or not (False, by | ||||
default). | ||||
'filesetpredicate' instance in example above can be used to | ||||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'filesetpredicate' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'fileset.loadpredicate()' is needed. | ||||
""" | ||||
_getname = _funcregistrarbase._parsefuncdecl | ||||
|
r31820 | _docformat = "``%s``\n %s" | ||
|
r28447 | |||
def _extrasetup(self, name, func, callstatus=False, callexisting=False): | ||||
func._callstatus = callstatus | ||||
func._callexisting = callexisting | ||||
|
r28538 | |||
class _templateregistrarbase(_funcregistrarbase): | ||||
"""Base of decorator to register functions as template specific one | ||||
""" | ||||
|
r31820 | _docformat = ":%s: %s" | ||
|
r28538 | |||
class templatekeyword(_templateregistrarbase): | ||||
"""Decorator to register template keyword | ||||
Usage:: | ||||
|
r30332 | templatekeyword = registrar.templatekeyword() | ||
|
r28538 | |||
@templatekeyword('mykeyword') | ||||
def mykeywordfunc(repo, ctx, templ, cache, revcache, **args): | ||||
'''Explanation of this template keyword .... | ||||
''' | ||||
pass | ||||
The first string argument is used also in online help. | ||||
'templatekeyword' instance in example above can be used to | ||||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'templatekeyword' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'templatekw.loadkeyword()' is needed. | ||||
""" | ||||
|
r28692 | |||
class templatefilter(_templateregistrarbase): | ||||
"""Decorator to register template filer | ||||
Usage:: | ||||
templatefilter = registrar.templatefilter() | ||||
@templatefilter('myfilter') | ||||
def myfilterfunc(text): | ||||
'''Explanation of this template filter .... | ||||
''' | ||||
pass | ||||
The first string argument is used also in online help. | ||||
'templatefilter' instance in example above can be used to | ||||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'templatefilter' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'templatefilters.loadkeyword()' is needed. | ||||
""" | ||||
|
r28695 | |||
class templatefunc(_templateregistrarbase): | ||||
"""Decorator to register template function | ||||
Usage:: | ||||
templatefunc = registrar.templatefunc() | ||||
|
r31886 | @templatefunc('myfunc(arg1, arg2[, arg3])', argspec='arg1 arg2 arg3') | ||
|
r28695 | def myfuncfunc(context, mapping, args): | ||
'''Explanation of this template function .... | ||||
''' | ||||
pass | ||||
The first string argument is used also in online help. | ||||
|
r31886 | If optional 'argspec' is defined, the function will receive 'args' as | ||
a dict of named arguments. Otherwise 'args' is a list of positional | ||||
arguments. | ||||
|
r28695 | 'templatefunc' instance in example above can be used to | ||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'templatefunc' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'templater.loadfunction()' is needed. | ||||
""" | ||||
_getname = _funcregistrarbase._parsefuncdecl | ||||
|
r31886 | |||
def _extrasetup(self, name, func, argspec=None): | ||||
func._argspec = argspec | ||||
|
r33663 | |||
class internalmerge(_funcregistrarbase): | ||||
"""Decorator to register in-process merge tool | ||||
Usage:: | ||||
internalmerge = registrar.internalmerge() | ||||
@internalmerge('mymerge', internalmerge.mergeonly, | ||||
onfailure=None, precheck=None): | ||||
def mymergefunc(repo, mynode, orig, fcd, fco, fca, | ||||
toolconf, files, labels=None): | ||||
'''Explanation of this internal merge tool .... | ||||
''' | ||||
return 1, False # means "conflicted", "no deletion needed" | ||||
The first string argument is used to compose actual merge tool name, | ||||
":name" and "internal:name" (the latter is historical one). | ||||
The second argument is one of merge types below: | ||||
========== ======== ======== ========= | ||||
merge type precheck premerge fullmerge | ||||
========== ======== ======== ========= | ||||
nomerge x x x | ||||
mergeonly o x o | ||||
fullmerge o o o | ||||
========== ======== ======== ========= | ||||
Optional argument 'onfalure' is the format of warning message | ||||
to be used at failure of merging (target filename is specified | ||||
at formatting). Or, None or so, if warning message should be | ||||
suppressed. | ||||
Optional argument 'precheck' is the function to be used | ||||
before actual invocation of internal merge tool itself. | ||||
It takes as same arguments as internal merge tool does, other than | ||||
'files' and 'labels'. If it returns false value, merging is aborted | ||||
immediately (and file is marked as "unresolved"). | ||||
'internalmerge' instance in example above can be used to | ||||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'internalmerge' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'filemerge.loadinternalmerge()' is needed. | ||||
""" | ||||
_docformat = "``:%s``\n %s" | ||||
# merge type definitions: | ||||
nomerge = None | ||||
mergeonly = 'mergeonly' # just the full merge, no premerge | ||||
fullmerge = 'fullmerge' # both premerge and merge | ||||
def _extrasetup(self, name, func, mergetype, | ||||
onfailure=None, precheck=None): | ||||
func.mergetype = mergetype | ||||
func.onfailure = onfailure | ||||
func.precheck = precheck | ||||