doc: document that labels must have a dot in them to have an effect

I noticed that the `hg topics` template has a bare `topic` label with
no dot, and that makes it useless, as such a label will never receive
any effect by the colour extension.

This dot has been required for a long time, at least since 2011, but
we never formally documented it!

mercurial/helptext/color.txt

@@ -1,149 +1,150 b''
 Mercurial colorizes output from several commands.
 
 For example, the diff command shows additions in green and deletions
 in red, while the status command shows modified files in magenta. Many
 other commands have analogous colors. It is possible to customize
 these colors.
 
 To enable color (default) whenever possible use::
 
   [ui]
   color = yes
 
 To disable color use::
 
   [ui]
   color = no
 
 See :hg:`help config.ui.color` for details.
 
 .. container:: windows
 
   The default pager on Windows does not support color, so enabling the pager
   will effectively disable color.  See :hg:`help config.ui.paginate` to disable
   the pager.  Alternately, MSYS and Cygwin shells provide `less` as a pager,
   which can be configured to support ANSI color mode.  Windows 10 natively
   supports ANSI color mode.
 
 Mode
 ====
 
 Mercurial can use various systems to display color. The supported modes are
 ``ansi``, ``win32``, and ``terminfo``.  See :hg:`help config.color` for details
 about how to control the mode.
 
 Effects
 =======
 
 Other effects in addition to color, like bold and underlined text, are
 also available. By default, the terminfo database is used to find the
 terminal codes used to change color and effect.  If terminfo is not
 available, then effects are rendered with the ECMA-48 SGR control
 function (aka ANSI escape codes).
 
 The available effects in terminfo mode are 'blink', 'bold', 'dim',
 'inverse', 'invisible', 'italic', 'standout', and 'underline'; in
 ECMA-48 mode, the options are 'bold', 'inverse', 'italic', and
 'underline'.  How each is rendered depends on the terminal emulator.
 Some may not be available for a given terminal type, and will be
 silently ignored.
 
 If the terminfo entry for your terminal is missing codes for an effect
 or has the wrong codes, you can add or override those codes in your
 configuration::
 
   [color]
   terminfo.dim = \E[2m
 
 where '\E' is substituted with an escape character.
 
 Labels
 ======
 
 Text receives color effects depending on the labels that it has. Many
 default Mercurial commands emit labelled text. You can also define
 your own labels in templates using the label function, see :hg:`help
-templates`. A single portion of text may have more than one label. In
-that case, effects given to the last label will override any other
-effects. This includes the special "none" effect, which nullifies
-other effects.
+templates`. In order to receive effects, labels must have a dot, such
+as `log.secret` or `branch.active`. A single portion of text may have
+more than one label. In that case, effects given to the last label
+will override any other effects. This includes the special "none"
+effect, which nullifies other effects.
 
 Labels are normally invisible. In order to see these labels and their
 position in the text, use the global --color=debug option. The same
 anchor text may be associated to multiple labels, e.g.
 
   [log.changeset changeset.secret|changeset:   22611:6f0a53c8f587]
 
 The following are the default effects for some default labels. Default
 effects may be overridden from your configuration file::
 
   [color]
   status.modified = blue bold underline red_background
   status.added = green bold
   status.removed = red bold blue_background
   status.deleted = cyan bold underline
   status.unknown = magenta bold underline
   status.ignored = black bold
 
   # 'none' turns off all effects
   status.clean = none
   status.copied = none
 
   qseries.applied = blue bold underline
   qseries.unapplied = black bold
   qseries.missing = red bold
 
   diff.diffline = bold
   diff.extended = cyan bold
   diff.file_a = red bold
   diff.file_b = green bold
   diff.hunk = magenta
   diff.deleted = red
   diff.inserted = green
   diff.changed = white
   diff.tab =
   diff.trailingwhitespace = bold red_background
 
   # Blank so it inherits the style of the surrounding label
   changeset.public =
   changeset.draft =
   changeset.secret =
 
   resolve.unresolved = red bold
   resolve.resolved = green bold
 
   bookmarks.active = green
 
   branches.active = none
   branches.closed = black bold
   branches.current = green
   branches.inactive = none
 
   tags.normal = green
   tags.local = black bold
 
   rebase.rebased = blue
   rebase.remaining = red bold
 
   shelve.age = cyan
   shelve.newest = green bold
   shelve.name = blue bold
 
   histedit.remaining = red bold
 
 Custom colors
 =============
 
 Because there are only eight standard colors, Mercurial allows you
 to define color names for other color slots which might be available
 for your terminal type, assuming terminfo mode.  For instance::
 
   color.brightblue = 12
   color.pink = 207
   color.orange = 202
 
 to set 'brightblue' to color slot 12 (useful for 16 color terminals
 that have brighter colors defined in the upper eight) and, 'pink' and
 'orange' to colors in 256-color xterm's default color cube.  These
 defined colors may then be used as any of the pre-defined eight,
 including appending '_background' to set the background to that color.

mercurial/templatefuncs.py

@@ -1,919 +1,920 b''
 # templatefuncs.py - common template functions
 #
 # Copyright 2005, 2006 Olivia Mackall <[e-mail]>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 
 import binascii
 import re
 
 from .i18n import _
 from .node import bin
 from . import (
     color,
     dagop,
     diffutil,
     encoding,
     error,
     minirst,
     obsutil,
     pycompat,
     registrar,
     revset as revsetmod,
     revsetlang,
     scmutil,
     templatefilters,
     templatekw,
     templateutil,
     util,
 )
 from .utils import (
     dateutil,
     stringutil,
 )
 
 evalrawexp = templateutil.evalrawexp
 evalwrapped = templateutil.evalwrapped
 evalfuncarg = templateutil.evalfuncarg
 evalboolean = templateutil.evalboolean
 evaldate = templateutil.evaldate
 evalinteger = templateutil.evalinteger
 evalstring = templateutil.evalstring
 evalstringliteral = templateutil.evalstringliteral
 
 # dict of template built-in functions
 funcs = {}
 templatefunc = registrar.templatefunc(funcs)
 
 
 @templatefunc(b'date(date[, fmt])')
 def date(context, mapping, args):
     """Format a date. The format string uses the Python strftime format.
     The default is a Unix date format, including the timezone:
     "Mon Sep 04 15:13:13 2006 0700"."""
     if not (1 <= len(args) <= 2):
         # i18n: "date" is a keyword
         raise error.ParseError(_(b"date expects one or two arguments"))
 
     date = evaldate(
         context,
         mapping,
         args[0],
         # i18n: "date" is a keyword
         _(b"date expects a date information"),
     )
     fmt = None
     if len(args) == 2:
         fmt = evalstring(context, mapping, args[1])
     if fmt is None:
         return dateutil.datestr(date)
     else:
         return dateutil.datestr(date, fmt)
 
 
 @templatefunc(b'dict([[key=]value...])', argspec=b'*args **kwargs')
 def dict_(context, mapping, args):
     """Construct a dict from key-value pairs. A key may be omitted if
     a value expression can provide an unambiguous name."""
     data = util.sortdict()
 
     for v in args[b'args']:
         k = templateutil.findsymbolicname(v)
         if not k:
             raise error.ParseError(_(b'dict key cannot be inferred'))
         if k in data or k in args[b'kwargs']:
             raise error.ParseError(_(b"duplicated dict key '%s' inferred") % k)
         data[k] = evalfuncarg(context, mapping, v)
 
     data.update(
         (k, evalfuncarg(context, mapping, v))
         for k, v in args[b'kwargs'].items()
     )
     return templateutil.hybriddict(data)
 
 
 @templatefunc(
     b'diff([includepattern [, excludepattern]])', requires={b'ctx', b'ui'}
 )
 def diff(context, mapping, args):
     """Show a diff, optionally
     specifying files to include or exclude."""
     if len(args) > 2:
         # i18n: "diff" is a keyword
         raise error.ParseError(_(b"diff expects zero, one, or two arguments"))
 
     def getpatterns(i):
         if i < len(args):
             s = evalstring(context, mapping, args[i]).strip()
             if s:
                 return [s]
         return []
 
     ctx = context.resource(mapping, b'ctx')
     ui = context.resource(mapping, b'ui')
     diffopts = diffutil.diffallopts(ui)
     chunks = ctx.diff(
         match=ctx.match([], getpatterns(0), getpatterns(1)), opts=diffopts
     )
 
     return b''.join(chunks)
 
 
 @templatefunc(
     b'extdata(source)', argspec=b'source', requires={b'ctx', b'cache'}
 )
 def extdata(context, mapping, args):
     """Show a text read from the specified extdata source. (EXPERIMENTAL)"""
     if b'source' not in args:
         # i18n: "extdata" is a keyword
         raise error.ParseError(_(b'extdata expects one argument'))
 
     source = evalstring(context, mapping, args[b'source'])
     if not source:
         sym = templateutil.findsymbolicname(args[b'source'])
         if sym:
             raise error.ParseError(
                 _(b'empty data source specified'),
                 hint=_(b"did you mean extdata('%s')?") % sym,
             )
         else:
             raise error.ParseError(_(b'empty data source specified'))
     cache = context.resource(mapping, b'cache').setdefault(b'extdata', {})
     ctx = context.resource(mapping, b'ctx')
     if source in cache:
         data = cache[source]
     else:
         data = cache[source] = scmutil.extdatasource(ctx.repo(), source)
     return data.get(ctx.rev(), b'')
 
 
 @templatefunc(b'files(pattern)', requires={b'ctx'})
 def files(context, mapping, args):
     """All files of the current changeset matching the pattern. See
     :hg:`help patterns`."""
     if not len(args) == 1:
         # i18n: "files" is a keyword
         raise error.ParseError(_(b"files expects one argument"))
 
     raw = evalstring(context, mapping, args[0])
     ctx = context.resource(mapping, b'ctx')
     m = ctx.match([raw])
     files = list(ctx.matches(m))
     return templateutil.compatfileslist(context, mapping, b"file", files)
 
 
 @templatefunc(b'fill(text[, width[, initialident[, hangindent]]])')
 def fill(context, mapping, args):
     """Fill many
     paragraphs with optional indentation. See the "fill" filter."""
     if not (1 <= len(args) <= 4):
         # i18n: "fill" is a keyword
         raise error.ParseError(_(b"fill expects one to four arguments"))
 
     text = evalstring(context, mapping, args[0])
     width = 76
     initindent = b''
     hangindent = b''
     if 2 <= len(args) <= 4:
         width = evalinteger(
             context,
             mapping,
             args[1],
             # i18n: "fill" is a keyword
             _(b"fill expects an integer width"),
         )
         try:
             initindent = evalstring(context, mapping, args[2])
             hangindent = evalstring(context, mapping, args[3])
         except IndexError:
             pass
 
     return templatefilters.fill(text, width, initindent, hangindent)
 
 
 @templatefunc(b'filter(iterable[, expr])')
 def filter_(context, mapping, args):
     """Remove empty elements from a list or a dict. If expr specified, it's
     applied to each element to test emptiness."""
     if not (1 <= len(args) <= 2):
         # i18n: "filter" is a keyword
         raise error.ParseError(_(b"filter expects one or two arguments"))
     iterable = evalwrapped(context, mapping, args[0])
     if len(args) == 1:
 
         def select(w):
             return w.tobool(context, mapping)
 
     else:
 
         def select(w):
             if not isinstance(w, templateutil.mappable):
                 raise error.ParseError(_(b"not filterable by expression"))
             lm = context.overlaymap(mapping, w.tomap(context))
             return evalboolean(context, lm, args[1])
 
     return iterable.filter(context, mapping, select)
 
 
 @templatefunc(b'formatnode(node)', requires={b'ui'})
 def formatnode(context, mapping, args):
     """Obtain the preferred form of a changeset hash. (DEPRECATED)"""
     if len(args) != 1:
         # i18n: "formatnode" is a keyword
         raise error.ParseError(_(b"formatnode expects one argument"))
 
     ui = context.resource(mapping, b'ui')
     node = evalstring(context, mapping, args[0])
     if ui.debugflag:
         return node
     return templatefilters.short(node)
 
 
 @templatefunc(b'mailmap(author)', requires={b'repo', b'cache'})
 def mailmap(context, mapping, args):
     """Return the author, updated according to the value
     set in the .mailmap file"""
     if len(args) != 1:
         raise error.ParseError(_(b"mailmap expects one argument"))
 
     author = evalstring(context, mapping, args[0])
 
     cache = context.resource(mapping, b'cache')
     repo = context.resource(mapping, b'repo')
 
     if b'mailmap' not in cache:
         data = repo.wvfs.tryread(b'.mailmap')
         cache[b'mailmap'] = stringutil.parsemailmap(data)
 
     return stringutil.mapname(cache[b'mailmap'], author)
 
 
 @templatefunc(
     b'pad(text, width[, fillchar=\' \'[, left=False[, truncate=False]]])',
     argspec=b'text width fillchar left truncate',
 )
 def pad(context, mapping, args):
     """Pad text with a
     fill character."""
     if b'text' not in args or b'width' not in args:
         # i18n: "pad" is a keyword
         raise error.ParseError(_(b"pad() expects two to four arguments"))
 
     width = evalinteger(
         context,
         mapping,
         args[b'width'],
         # i18n: "pad" is a keyword
         _(b"pad() expects an integer width"),
     )
 
     text = evalstring(context, mapping, args[b'text'])
 
     truncate = False
     left = False
     fillchar = b' '
     if b'fillchar' in args:
         fillchar = evalstring(context, mapping, args[b'fillchar'])
         if len(color.stripeffects(fillchar)) != 1:
             # i18n: "pad" is a keyword
             raise error.ParseError(_(b"pad() expects a single fill character"))
     if b'left' in args:
         left = evalboolean(context, mapping, args[b'left'])
     if b'truncate' in args:
         truncate = evalboolean(context, mapping, args[b'truncate'])
 
     fillwidth = width - encoding.colwidth(color.stripeffects(text))
     if fillwidth < 0 and truncate:
         return encoding.trim(color.stripeffects(text), width, leftside=left)
     if fillwidth <= 0:
         return text
     if left:
         return fillchar * fillwidth + text
     else:
         return text + fillchar * fillwidth
 
 
 @templatefunc(b'indent(text, indentchars[, firstline])')
 def indent(context, mapping, args):
     """Indents all non-empty lines
     with the characters given in the indentchars string. An optional
     third parameter will override the indent for the first line only
     if present."""
     if not (2 <= len(args) <= 3):
         # i18n: "indent" is a keyword
         raise error.ParseError(_(b"indent() expects two or three arguments"))
 
     text = evalstring(context, mapping, args[0])
     indent = evalstring(context, mapping, args[1])
 
     firstline = indent
     if len(args) == 3:
         firstline = evalstring(context, mapping, args[2])
 
     return templatefilters.indent(text, indent, firstline=firstline)
 
 
 @templatefunc(b'get(dict, key)')
 def get(context, mapping, args):
     """Get an attribute/key from an object. Some keywords
     are complex types. This function allows you to obtain the value of an
     attribute on these types."""
     if len(args) != 2:
         # i18n: "get" is a keyword
         raise error.ParseError(_(b"get() expects two arguments"))
 
     dictarg = evalwrapped(context, mapping, args[0])
     key = evalrawexp(context, mapping, args[1])
     try:
         return dictarg.getmember(context, mapping, key)
     except error.ParseError as err:
         # i18n: "get" is a keyword
         hint = _(b"get() expects a dict as first argument")
         raise error.ParseError(bytes(err), hint=hint)
 
 
 @templatefunc(b'config(section, name[, default])', requires={b'ui'})
 def config(context, mapping, args):
     """Returns the requested hgrc config option as a string."""
     fn = context.resource(mapping, b'ui').config
     return _config(context, mapping, args, fn, evalstring)
 
 
 @templatefunc(b'configbool(section, name[, default])', requires={b'ui'})
 def configbool(context, mapping, args):
     """Returns the requested hgrc config option as a boolean."""
     fn = context.resource(mapping, b'ui').configbool
     return _config(context, mapping, args, fn, evalboolean)
 
 
 @templatefunc(b'configint(section, name[, default])', requires={b'ui'})
 def configint(context, mapping, args):
     """Returns the requested hgrc config option as an integer."""
     fn = context.resource(mapping, b'ui').configint
     return _config(context, mapping, args, fn, evalinteger)
 
 
 def _config(context, mapping, args, configfn, defaultfn):
     if not (2 <= len(args) <= 3):
         raise error.ParseError(_(b"config expects two or three arguments"))
 
     # The config option can come from any section, though we specifically
     # reserve the [templateconfig] section for dynamically defining options
     # for this function without also requiring an extension.
     section = evalstringliteral(context, mapping, args[0])
     name = evalstringliteral(context, mapping, args[1])
     if len(args) == 3:
         default = defaultfn(context, mapping, args[2])
         return configfn(section, name, default)
     else:
         return configfn(section, name)
 
 
 @templatefunc(b'if(expr, then[, else])')
 def if_(context, mapping, args):
     """Conditionally execute based on the result of
     an expression."""
     if not (2 <= len(args) <= 3):
         # i18n: "if" is a keyword
         raise error.ParseError(_(b"if expects two or three arguments"))
 
     test = evalboolean(context, mapping, args[0])
     if test:
         return evalrawexp(context, mapping, args[1])
     elif len(args) == 3:
         return evalrawexp(context, mapping, args[2])
 
 
 @templatefunc(b'ifcontains(needle, haystack, then[, else])')
 def ifcontains(context, mapping, args):
     """Conditionally execute based
     on whether the item "needle" is in "haystack"."""
     if not (3 <= len(args) <= 4):
         # i18n: "ifcontains" is a keyword
         raise error.ParseError(_(b"ifcontains expects three or four arguments"))
 
     haystack = evalwrapped(context, mapping, args[1])
     try:
         needle = evalrawexp(context, mapping, args[0])
         found = haystack.contains(context, mapping, needle)
     except error.ParseError:
         found = False
 
     if found:
         return evalrawexp(context, mapping, args[2])
     elif len(args) == 4:
         return evalrawexp(context, mapping, args[3])
 
 
 @templatefunc(b'ifeq(expr1, expr2, then[, else])')
 def ifeq(context, mapping, args):
     """Conditionally execute based on
     whether 2 items are equivalent."""
     if not (3 <= len(args) <= 4):
         # i18n: "ifeq" is a keyword
         raise error.ParseError(_(b"ifeq expects three or four arguments"))
 
     test = evalstring(context, mapping, args[0])
     match = evalstring(context, mapping, args[1])
     if test == match:
         return evalrawexp(context, mapping, args[2])
     elif len(args) == 4:
         return evalrawexp(context, mapping, args[3])
 
 
 @templatefunc(b'join(list, sep)')
 def join(context, mapping, args):
     """Join items in a list with a delimiter."""
     if not (1 <= len(args) <= 2):
         # i18n: "join" is a keyword
         raise error.ParseError(_(b"join expects one or two arguments"))
 
     joinset = evalwrapped(context, mapping, args[0])
     joiner = b" "
     if len(args) > 1:
         joiner = evalstring(context, mapping, args[1])
     return joinset.join(context, mapping, joiner)
 
 
 @templatefunc(b'label(label, expr)', requires={b'ui'})
 def label(context, mapping, args):
-    """Apply a label to generated content. Content with
-    a label applied can result in additional post-processing, such as
-    automatic colorization."""
+    """Apply a label to generated content. Content with a label
+    applied can result in additional post-processing, such as
+    automatic colorization. In order to receive effects, labels must
+    have a dot, such as `log.secret` or `branch.active`."""
     if len(args) != 2:
         # i18n: "label" is a keyword
         raise error.ParseError(_(b"label expects two arguments"))
 
     ui = context.resource(mapping, b'ui')
     thing = evalstring(context, mapping, args[1])
     # preserve unknown symbol as literal so effects like 'red', 'bold',
     # etc. don't need to be quoted
     label = evalstringliteral(context, mapping, args[0])
 
     return ui.label(thing, label)
 
 
 @templatefunc(b'latesttag([pattern])')
 def latesttag(context, mapping, args):
     """The global tags matching the given pattern on the
     most recent globally tagged ancestor of this changeset.
     If no such tags exist, the "{tag}" template resolves to
     the string "null". See :hg:`help revisions.patterns` for the pattern
     syntax.
     """
     if len(args) > 1:
         # i18n: "latesttag" is a keyword
         raise error.ParseError(_(b"latesttag expects at most one argument"))
 
     pattern = None
     if len(args) == 1:
         pattern = evalstring(context, mapping, args[0])
     return templatekw.showlatesttags(context, mapping, pattern)
 
 
 @templatefunc(b'localdate(date[, tz])')
 def localdate(context, mapping, args):
     """Converts a date to the specified timezone.
     The default is local date."""
     if not (1 <= len(args) <= 2):
         # i18n: "localdate" is a keyword
         raise error.ParseError(_(b"localdate expects one or two arguments"))
 
     date = evaldate(
         context,
         mapping,
         args[0],
         # i18n: "localdate" is a keyword
         _(b"localdate expects a date information"),
     )
     if len(args) >= 2:
         tzoffset = None
         tz = evalfuncarg(context, mapping, args[1])
         if isinstance(tz, bytes):
             tzoffset, remainder = dateutil.parsetimezone(tz)
             if remainder:
                 tzoffset = None
         if tzoffset is None:
             try:
                 tzoffset = int(tz)
             except (TypeError, ValueError):
                 # i18n: "localdate" is a keyword
                 raise error.ParseError(_(b"localdate expects a timezone"))
     else:
         tzoffset = dateutil.makedate()[1]
     return templateutil.date((date[0], tzoffset))
 
 
 @templatefunc(b'max(iterable)')
 def max_(context, mapping, args, **kwargs):
     """Return the max of an iterable"""
     if len(args) != 1:
         # i18n: "max" is a keyword
         raise error.ParseError(_(b"max expects one argument"))
 
     iterable = evalwrapped(context, mapping, args[0])
     try:
         return iterable.getmax(context, mapping)
     except error.ParseError as err:
         # i18n: "max" is a keyword
         hint = _(b"max first argument should be an iterable")
         raise error.ParseError(bytes(err), hint=hint)
 
 
 @templatefunc(b'min(iterable)')
 def min_(context, mapping, args, **kwargs):
     """Return the min of an iterable"""
     if len(args) != 1:
         # i18n: "min" is a keyword
         raise error.ParseError(_(b"min expects one argument"))
 
     iterable = evalwrapped(context, mapping, args[0])
     try:
         return iterable.getmin(context, mapping)
     except error.ParseError as err:
         # i18n: "min" is a keyword
         hint = _(b"min first argument should be an iterable")
         raise error.ParseError(bytes(err), hint=hint)
 
 
 @templatefunc(b'mod(a, b)')
 def mod(context, mapping, args):
     """Calculate a mod b such that a / b + a mod b == a"""
     if not len(args) == 2:
         # i18n: "mod" is a keyword
         raise error.ParseError(_(b"mod expects two arguments"))
 
     func = lambda a, b: a % b
     return templateutil.runarithmetic(
         context, mapping, (func, args[0], args[1])
     )
 
 
 @templatefunc(b'obsfateoperations(markers)')
 def obsfateoperations(context, mapping, args):
     """Compute obsfate related information based on markers (EXPERIMENTAL)"""
     if len(args) != 1:
         # i18n: "obsfateoperations" is a keyword
         raise error.ParseError(_(b"obsfateoperations expects one argument"))
 
     markers = evalfuncarg(context, mapping, args[0])
 
     try:
         data = obsutil.markersoperations(markers)
         return templateutil.hybridlist(data, name=b'operation')
     except (TypeError, KeyError):
         # i18n: "obsfateoperations" is a keyword
         errmsg = _(b"obsfateoperations first argument should be an iterable")
         raise error.ParseError(errmsg)
 
 
 @templatefunc(b'obsfatedate(markers)')
 def obsfatedate(context, mapping, args):
     """Compute obsfate related information based on markers (EXPERIMENTAL)"""
     if len(args) != 1:
         # i18n: "obsfatedate" is a keyword
         raise error.ParseError(_(b"obsfatedate expects one argument"))
 
     markers = evalfuncarg(context, mapping, args[0])
 
     try:
         # TODO: maybe this has to be a wrapped list of date wrappers?
         data = obsutil.markersdates(markers)
         return templateutil.hybridlist(data, name=b'date', fmt=b'%d %d')
     except (TypeError, KeyError):
         # i18n: "obsfatedate" is a keyword
         errmsg = _(b"obsfatedate first argument should be an iterable")
         raise error.ParseError(errmsg)
 
 
 @templatefunc(b'obsfateusers(markers)')
 def obsfateusers(context, mapping, args):
     """Compute obsfate related information based on markers (EXPERIMENTAL)"""
     if len(args) != 1:
         # i18n: "obsfateusers" is a keyword
         raise error.ParseError(_(b"obsfateusers expects one argument"))
 
     markers = evalfuncarg(context, mapping, args[0])
 
     try:
         data = obsutil.markersusers(markers)
         return templateutil.hybridlist(data, name=b'user')
     except (TypeError, KeyError, ValueError):
         # i18n: "obsfateusers" is a keyword
         msg = _(
             b"obsfateusers first argument should be an iterable of "
             b"obsmakers"
         )
         raise error.ParseError(msg)
 
 
 @templatefunc(b'obsfateverb(successors, markers)')
 def obsfateverb(context, mapping, args):
     """Compute obsfate related information based on successors (EXPERIMENTAL)"""
     if len(args) != 2:
         # i18n: "obsfateverb" is a keyword
         raise error.ParseError(_(b"obsfateverb expects two arguments"))
 
     successors = evalfuncarg(context, mapping, args[0])
     markers = evalfuncarg(context, mapping, args[1])
 
     try:
         return obsutil.obsfateverb(successors, markers)
     except TypeError:
         # i18n: "obsfateverb" is a keyword
         errmsg = _(b"obsfateverb first argument should be countable")
         raise error.ParseError(errmsg)
 
 
 @templatefunc(b'relpath(path)', requires={b'repo'})
 def relpath(context, mapping, args):
     """Convert a repository-absolute path into a filesystem path relative to
     the current working directory."""
     if len(args) != 1:
         # i18n: "relpath" is a keyword
         raise error.ParseError(_(b"relpath expects one argument"))
 
     repo = context.resource(mapping, b'repo')
     path = evalstring(context, mapping, args[0])
     return repo.pathto(path)
 
 
 @templatefunc(b'revset(query[, formatargs...])', requires={b'repo', b'cache'})
 def revset(context, mapping, args):
     """Execute a revision set query. See
     :hg:`help revset`."""
     if not len(args) > 0:
         # i18n: "revset" is a keyword
         raise error.ParseError(_(b"revset expects one or more arguments"))
 
     raw = evalstring(context, mapping, args[0])
     repo = context.resource(mapping, b'repo')
 
     def query(expr):
         m = revsetmod.match(repo.ui, expr, lookup=revsetmod.lookupfn(repo))
         return m(repo)
 
     if len(args) > 1:
         key = None  # dynamically-created revs shouldn't be cached
         formatargs = [evalfuncarg(context, mapping, a) for a in args[1:]]
         revs = query(revsetlang.formatspec(raw, *formatargs))
     else:
         cache = context.resource(mapping, b'cache')
         revsetcache = cache.setdefault(b"revsetcache", {})
         key = raw
         if key in revsetcache:
             revs = revsetcache[key]
         else:
             revs = query(raw)
             revsetcache[key] = revs
     return templateutil.revslist(repo, revs, name=b'revision', cachekey=key)
 
 
 @templatefunc(b'rstdoc(text, style)')
 def rstdoc(context, mapping, args):
     """Format reStructuredText."""
     if len(args) != 2:
         # i18n: "rstdoc" is a keyword
         raise error.ParseError(_(b"rstdoc expects two arguments"))
 
     text = evalstring(context, mapping, args[0])
     style = evalstring(context, mapping, args[1])
 
     return minirst.format(text, style=style, keep=[b'verbose'])
 
 
 @templatefunc(b'search(pattern, text)')
 def search(context, mapping, args):
     """Look for the first text matching the regular expression pattern.
     Groups are accessible as ``{1}``, ``{2}``, ... in %-mapped template."""
     if len(args) != 2:
         # i18n: "search" is a keyword
         raise error.ParseError(_(b'search expects two arguments'))
 
     pat = evalstring(context, mapping, args[0])
     src = evalstring(context, mapping, args[1])
     try:
         patre = re.compile(pat)
     except re.error:
         # i18n: "search" is a keyword
         raise error.ParseError(_(b'search got an invalid pattern: %s') % pat)
     # named groups shouldn't shadow *reserved* resource keywords
     badgroups = context.knownresourcekeys() & set(
         pycompat.byteskwargs(patre.groupindex)
     )
     if badgroups:
         raise error.ParseError(
             # i18n: "search" is a keyword
             _(b'invalid group %(group)s in search pattern: %(pat)s')
             % {
                 b'group': b', '.join(b"'%s'" % g for g in sorted(badgroups)),
                 b'pat': pat,
             }
         )
 
     match = patre.search(src)
     if not match:
         return templateutil.mappingnone()
 
     lm = {b'0': match.group(0)}
     lm.update((b'%d' % i, v) for i, v in enumerate(match.groups(), 1))
     lm.update(pycompat.byteskwargs(match.groupdict()))
     return templateutil.mappingdict(lm, tmpl=b'{0}')
 
 
 @templatefunc(b'separate(sep, args...)', argspec=b'sep *args')
 def separate(context, mapping, args):
     """Add a separator between non-empty arguments."""
     if b'sep' not in args:
         # i18n: "separate" is a keyword
         raise error.ParseError(_(b"separate expects at least one argument"))
 
     sep = evalstring(context, mapping, args[b'sep'])
     first = True
     for arg in args[b'args']:
         argstr = evalstring(context, mapping, arg)
         if not argstr:
             continue
         if first:
             first = False
         else:
             yield sep
         yield argstr
 
 
 @templatefunc(b'shortest(node, minlength=4)', requires={b'repo', b'cache'})
 def shortest(context, mapping, args):
     """Obtain the shortest representation of
     a node."""
     if not (1 <= len(args) <= 2):
         # i18n: "shortest" is a keyword
         raise error.ParseError(_(b"shortest() expects one or two arguments"))
 
     hexnode = evalstring(context, mapping, args[0])
 
     minlength = 4
     if len(args) > 1:
         minlength = evalinteger(
             context,
             mapping,
             args[1],
             # i18n: "shortest" is a keyword
             _(b"shortest() expects an integer minlength"),
         )
 
     repo = context.resource(mapping, b'repo')
     hexnodelen = 2 * repo.nodeconstants.nodelen
     if len(hexnode) > hexnodelen:
         return hexnode
     elif len(hexnode) == hexnodelen:
         try:
             node = bin(hexnode)
         except binascii.Error:
             return hexnode
     else:
         try:
             node = scmutil.resolvehexnodeidprefix(repo, hexnode)
         except error.WdirUnsupported:
             node = repo.nodeconstants.wdirid
         except error.LookupError:
             return hexnode
         if not node:
             return hexnode
     cache = context.resource(mapping, b'cache')
     try:
         return scmutil.shortesthexnodeidprefix(repo, node, minlength, cache)
     except error.RepoLookupError:
         return hexnode
 
 
 @templatefunc(b'strip(text[, chars])')
 def strip(context, mapping, args):
     """Strip characters from a string. By default,
     strips all leading and trailing whitespace."""
     if not (1 <= len(args) <= 2):
         # i18n: "strip" is a keyword
         raise error.ParseError(_(b"strip expects one or two arguments"))
 
     text = evalstring(context, mapping, args[0])
     if len(args) == 2:
         chars = evalstring(context, mapping, args[1])
         return text.strip(chars)
     return text.strip()
 
 
 @templatefunc(b'sub(pattern, replacement, expression)')
 def sub(context, mapping, args):
     """Perform text substitution
     using regular expressions."""
     if len(args) != 3:
         # i18n: "sub" is a keyword
         raise error.ParseError(_(b"sub expects three arguments"))
 
     pat = evalstring(context, mapping, args[0])
     rpl = evalstring(context, mapping, args[1])
     src = evalstring(context, mapping, args[2])
     try:
         patre = re.compile(pat)
     except re.error:
         # i18n: "sub" is a keyword
         raise error.ParseError(_(b"sub got an invalid pattern: %s") % pat)
     try:
         yield patre.sub(rpl, src)
     except re.error:
         # i18n: "sub" is a keyword
         raise error.ParseError(_(b"sub got an invalid replacement: %s") % rpl)
 
 
 @templatefunc(b'startswith(pattern, text)')
 def startswith(context, mapping, args):
     """Returns the value from the "text" argument
     if it begins with the content from the "pattern" argument."""
     if len(args) != 2:
         # i18n: "startswith" is a keyword
         raise error.ParseError(_(b"startswith expects two arguments"))
 
     patn = evalstring(context, mapping, args[0])
     text = evalstring(context, mapping, args[1])
     if text.startswith(patn):
         return text
     return b''
 
 
 @templatefunc(
     b'subsetparents(rev, revset)',
     argspec=b'rev revset',
     requires={b'repo', b'cache'},
 )
 def subsetparents(context, mapping, args):
     """Look up parents of the rev in the sub graph given by the revset."""
     if b'rev' not in args or b'revset' not in args:
         # i18n: "subsetparents" is a keyword
         raise error.ParseError(_(b"subsetparents expects two arguments"))
 
     repo = context.resource(mapping, b'repo')
 
     rev = templateutil.evalinteger(context, mapping, args[b'rev'])
 
     # TODO: maybe subsetparents(rev) should be allowed. the default revset
     # will be the revisions specified by -rREV argument.
     q = templateutil.evalwrapped(context, mapping, args[b'revset'])
     if not isinstance(q, templateutil.revslist):
         # i18n: "subsetparents" is a keyword
         raise error.ParseError(_(b"subsetparents expects a queried revset"))
     subset = q.tovalue(context, mapping)
     key = q.cachekey
 
     if key:
         # cache only if revset query isn't dynamic
         cache = context.resource(mapping, b'cache')
         walkercache = cache.setdefault(b'subsetparentswalker', {})
         if key in walkercache:
             walker = walkercache[key]
         else:
             walker = dagop.subsetparentswalker(repo, subset)
             walkercache[key] = walker
     else:
         # for one-shot use, specify startrev to limit the search space
         walker = dagop.subsetparentswalker(repo, subset, startrev=rev)
     return templateutil.revslist(repo, walker.parentsset(rev))
 
 
 @templatefunc(b'word(number, text[, separator])')
 def word(context, mapping, args):
     """Return the nth word from a string."""
     if not (2 <= len(args) <= 3):
         # i18n: "word" is a keyword
         raise error.ParseError(
             _(b"word expects two or three arguments, got %d") % len(args)
         )
 
     num = evalinteger(
         context,
         mapping,
         args[0],
         # i18n: "word" is a keyword
         _(b"word expects an integer index"),
     )
     text = evalstring(context, mapping, args[1])
     if len(args) == 3:
         splitter = evalstring(context, mapping, args[2])
     else:
         splitter = None
 
     tokens = text.split(splitter)
     if num >= len(tokens) or num < -len(tokens):
         return b''
     else:
         return tokens[num]
 
 
 def loadfunction(ui, extname, registrarobj):
     """Load template function from specified registrarobj"""
     for name, func in registrarobj._table.items():
         funcs[name] = func
 
 
 # tell hggettext to extract docstrings from these functions:
 i18nfunctions = funcs.values()