templates: 'children' keyword

The template keyword 'parents' is already present and this just
provides the complimentary template keyword.

mercurial/help/templates.txt

@@ -1,151 +1,153 b''
 Mercurial allows you to customize output of commands through
 templates. You can either pass in a template from the command
 line, via the --template option, or select an existing
 template-style (--style).
 
 You can customize output for any "log-like" command: log,
 outgoing, incoming, tip, parents, heads and glog.
 
 Four styles are packaged with Mercurial: default (the style used
 when no explicit preference is passed), compact, changelog,
 and xml.
 Usage::
 
     $ hg log -r1 --style changelog
 
 A template is a piece of text, with markup to invoke variable
 expansion::
 
     $ hg log -r1 --template "{node}\n"
     b56ce7b07c52de7d5fd79fb89701ea538af65746
 
 Strings in curly braces are called keywords. The availability of
 keywords depends on the exact context of the templater. These
 keywords are usually available for templating a log-like command:
 
 :author: String. The unmodified author of the changeset.
 
 :branches: String. The name of the branch on which the changeset was
     committed. Will be empty if the branch name was default.
 
+:children: List of strings. The children of the changeset.
+
 :date: Date information. The date when the changeset was committed.
 
 :desc: String. The text of the changeset description.
 
 :diffstat: String. Statistics of changes with the following format:
     "modified files: +added/-removed lines"
 
 :files: List of strings. All files modified, added, or removed by this
     changeset.
 
 :file_adds: List of strings. Files added by this changeset.
 
 :file_copies: List of strings. Files copied in this changeset with
     their sources.
 
 :file_copies_switch: List of strings. Like "file_copies" but displayed
     only if the --copied switch is set.
 
 :file_mods: List of strings. Files modified by this changeset.
 
 :file_dels: List of strings. Files removed by this changeset.
 
 :node: String. The changeset identification hash, as a 40-character
     hexadecimal string.
 
 :parents: List of strings. The parents of the changeset.
 
 :rev: Integer. The repository-local changeset revision number.
 
 :tags: List of strings. Any tags associated with the changeset.
 
 :latesttag: String. Most recent global tag in the ancestors of this
     changeset.
 
 :latesttagdistance: Integer. Longest path to the latest tag.
 
 The "date" keyword does not produce human-readable output. If you
 want to use a date in your output, you can use a filter to process
 it. Filters are functions which return a string based on the input
 variable. Be sure to use the stringify filter first when you're
 applying a string-input filter to a list-like input variable.
 You can also use a chain of filters to get the desired output::
 
    $ hg tip --template "{date|isodate}\n"
    2008-08-21 18:22 +0000
 
 List of filters:
 
 :addbreaks: Any text. Add an XHTML "<br />" tag before the end of
     every line except the last.
 
 :age: Date. Returns a human-readable date/time difference between the
     given date/time and the current date/time.
 
 :basename: Any text. Treats the text as a path, and returns the last
     component of the path after splitting by the path separator
     (ignoring trailing separators). For example, "foo/bar/baz" becomes
     "baz" and "foo/bar//" becomes "bar".
 
 :stripdir: Treat the text as path and strip a directory level, if
     possible. For example, "foo" and "foo/bar" becomes "foo".
 
 :date: Date. Returns a date in a Unix date format, including the
     timezone: "Mon Sep 04 15:13:13 2006 0700".
 
 :domain: Any text. Finds the first string that looks like an email
     address, and extracts just the domain component. Example: ``User
     <[e-mail]>`` becomes ``example.com``.
 
 :email: Any text. Extracts the first string that looks like an email
     address. Example: ``User <[e-mail]>`` becomes
     ``[e-mail]``.
 
 :escape: Any text. Replaces the special XML/XHTML characters "&", "<"
     and ">" with XML entities.
 
 :fill68: Any text. Wraps the text to fit in 68 columns.
 
 :fill76: Any text. Wraps the text to fit in 76 columns.
 
 :firstline: Any text. Returns the first line of text.
 
 :nonempty: Any text. Returns '(none)' if the string is empty.
 
 :hgdate: Date. Returns the date as a pair of numbers: "1157407993
     25200" (Unix timestamp, timezone offset).
 
 :isodate: Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
     +0200".
 
 :isodatesec: Date. Returns the date in ISO 8601 format, including
     seconds: "2009-08-18 13:00:13 +0200". See also the rfc3339date
     filter.
 
 :localdate: Date. Converts a date to local date.
 
 :obfuscate: Any text. Returns the input text rendered as a sequence of
     XML entities.
 
 :person: Any text. Returns the text before an email address.
 
 :rfc822date: Date. Returns a date using the same format used in email
     headers: "Tue, 18 Aug 2009 13:00:13 +0200".
 
 :rfc3339date: Date. Returns a date using the Internet date format
     specified in RFC 3339: "2009-08-18T13:00:13+02:00".
 
 :short: Changeset hash. Returns the short form of a changeset hash,
     i.e. a 12-byte hexadecimal string.
 
 :shortdate: Date. Returns a date like "2006-09-18".
 
 :strip: Any text. Strips all leading and trailing whitespace.
 
 :tabindent: Any text. Returns the text, with every line except the
      first starting with a tab character.
 
 :urlescape: Any text. Escapes all "special" characters. For example,
     "foo bar" becomes "foo%20bar".
 
 :user: Any text. Returns the user portion of an email address.

mercurial/templatekw.py

@@ -1,265 +1,271 b''
 # templatekw.py - common changeset template keywords
 #
 # Copyright 2005-2009 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 node import hex
 import encoding, patch, util, error
 
 def showlist(name, values, plural=None, **args):
     '''expand set of values.
     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'.
 
     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 space.
 
     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'.
     '''
     templ = args['templ']
     if plural:
         names = plural
     else: names = name + 's'
     if not values:
         noname = 'no_' + names
         if noname in templ:
             yield templ(noname, **args)
         return
     if name not in templ:
         if isinstance(values[0], str):
             yield ' '.join(values)
         else:
             for v in values:
                 yield dict(v, **args)
         return
     startname = 'start_' + names
     if startname in templ:
         yield templ(startname, **args)
     vargs = args.copy()
     def one(v, tag=name):
         try:
             vargs.update(v)
         except (AttributeError, ValueError):
             try:
                 for a, b in v:
                     vargs[a] = b
             except ValueError:
                 vargs[name] = v
         return templ(tag, **vargs)
     lastname = 'last_' + name
     if lastname in templ:
         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_' + names
     if endname in templ:
         yield templ(endname, **args)
 
 def getfiles(repo, ctx, revcache):
     if 'files' not in revcache:
         revcache['files'] = repo.status(ctx.parents()[0].node(),
                                         ctx.node())[:3]
     return revcache['files']
 
 def getlatesttags(repo, ctx, cache):
     '''return date, distance and name for the latest tag of rev'''
 
     if 'latesttags' not in cache:
         # Cache mapping from rev to a tuple with tag date, tag
         # distance and tag name
         cache['latesttags'] = {-1: (0, 0, 'null')}
     latesttags = cache['latesttags']
 
     rev = ctx.rev()
     todo = [rev]
     while todo:
         rev = todo.pop()
         if rev in latesttags:
             continue
         ctx = repo[rev]
         tags = [t for t in ctx.tags() if repo.tagtype(t) == 'global']
         if tags:
             latesttags[rev] = ctx.date()[0], 0, ':'.join(sorted(tags))
             continue
         try:
             # The tuples are laid out so the right one can be found by
             # comparison.
             pdate, pdist, ptag = max(
                 latesttags[p.rev()] for p in ctx.parents())
         except KeyError:
             # Cache miss - recurse
             todo.append(rev)
             todo.extend(p.rev() for p in ctx.parents())
             continue
         latesttags[rev] = pdate, pdist + 1, ptag
     return latesttags[rev]
 
 def getrenamedfn(repo, endrev=None):
     rcache = {}
     if endrev is None:
         endrev = len(repo)
 
     def getrenamed(fn, rev):
         '''looks up all renames for a file (up to endrev) the first
         time the file is given. It indexes on the changerev and only
         parses the manifest if linkrev != changerev.
         Returns rename info for fn at changerev rev.'''
         if fn not in rcache:
             rcache[fn] = {}
             fl = repo.file(fn)
             for i in fl:
                 lr = fl.linkrev(i)
                 renamed = fl.renamed(fl.node(i))
                 rcache[fn][lr] = renamed
                 if lr >= endrev:
                     break
         if rev in rcache[fn]:
             return rcache[fn][rev]
 
         # If linkrev != rev (i.e. rev not found in rcache) fallback to
         # filectx logic.
         try:
             return repo[rev][fn].renamed()
         except error.LookupError:
             return None
 
     return getrenamed
 
 
 def showauthor(repo, ctx, templ, **args):
     return ctx.user()
 
 def showbranches(**args):
     branch = args['ctx'].branch()
     if branch != 'default':
         branch = encoding.tolocal(branch)
         return showlist('branch', [branch], plural='branches', **args)
 
+def showchildren(**args):
+    ctx = args['ctx']
+    childrevs = ['%d:%s' % (cctx, cctx) for cctx in ctx.children()]
+    return showlist('children', childrevs, **args)
+
 def showdate(repo, ctx, templ, **args):
     return ctx.date()
 
 def showdescription(repo, ctx, templ, **args):
     return ctx.description().strip()
 
 def showdiffstat(repo, ctx, templ, **args):
     diff = patch.diff(repo, ctx.parents()[0].node(), ctx.node())
     files, adds, removes = 0, 0, 0
     for i in patch.diffstatdata(util.iterlines(diff)):
         files += 1
         adds += i[1]
         removes += i[2]
     return '%s: +%s/-%s' % (files, adds, removes)
 
 def showextras(**args):
     templ = args['templ']
     for key, value in sorted(args['ctx'].extra().items()):
         args = args.copy()
         args.update(dict(key=key, value=value))
         yield templ('extra', **args)
 
 def showfileadds(**args):
     repo, ctx, revcache = args['repo'], args['ctx'], args['revcache']
     return showlist('file_add', getfiles(repo, ctx, revcache)[1], **args)
 
 def showfilecopies(**args):
     cache, ctx = args['cache'], args['ctx']
     copies = args['revcache'].get('copies')
     if copies is None:
         if 'getrenamed' not in cache:
             cache['getrenamed'] = getrenamedfn(args['repo'])
         copies = []
         getrenamed = cache['getrenamed']
         for fn in ctx.files():
             rename = getrenamed(fn, ctx.rev())
             if rename:
                 copies.append((fn, rename[0]))
 
     c = [{'name': x[0], 'source': x[1]} for x in copies]
     return showlist('file_copy', c, plural='file_copies', **args)
 
 # showfilecopiesswitch() displays file copies only if copy records are
 # provided before calling the templater, usually with a --copies
 # command line switch.
 def showfilecopiesswitch(**args):
     copies = args['revcache'].get('copies') or []
     c = [{'name': x[0], 'source': x[1]} for x in copies]
     return showlist('file_copy', c, plural='file_copies', **args)
 
 def showfiledels(**args):
     repo, ctx, revcache = args['repo'], args['ctx'], args['revcache']
     return showlist('file_del', getfiles(repo, ctx, revcache)[2], **args)
 
 def showfilemods(**args):
     repo, ctx, revcache = args['repo'], args['ctx'], args['revcache']
     return showlist('file_mod', getfiles(repo, ctx, revcache)[0], **args)
 
 def showfiles(**args):
     return showlist('file', args['ctx'].files(), **args)
 
 def showlatesttag(repo, ctx, templ, cache, **args):
     return getlatesttags(repo, ctx, cache)[2]
 
 def showlatesttagdistance(repo, ctx, templ, cache, **args):
     return getlatesttags(repo, ctx, cache)[1]
 
 def showmanifest(**args):
     repo, ctx, templ = args['repo'], args['ctx'], args['templ']
     args = args.copy()
     args.update(dict(rev=repo.manifest.rev(ctx.changeset()[0]),
                      node=hex(ctx.changeset()[0])))
     return templ('manifest', **args)
 
 def shownode(repo, ctx, templ, **args):
     return ctx.hex()
 
 def showrev(repo, ctx, templ, **args):
     return ctx.rev()
 
 def showtags(**args):
     return showlist('tag', args['ctx'].tags(), **args)
 
 # keywords are callables like:
 # fn(repo, ctx, templ, cache, revcache, **args)
 # with:
 # repo - current repository instance
 # ctx - the changectx being displayed
 # templ - the templater instance
 # cache - a cache dictionary for the whole templater run
 # revcache - a cache dictionary for the current revision
 keywords = {
     'author': showauthor,
     'branches': showbranches,
+    'children': showchildren,
     'date': showdate,
     'desc': showdescription,
     'diffstat': showdiffstat,
     'extras': showextras,
     'file_adds': showfileadds,
     'file_copies': showfilecopies,
     'file_copies_switch': showfilecopiesswitch,
     'file_dels': showfiledels,
     'file_mods': showfilemods,
     'files': showfiles,
     'latesttag': showlatesttag,
     'latesttagdistance': showlatesttagdistance,
     'manifest': showmanifest,
     'node': shownode,
     'rev': showrev,
     'tags': showtags,
 }