templater: abstract away from joinfmt

Future patches will add a wrapper for a list of template mappings, which
will implement a custom join() something like {join(mappings % template)}.

The original join() function is broken down as follows:

  if hasattr(joinset, 'joinfmt'):
      # hybrid.join() where values must be a list or a dict
      joinitems((joinfmt(x) for x in values), sep)
  elif isinstance(joinset, templateutil.wrapped):
      # mappable.join()
      show()
  else:
      # a plain list, a generator, or a byte string; joinfmt was identity()
      joinset = templateutil.unwrapvalue(context, joinset)
      joinitems(pycompat.maybebytestr(joinset), joiner)

mercurial/templatefuncs.py

@@ -1,676 +1,676 b''
 # templatefuncs.py - common template functions
 #
 # Copyright 2005, 2006 Matt 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.
 
 from __future__ import absolute_import
 
 import re
 
 from .i18n import _
 from . import (
     color,
     encoding,
     error,
     minirst,
     obsutil,
     pycompat,
     registrar,
     revset as revsetmod,
     revsetlang,
     scmutil,
     templatefilters,
     templatekw,
     templateutil,
     util,
 )
 from .utils import (
     dateutil,
     stringutil,
 )
 
 evalrawexp = templateutil.evalrawexp
 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('date(date[, fmt])')
 def date(context, mapping, args):
     """Format a date. See :hg:`help dates` for formatting
     strings. 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(_("date expects one or two arguments"))
 
     date = evaldate(context, mapping, args[0],
                     # i18n: "date" is a keyword
                     _("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('dict([[key=]value...])', argspec='*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['args']:
         k = templateutil.findsymbolicname(v)
         if not k:
             raise error.ParseError(_('dict key cannot be inferred'))
         if k in data or k in args['kwargs']:
             raise error.ParseError(_("duplicated dict key '%s' inferred") % k)
         data[k] = evalfuncarg(context, mapping, v)
 
     data.update((k, evalfuncarg(context, mapping, v))
                 for k, v in args['kwargs'].iteritems())
     return templateutil.hybriddict(data)
 
 @templatefunc('diff([includepattern [, excludepattern]])')
 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(_("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, 'ctx')
     chunks = ctx.diff(match=ctx.match([], getpatterns(0), getpatterns(1)))
 
     return ''.join(chunks)
 
 @templatefunc('extdata(source)', argspec='source')
 def extdata(context, mapping, args):
     """Show a text read from the specified extdata source. (EXPERIMENTAL)"""
     if 'source' not in args:
         # i18n: "extdata" is a keyword
         raise error.ParseError(_('extdata expects one argument'))
 
     source = evalstring(context, mapping, args['source'])
     cache = context.resource(mapping, 'cache').setdefault('extdata', {})
     ctx = context.resource(mapping, 'ctx')
     if source in cache:
         data = cache[source]
     else:
         data = cache[source] = scmutil.extdatasource(ctx.repo(), source)
     return data.get(ctx.rev(), '')
 
 @templatefunc('files(pattern)')
 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(_("files expects one argument"))
 
     raw = evalstring(context, mapping, args[0])
     ctx = context.resource(mapping, 'ctx')
     m = ctx.match([raw])
     files = list(ctx.matches(m))
     return templateutil.compatlist(context, mapping, "file", files)
 
 @templatefunc('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(_("fill expects one to four arguments"))
 
     text = evalstring(context, mapping, args[0])
     width = 76
     initindent = ''
     hangindent = ''
     if 2 <= len(args) <= 4:
         width = evalinteger(context, mapping, args[1],
                             # i18n: "fill" is a keyword
                             _("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('formatnode(node)')
 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(_("formatnode expects one argument"))
 
     ui = context.resource(mapping, 'ui')
     node = evalstring(context, mapping, args[0])
     if ui.debugflag:
         return node
     return templatefilters.short(node)
 
 @templatefunc('mailmap(author)')
 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(_("mailmap expects one argument"))
 
     author = evalstring(context, mapping, args[0])
 
     cache = context.resource(mapping, 'cache')
     repo = context.resource(mapping, 'repo')
 
     if 'mailmap' not in cache:
         data = repo.wvfs.tryread('.mailmap')
         cache['mailmap'] = stringutil.parsemailmap(data)
 
     return stringutil.mapname(cache['mailmap'], author)
 
 @templatefunc('pad(text, width[, fillchar=\' \'[, left=False]])',
               argspec='text width fillchar left')
 def pad(context, mapping, args):
     """Pad text with a
     fill character."""
     if 'text' not in args or 'width' not in args:
         # i18n: "pad" is a keyword
         raise error.ParseError(_("pad() expects two to four arguments"))
 
     width = evalinteger(context, mapping, args['width'],
                         # i18n: "pad" is a keyword
                         _("pad() expects an integer width"))
 
     text = evalstring(context, mapping, args['text'])
 
     left = False
     fillchar = ' '
     if 'fillchar' in args:
         fillchar = evalstring(context, mapping, args['fillchar'])
         if len(color.stripeffects(fillchar)) != 1:
             # i18n: "pad" is a keyword
             raise error.ParseError(_("pad() expects a single fill character"))
     if 'left' in args:
         left = evalboolean(context, mapping, args['left'])
 
     fillwidth = width - encoding.colwidth(color.stripeffects(text))
     if fillwidth <= 0:
         return text
     if left:
         return fillchar * fillwidth + text
     else:
         return text + fillchar * fillwidth
 
 @templatefunc('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(_("indent() expects two or three arguments"))
 
     text = evalstring(context, mapping, args[0])
     indent = evalstring(context, mapping, args[1])
 
     if len(args) == 3:
         firstline = evalstring(context, mapping, args[2])
     else:
         firstline = indent
 
     # the indent function doesn't indent the first line, so we do it here
     return templatefilters.indent(firstline + text, indent)
 
 @templatefunc('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(_("get() expects two arguments"))
 
     dictarg = evalfuncarg(context, mapping, args[0])
     if not util.safehasattr(dictarg, 'get'):
         # i18n: "get" is a keyword
         raise error.ParseError(_("get() expects a dict as first argument"))
 
     key = evalfuncarg(context, mapping, args[1])
     return templateutil.getdictitem(dictarg, key)
 
 @templatefunc('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(_("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('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(_("ifcontains expects three or four arguments"))
 
     haystack = evalfuncarg(context, mapping, args[1])
     keytype = getattr(haystack, 'keytype', None)
     try:
         needle = evalrawexp(context, mapping, args[0])
         needle = templateutil.unwrapastype(context, mapping, needle,
                                            keytype or bytes)
         found = (needle in haystack)
     except error.ParseError:
         found = False
 
     if found:
         return evalrawexp(context, mapping, args[2])
     elif len(args) == 4:
         return evalrawexp(context, mapping, args[3])
 
 @templatefunc('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(_("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('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(_("join expects one or two arguments"))
 
-    # TODO: perhaps this should be evalfuncarg(), but it can't because hgweb
-    # abuses generator as a keyword that returns a list of dicts.
     joinset = evalrawexp(context, mapping, args[0])
-    joinset = templateutil.unwrapvalue(context, mapping, joinset)
-    joinfmt = getattr(joinset, 'joinfmt', pycompat.identity)
     joiner = " "
     if len(args) > 1:
         joiner = evalstring(context, mapping, args[1])
-    itemiter = (joinfmt(x) for x in pycompat.maybebytestr(joinset))
-    return templateutil.joinitems(itemiter, joiner)
+    if isinstance(joinset, templateutil.wrapped):
+        return joinset.join(context, mapping, joiner)
+    # TODO: perhaps a generator should be stringify()-ed here, but we can't
+    # because hgweb abuses it as a keyword that returns a list of dicts.
+    joinset = templateutil.unwrapvalue(context, mapping, joinset)
+    return templateutil.joinitems(pycompat.maybebytestr(joinset), joiner)
 
 @templatefunc('label(label, expr)')
 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."""
     if len(args) != 2:
         # i18n: "label" is a keyword
         raise error.ParseError(_("label expects two arguments"))
 
     ui = context.resource(mapping, '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('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"."""
     if len(args) > 1:
         # i18n: "latesttag" is a keyword
         raise error.ParseError(_("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('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(_("localdate expects one or two arguments"))
 
     date = evaldate(context, mapping, args[0],
                     # i18n: "localdate" is a keyword
                     _("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(_("localdate expects a timezone"))
     else:
         tzoffset = dateutil.makedate()[1]
     return (date[0], tzoffset)
 
 @templatefunc('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(_("max expects one argument"))
 
     iterable = evalfuncarg(context, mapping, args[0])
     try:
         x = max(pycompat.maybebytestr(iterable))
     except (TypeError, ValueError):
         # i18n: "max" is a keyword
         raise error.ParseError(_("max first argument should be an iterable"))
     return templateutil.wraphybridvalue(iterable, x, x)
 
 @templatefunc('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(_("min expects one argument"))
 
     iterable = evalfuncarg(context, mapping, args[0])
     try:
         x = min(pycompat.maybebytestr(iterable))
     except (TypeError, ValueError):
         # i18n: "min" is a keyword
         raise error.ParseError(_("min first argument should be an iterable"))
     return templateutil.wraphybridvalue(iterable, x, x)
 
 @templatefunc('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(_("mod expects two arguments"))
 
     func = lambda a, b: a % b
     return templateutil.runarithmetic(context, mapping,
                                       (func, args[0], args[1]))
 
 @templatefunc('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(_("obsfateoperations expects one argument"))
 
     markers = evalfuncarg(context, mapping, args[0])
 
     try:
         data = obsutil.markersoperations(markers)
         return templateutil.hybridlist(data, name='operation')
     except (TypeError, KeyError):
         # i18n: "obsfateoperations" is a keyword
         errmsg = _("obsfateoperations first argument should be an iterable")
         raise error.ParseError(errmsg)
 
 @templatefunc('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(_("obsfatedate expects one argument"))
 
     markers = evalfuncarg(context, mapping, args[0])
 
     try:
         data = obsutil.markersdates(markers)
         return templateutil.hybridlist(data, name='date', fmt='%d %d')
     except (TypeError, KeyError):
         # i18n: "obsfatedate" is a keyword
         errmsg = _("obsfatedate first argument should be an iterable")
         raise error.ParseError(errmsg)
 
 @templatefunc('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(_("obsfateusers expects one argument"))
 
     markers = evalfuncarg(context, mapping, args[0])
 
     try:
         data = obsutil.markersusers(markers)
         return templateutil.hybridlist(data, name='user')
     except (TypeError, KeyError, ValueError):
         # i18n: "obsfateusers" is a keyword
         msg = _("obsfateusers first argument should be an iterable of "
                 "obsmakers")
         raise error.ParseError(msg)
 
 @templatefunc('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(_("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 = _("obsfateverb first argument should be countable")
         raise error.ParseError(errmsg)
 
 @templatefunc('relpath(path)')
 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(_("relpath expects one argument"))
 
     repo = context.resource(mapping, 'ctx').repo()
     path = evalstring(context, mapping, args[0])
     return repo.pathto(path)
 
 @templatefunc('revset(query[, formatargs...])')
 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(_("revset expects one or more arguments"))
 
     raw = evalstring(context, mapping, args[0])
     ctx = context.resource(mapping, 'ctx')
     repo = ctx.repo()
 
     def query(expr):
         m = revsetmod.match(repo.ui, expr, repo=repo)
         return m(repo)
 
     if len(args) > 1:
         formatargs = [evalfuncarg(context, mapping, a) for a in args[1:]]
         revs = query(revsetlang.formatspec(raw, *formatargs))
         revs = list(revs)
     else:
         cache = context.resource(mapping, 'cache')
         revsetcache = cache.setdefault("revsetcache", {})
         if raw in revsetcache:
             revs = revsetcache[raw]
         else:
             revs = query(raw)
             revs = list(revs)
             revsetcache[raw] = revs
     return templatekw.showrevslist(context, mapping, "revision", revs)
 
 @templatefunc('rstdoc(text, style)')
 def rstdoc(context, mapping, args):
     """Format reStructuredText."""
     if len(args) != 2:
         # i18n: "rstdoc" is a keyword
         raise error.ParseError(_("rstdoc expects two arguments"))
 
     text = evalstring(context, mapping, args[0])
     style = evalstring(context, mapping, args[1])
 
     return minirst.format(text, style=style, keep=['verbose'])
 
 @templatefunc('separate(sep, args)', argspec='sep *args')
 def separate(context, mapping, args):
     """Add a separator between non-empty arguments."""
     if 'sep' not in args:
         # i18n: "separate" is a keyword
         raise error.ParseError(_("separate expects at least one argument"))
 
     sep = evalstring(context, mapping, args['sep'])
     first = True
     for arg in args['args']:
         argstr = evalstring(context, mapping, arg)
         if not argstr:
             continue
         if first:
             first = False
         else:
             yield sep
         yield argstr
 
 @templatefunc('shortest(node, minlength=4)')
 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(_("shortest() expects one or two arguments"))
 
     node = evalstring(context, mapping, args[0])
 
     minlength = 4
     if len(args) > 1:
         minlength = evalinteger(context, mapping, args[1],
                                 # i18n: "shortest" is a keyword
                                 _("shortest() expects an integer minlength"))
 
     # _partialmatch() of filtered changelog could take O(len(repo)) time,
     # which would be unacceptably slow. so we look for hash collision in
     # unfiltered space, which means some hashes may be slightly longer.
     cl = context.resource(mapping, 'ctx')._repo.unfiltered().changelog
     return cl.shortest(node, minlength)
 
 @templatefunc('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(_("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('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(_("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(_("sub got an invalid pattern: %s") % pat)
     try:
         yield patre.sub(rpl, src)
     except re.error:
         # i18n: "sub" is a keyword
         raise error.ParseError(_("sub got an invalid replacement: %s") % rpl)
 
 @templatefunc('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(_("startswith expects two arguments"))
 
     patn = evalstring(context, mapping, args[0])
     text = evalstring(context, mapping, args[1])
     if text.startswith(patn):
         return text
     return ''
 
 @templatefunc('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(_("word expects two or three arguments, got %d")
                                % len(args))
 
     num = evalinteger(context, mapping, args[0],
                       # i18n: "word" is a keyword
                       _("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 ''
     else:
         return tokens[num]
 
 def loadfunction(ui, extname, registrarobj):
     """Load template function from specified registrarobj
     """
     for name, func in registrarobj._table.iteritems():
         funcs[name] = func
 
 # tell hggettext to extract docstrings from these functions:
 i18nfunctions = funcs.values()

mercurial/templateutil.py

@@ -1,563 +1,584 b''
 # templateutil.py - utility for template evaluation
 #
 # Copyright 2005, 2006 Matt 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.
 
 from __future__ import absolute_import
 
 import abc
 import types
 
 from .i18n import _
 from . import (
     error,
     pycompat,
     util,
 )
 from .utils import (
     dateutil,
     stringutil,
 )
 
 class ResourceUnavailable(error.Abort):
     pass
 
 class TemplateNotFound(error.Abort):
     pass
 
 class wrapped(object):
     """Object requiring extra conversion prior to displaying or processing
     as value
 
     Use unwrapvalue(), unwrapastype(), or unwraphybrid() to obtain the inner
     object.
     """
 
     __metaclass__ = abc.ABCMeta
 
     @abc.abstractmethod
     def itermaps(self, context):
         """Yield each template mapping"""
 
     @abc.abstractmethod
+    def join(self, context, mapping, sep):
+        """Join items with the separator; Returns a bytes or (possibly nested)
+        generator of bytes
+
+        A pre-configured template may be rendered per item if this container
+        holds unprintable items.
+        """
+
+    @abc.abstractmethod
     def show(self, context, mapping):
         """Return a bytes or (possibly nested) generator of bytes representing
         the underlying object
 
         A pre-configured template may be rendered if the underlying object is
         not printable.
         """
 
     @abc.abstractmethod
     def tovalue(self, context, mapping):
         """Move the inner value object out or create a value representation
 
         A returned value must be serializable by templaterfilters.json().
         """
 
 # stub for representing a date type; may be a real date type that can
 # provide a readable string value
 class date(object):
     pass
 
 class hybrid(wrapped):
     """Wrapper for list or dict to support legacy template
 
     This class allows us to handle both:
     - "{files}" (legacy command-line-specific list hack) and
     - "{files % '{file}\n'}" (hgweb-style with inlining and function support)
     and to access raw values:
     - "{ifcontains(file, files, ...)}", "{ifcontains(key, extras, ...)}"
     - "{get(extras, key)}"
     - "{files|json}"
     """
 
     def __init__(self, gen, values, makemap, joinfmt, keytype=None):
         self._gen = gen  # generator or function returning generator
         self._values = values
         self._makemap = makemap
         self.joinfmt = joinfmt
         self.keytype = keytype  # hint for 'x in y' where type(x) is unresolved
 
     def itermaps(self, context):
         makemap = self._makemap
         for x in self._values:
             yield makemap(x)
 
+    def join(self, context, mapping, sep):
+        # TODO: switch gen to (context, mapping) API?
+        return joinitems((self.joinfmt(x) for x in self._values), sep)
+
     def show(self, context, mapping):
         # TODO: switch gen to (context, mapping) API?
         gen = self._gen
         if gen is None:
-            return joinitems((self.joinfmt(x) for x in self._values), ' ')
+            return self.join(context, mapping, ' ')
         if callable(gen):
             return gen()
         return gen
 
     def tovalue(self, context, mapping):
         # TODO: return self._values and get rid of proxy methods
         return self
 
     def __contains__(self, x):
         return x in self._values
     def __getitem__(self, key):
         return self._values[key]
     def __len__(self):
         return len(self._values)
     def __iter__(self):
         return iter(self._values)
     def __getattr__(self, name):
         if name not in (r'get', r'items', r'iteritems', r'iterkeys',
                         r'itervalues', r'keys', r'values'):
             raise AttributeError(name)
         return getattr(self._values, name)
 
 class mappable(wrapped):
     """Wrapper for non-list/dict object to support map operation
 
     This class allows us to handle both:
     - "{manifest}"
     - "{manifest % '{rev}:{node}'}"
     - "{manifest.rev}"
 
     Unlike a hybrid, this does not simulate the behavior of the underling
     value.
     """
 
     def __init__(self, gen, key, value, makemap):
         self._gen = gen  # generator or function returning generator
         self._key = key
         self._value = value  # may be generator of strings
         self._makemap = makemap
 
     def tomap(self):
         return self._makemap(self._key)
 
     def itermaps(self, context):
         yield self.tomap()
 
+    def join(self, context, mapping, sep):
+        # TODO: just copies the old behavior where a value was a generator
+        # yielding one item, but reconsider about it. join() over a string
+        # has no consistent result because a string may be a bytes, or a
+        # generator yielding an item, or a generator yielding multiple items.
+        # Preserving all of the current behaviors wouldn't make any sense.
+        return self.show(context, mapping)
+
     def show(self, context, mapping):
         # TODO: switch gen to (context, mapping) API?
         gen = self._gen
         if gen is None:
             return pycompat.bytestr(self._value)
         if callable(gen):
             return gen()
         return gen
 
     def tovalue(self, context, mapping):
         return _unthunk(context, mapping, self._value)
 
 def hybriddict(data, key='key', value='value', fmt=None, gen=None):
     """Wrap data to support both dict-like and string-like operations"""
     prefmt = pycompat.identity
     if fmt is None:
         fmt = '%s=%s'
         prefmt = pycompat.bytestr
     return hybrid(gen, data, lambda k: {key: k, value: data[k]},
                   lambda k: fmt % (prefmt(k), prefmt(data[k])))
 
 def hybridlist(data, name, fmt=None, gen=None):
     """Wrap data to support both list-like and string-like operations"""
     prefmt = pycompat.identity
     if fmt is None:
         fmt = '%s'
         prefmt = pycompat.bytestr
     return hybrid(gen, data, lambda x: {name: x}, lambda x: fmt % prefmt(x))
 
 def unwraphybrid(context, mapping, thing):
     """Return an object which can be stringified possibly by using a legacy
     template"""
     if not isinstance(thing, wrapped):
         return thing
     return thing.show(context, mapping)
 
 def unwrapvalue(context, mapping, thing):
     """Move the inner value object out of the wrapper"""
     if not isinstance(thing, wrapped):
         return thing
     return thing.tovalue(context, mapping)
 
 def wraphybridvalue(container, key, value):
     """Wrap an element of hybrid container to be mappable
 
     The key is passed to the makemap function of the given container, which
     should be an item generated by iter(container).
     """
     makemap = getattr(container, '_makemap', None)
     if makemap is None:
         return value
     if util.safehasattr(value, '_makemap'):
         # a nested hybrid list/dict, which has its own way of map operation
         return value
     return mappable(None, key, value, makemap)
 
 def compatdict(context, mapping, name, data, key='key', value='value',
                fmt=None, plural=None, separator=' '):
     """Wrap data like hybriddict(), but also supports old-style list template
 
     This exists for backward compatibility with the old-style template. Use
     hybriddict() for new template keywords.
     """
     c = [{key: k, value: v} for k, v in data.iteritems()]
     f = _showcompatlist(context, mapping, name, c, plural, separator)
     return hybriddict(data, key=key, value=value, fmt=fmt, gen=f)
 
 def compatlist(context, mapping, name, data, element=None, fmt=None,
                plural=None, separator=' '):
     """Wrap data like hybridlist(), but also supports old-style list template
 
     This exists for backward compatibility with the old-style template. Use
     hybridlist() for new template keywords.
     """
     f = _showcompatlist(context, mapping, name, data, plural, separator)
     return hybridlist(data, name=element or name, fmt=fmt, gen=f)
 
 def _showcompatlist(context, mapping, name, values, plural=None, separator=' '):
     """Return a generator that renders old-style list template
 
     name is name of key in template map.
     values is list of strings or dicts.
     plural is plural of name, if not simply name + 's'.
     separator is used to join values as a string
 
     expansion works like this, given name 'foo'.
 
     if values is empty, expand 'no_foos'.
 
     if 'foo' not in template map, return values as a string,
     joined by 'separator'.
 
     expand 'start_foos'.
 
     for each value, expand 'foo'. if 'last_foo' in template
     map, expand it instead of 'foo' for last key.
 
     expand 'end_foos'.
     """
     if not plural:
         plural = name + 's'
     if not values:
         noname = 'no_' + plural
         if context.preload(noname):
             yield context.process(noname, mapping)
         return
     if not context.preload(name):
         if isinstance(values[0], bytes):
             yield separator.join(values)
         else:
             for v in values:
                 r = dict(v)
                 r.update(mapping)
                 yield r
         return
     startname = 'start_' + plural
     if context.preload(startname):
         yield context.process(startname, mapping)
     def one(v, tag=name):
         vmapping = {}
         try:
             vmapping.update(v)
         # Python 2 raises ValueError if the type of v is wrong. Python
         # 3 raises TypeError.
         except (AttributeError, TypeError, ValueError):
             try:
                 # Python 2 raises ValueError trying to destructure an e.g.
                 # bytes. Python 3 raises TypeError.
                 for a, b in v:
                     vmapping[a] = b
             except (TypeError, ValueError):
                 vmapping[name] = v
         vmapping = context.overlaymap(mapping, vmapping)
         return context.process(tag, vmapping)
     lastname = 'last_' + name
     if context.preload(lastname):
         last = values.pop()
     else:
         last = None
     for v in values:
         yield one(v)
     if last is not None:
         yield one(last, tag=lastname)
     endname = 'end_' + plural
     if context.preload(endname):
         yield context.process(endname, mapping)
 
 def flatten(context, mapping, thing):
     """Yield a single stream from a possibly nested set of iterators"""
     thing = unwraphybrid(context, mapping, thing)
     if isinstance(thing, bytes):
         yield thing
     elif isinstance(thing, str):
         # We can only hit this on Python 3, and it's here to guard
         # against infinite recursion.
         raise error.ProgrammingError('Mercurial IO including templates is done'
                                      ' with bytes, not strings, got %r' % thing)
     elif thing is None:
         pass
     elif not util.safehasattr(thing, '__iter__'):
         yield pycompat.bytestr(thing)
     else:
         for i in thing:
             i = unwraphybrid(context, mapping, i)
             if isinstance(i, bytes):
                 yield i
             elif i is None:
                 pass
             elif not util.safehasattr(i, '__iter__'):
                 yield pycompat.bytestr(i)
             else:
                 for j in flatten(context, mapping, i):
                     yield j
 
 def stringify(context, mapping, thing):
     """Turn values into bytes by converting into text and concatenating them"""
     if isinstance(thing, bytes):
         return thing  # retain localstr to be round-tripped
     return b''.join(flatten(context, mapping, thing))
 
 def findsymbolicname(arg):
     """Find symbolic name for the given compiled expression; returns None
     if nothing found reliably"""
     while True:
         func, data = arg
         if func is runsymbol:
             return data
         elif func is runfilter:
             arg = data[0]
         else:
             return None
 
 def _unthunk(context, mapping, thing):
     """Evaluate a lazy byte string into value"""
     if not isinstance(thing, types.GeneratorType):
         return thing
     return stringify(context, mapping, thing)
 
 def evalrawexp(context, mapping, arg):
     """Evaluate given argument as a bare template object which may require
     further processing (such as folding generator of strings)"""
     func, data = arg
     return func(context, mapping, data)
 
 def evalfuncarg(context, mapping, arg):
     """Evaluate given argument as value type"""
     return _unwrapvalue(context, mapping, evalrawexp(context, mapping, arg))
 
 # TODO: unify this with unwrapvalue() once the bug of templatefunc.join()
 # is fixed. we can't do that right now because join() has to take a generator
 # of byte strings as it is, not a lazy byte string.
 def _unwrapvalue(context, mapping, thing):
     thing = unwrapvalue(context, mapping, thing)
     # evalrawexp() may return string, generator of strings or arbitrary object
     # such as date tuple, but filter does not want generator.
     return _unthunk(context, mapping, thing)
 
 def evalboolean(context, mapping, arg):
     """Evaluate given argument as boolean, but also takes boolean literals"""
     func, data = arg
     if func is runsymbol:
         thing = func(context, mapping, data, default=None)
         if thing is None:
             # not a template keyword, takes as a boolean literal
             thing = stringutil.parsebool(data)
     else:
         thing = func(context, mapping, data)
     thing = unwrapvalue(context, mapping, thing)
     if isinstance(thing, bool):
         return thing
     # other objects are evaluated as strings, which means 0 is True, but
     # empty dict/list should be False as they are expected to be ''
     return bool(stringify(context, mapping, thing))
 
 def evaldate(context, mapping, arg, err=None):
     """Evaluate given argument as a date tuple or a date string; returns
     a (unixtime, offset) tuple"""
     thing = evalrawexp(context, mapping, arg)
     return unwrapdate(context, mapping, thing, err)
 
 def unwrapdate(context, mapping, thing, err=None):
     thing = _unwrapvalue(context, mapping, thing)
     try:
         return dateutil.parsedate(thing)
     except AttributeError:
         raise error.ParseError(err or _('not a date tuple nor a string'))
     except error.ParseError:
         if not err:
             raise
         raise error.ParseError(err)
 
 def evalinteger(context, mapping, arg, err=None):
     thing = evalrawexp(context, mapping, arg)
     return unwrapinteger(context, mapping, thing, err)
 
 def unwrapinteger(context, mapping, thing, err=None):
     thing = _unwrapvalue(context, mapping, thing)
     try:
         return int(thing)
     except (TypeError, ValueError):
         raise error.ParseError(err or _('not an integer'))
 
 def evalstring(context, mapping, arg):
     return stringify(context, mapping, evalrawexp(context, mapping, arg))
 
 def evalstringliteral(context, mapping, arg):
     """Evaluate given argument as string template, but returns symbol name
     if it is unknown"""
     func, data = arg
     if func is runsymbol:
         thing = func(context, mapping, data, default=data)
     else:
         thing = func(context, mapping, data)
     return stringify(context, mapping, thing)
 
 _unwrapfuncbytype = {
     None: _unwrapvalue,
     bytes: stringify,
     date: unwrapdate,
     int: unwrapinteger,
 }
 
 def unwrapastype(context, mapping, thing, typ):
     """Move the inner value object out of the wrapper and coerce its type"""
     try:
         f = _unwrapfuncbytype[typ]
     except KeyError:
         raise error.ProgrammingError('invalid type specified: %r' % typ)
     return f(context, mapping, thing)
 
 def runinteger(context, mapping, data):
     return int(data)
 
 def runstring(context, mapping, data):
     return data
 
 def _recursivesymbolblocker(key):
     def showrecursion(**args):
         raise error.Abort(_("recursive reference '%s' in template") % key)
     return showrecursion
 
 def runsymbol(context, mapping, key, default=''):
     v = context.symbol(mapping, key)
     if v is None:
         # put poison to cut recursion. we can't move this to parsing phase
         # because "x = {x}" is allowed if "x" is a keyword. (issue4758)
         safemapping = mapping.copy()
         safemapping[key] = _recursivesymbolblocker(key)
         try:
             v = context.process(key, safemapping)
         except TemplateNotFound:
             v = default
     if callable(v) and getattr(v, '_requires', None) is None:
         # old templatekw: expand all keywords and resources
         # (TODO: deprecate this after porting web template keywords to new API)
         props = {k: context._resources.lookup(context, mapping, k)
                  for k in context._resources.knownkeys()}
         # pass context to _showcompatlist() through templatekw._showlist()
         props['templ'] = context
         props.update(mapping)
         return v(**pycompat.strkwargs(props))
     if callable(v):
         # new templatekw
         try:
             return v(context, mapping)
         except ResourceUnavailable:
             # unsupported keyword is mapped to empty just like unknown keyword
             return None
     return v
 
 def runtemplate(context, mapping, template):
     for arg in template:
         yield evalrawexp(context, mapping, arg)
 
 def runfilter(context, mapping, data):
     arg, filt = data
     thing = evalrawexp(context, mapping, arg)
     intype = getattr(filt, '_intype', None)
     try:
         thing = unwrapastype(context, mapping, thing, intype)
         return filt(thing)
     except error.ParseError as e:
         raise error.ParseError(bytes(e), hint=_formatfiltererror(arg, filt))
 
 def _formatfiltererror(arg, filt):
     fn = pycompat.sysbytes(filt.__name__)
     sym = findsymbolicname(arg)
     if not sym:
         return _("incompatible use of template filter '%s'") % fn
     return (_("template filter '%s' is not compatible with keyword '%s'")
             % (fn, sym))
 
 def runmap(context, mapping, data):
     darg, targ = data
     d = evalrawexp(context, mapping, darg)
     if isinstance(d, wrapped):
         diter = d.itermaps(context)
     else:
         try:
             diter = iter(d)
         except TypeError:
             sym = findsymbolicname(darg)
             if sym:
                 raise error.ParseError(_("keyword '%s' is not iterable") % sym)
             else:
                 raise error.ParseError(_("%r is not iterable") % d)
 
     for i, v in enumerate(diter):
         if isinstance(v, dict):
             lm = context.overlaymap(mapping, v)
             lm['index'] = i
             yield evalrawexp(context, lm, targ)
         else:
             # v is not an iterable of dicts, this happen when 'key'
             # has been fully expanded already and format is useless.
             # If so, return the expanded value.
             yield v
 
 def runmember(context, mapping, data):
     darg, memb = data
     d = evalrawexp(context, mapping, darg)
     if util.safehasattr(d, 'tomap'):
         lm = context.overlaymap(mapping, d.tomap())
         return runsymbol(context, lm, memb)
     if util.safehasattr(d, 'get'):
         return getdictitem(d, memb)
 
     sym = findsymbolicname(darg)
     if sym:
         raise error.ParseError(_("keyword '%s' has no member") % sym)
     else:
         raise error.ParseError(_("%r has no member") % pycompat.bytestr(d))
 
 def runnegate(context, mapping, data):
     data = evalinteger(context, mapping, data,
                        _('negation needs an integer argument'))
     return -data
 
 def runarithmetic(context, mapping, data):
     func, left, right = data
     left = evalinteger(context, mapping, left,
                        _('arithmetic only defined on integers'))
     right = evalinteger(context, mapping, right,
                         _('arithmetic only defined on integers'))
     try:
         return func(left, right)
     except ZeroDivisionError:
         raise error.Abort(_('division by zero is not defined'))
 
 def getdictitem(dictarg, key):
     val = dictarg.get(key)
     if val is None:
         return
     return wraphybridvalue(dictarg, key, val)
 
 def joinitems(itemiter, sep):
     """Join items with the separator; Returns generator of bytes"""
     first = True
     for x in itemiter:
         if first:
             first = False
         elif sep:
             yield sep
         yield x