templater: add hex filter.

mercurial/help/templates.txt

@@ -1,156 +1,159 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 hexadecimal
     digit 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.
 
+:hex: Any text. Convert a binary Mercurial node identifier into
+    its long hexadecimal representation.
+
 :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 hexadecimal digit string.
 
 :shortdate: Date. Returns a date like "2006-09-18".
 
 :stringify: Any type. Turns the value into text by converting values into
     text and concatenating them.
 
 :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/templatefilters.py

@@ -1,227 +1,228 b''
 # template-filters.py - common template expansion filters
 #
 # Copyright 2005-2008 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.
 
 import cgi, re, os, time, urllib
-import util, encoding
+import encoding, node, util
 
 def stringify(thing):
     '''turn nested template iterator into string.'''
     if hasattr(thing, '__iter__') and not isinstance(thing, str):
         return "".join([stringify(t) for t in thing if t is not None])
     return str(thing)
 
 agescales = [("year", 3600 * 24 * 365),
              ("month", 3600 * 24 * 30),
              ("week", 3600 * 24 * 7),
              ("day", 3600 * 24),
              ("hour", 3600),
              ("minute", 60),
              ("second", 1)]
 
 def age(date):
     '''turn a (timestamp, tzoff) tuple into an age string.'''
 
     def plural(t, c):
         if c == 1:
             return t
         return t + "s"
     def fmt(t, c):
         return "%d %s" % (c, plural(t, c))
 
     now = time.time()
     then = date[0]
     if then > now:
         return 'in the future'
 
     delta = max(1, int(now - then))
     if delta > agescales[0][1] * 2:
         return util.shortdate(date)
 
     for t, s in agescales:
         n = delta // s
         if n >= 2 or s == 1:
             return '%s ago' % fmt(t, n)
 
 para_re = None
 space_re = None
 
 def fill(text, width):
     '''fill many paragraphs.'''
     global para_re, space_re
     if para_re is None:
         para_re = re.compile('(\n\n|\n\\s*[-*]\\s*)', re.M)
         space_re = re.compile(r'  +')
 
     def findparas():
         start = 0
         while True:
             m = para_re.search(text, start)
             if not m:
                 uctext = unicode(text[start:], encoding.encoding)
                 w = len(uctext)
                 while 0 < w and uctext[w - 1].isspace():
                     w -= 1
                 yield (uctext[:w].encode(encoding.encoding),
                        uctext[w:].encode(encoding.encoding))
                 break
             yield text[start:m.start(0)], m.group(1)
             start = m.end(1)
 
     return "".join([space_re.sub(' ', util.wrap(para, width=width)) + rest
                     for para, rest in findparas()])
 
 def firstline(text):
     '''return the first line of text'''
     try:
         return text.splitlines(True)[0].rstrip('\r\n')
     except IndexError:
         return ''
 
 def nl2br(text):
     '''replace raw newlines with xhtml line breaks.'''
     return text.replace('\n', '<br/>\n')
 
 def obfuscate(text):
     text = unicode(text, encoding.encoding, 'replace')
     return ''.join(['&#%d;' % ord(c) for c in text])
 
 def domain(author):
     '''get domain of author, or empty string if none.'''
     f = author.find('@')
     if f == -1:
         return ''
     author = author[f + 1:]
     f = author.find('>')
     if f >= 0:
         author = author[:f]
     return author
 
 def person(author):
     '''get name of author, or else username.'''
     if not '@' in author:
         return author
     f = author.find('<')
     if f == -1:
         return util.shortuser(author)
     return author[:f].rstrip()
 
 def indent(text, prefix):
     '''indent each non-empty line of text after first with prefix.'''
     lines = text.splitlines()
     num_lines = len(lines)
     endswithnewline = text[-1:] == '\n'
     def indenter():
         for i in xrange(num_lines):
             l = lines[i]
             if i and l.strip():
                 yield prefix
             yield l
             if i < num_lines - 1 or endswithnewline:
                 yield '\n'
     return "".join(indenter())
 
 def permissions(flags):
     if "l" in flags:
         return "lrwxrwxrwx"
     if "x" in flags:
         return "-rwxr-xr-x"
     return "-rw-r--r--"
 
 def xmlescape(text):
     text = (text
             .replace('&', '&amp;')
             .replace('<', '&lt;')
             .replace('>', '&gt;')
             .replace('"', '&quot;')
             .replace("'", '&#39;')) # &apos; invalid in HTML
     return re.sub('[\x00-\x08\x0B\x0C\x0E-\x1F]', ' ', text)
 
 def uescape(c):
     if ord(c) < 0x80:
         return c
     else:
         return '\\u%04x' % ord(c)
 
 _escapes = [
     ('\\', '\\\\'), ('"', '\\"'), ('\t', '\\t'), ('\n', '\\n'),
     ('\r', '\\r'), ('\f', '\\f'), ('\b', '\\b'),
 ]
 
 def jsonescape(s):
     for k, v in _escapes:
         s = s.replace(k, v)
     return ''.join(uescape(c) for c in s)
 
 def json(obj):
     if obj is None or obj is False or obj is True:
         return {None: 'null', False: 'false', True: 'true'}[obj]
     elif isinstance(obj, int) or isinstance(obj, float):
         return str(obj)
     elif isinstance(obj, str):
         u = unicode(obj, encoding.encoding, 'replace')
         return '"%s"' % jsonescape(u)
     elif isinstance(obj, unicode):
         return '"%s"' % jsonescape(obj)
     elif hasattr(obj, 'keys'):
         out = []
         for k, v in obj.iteritems():
             s = '%s: %s' % (json(k), json(v))
             out.append(s)
         return '{' + ', '.join(out) + '}'
     elif hasattr(obj, '__iter__'):
         out = []
         for i in obj:
             out.append(json(i))
         return '[' + ', '.join(out) + ']'
     else:
         raise TypeError('cannot encode type %s' % obj.__class__.__name__)
 
 def stripdir(text):
     '''Treat the text as path and strip a directory level, if possible.'''
     dir = os.path.dirname(text)
     if dir == "":
         return os.path.basename(text)
     else:
         return dir
 
 def nonempty(str):
     return str or "(none)"
 
 filters = {
     "addbreaks": nl2br,
     "basename": os.path.basename,
     "stripdir": stripdir,
     "age": age,
     "date": lambda x: util.datestr(x),
     "domain": domain,
     "email": util.email,
     "escape": lambda x: cgi.escape(x, True),
     "fill68": lambda x: fill(x, width=68),
     "fill76": lambda x: fill(x, width=76),
     "firstline": firstline,
     "tabindent": lambda x: indent(x, '\t'),
     "hgdate": lambda x: "%d %d" % x,
     "isodate": lambda x: util.datestr(x, '%Y-%m-%d %H:%M %1%2'),
     "isodatesec": lambda x: util.datestr(x, '%Y-%m-%d %H:%M:%S %1%2'),
     "json": json,
     "jsonescape": jsonescape,
     "localdate": lambda x: (x[0], util.makedate()[1]),
     "nonempty": nonempty,
     "obfuscate": obfuscate,
     "permissions": permissions,
     "person": person,
     "rfc822date": lambda x: util.datestr(x, "%a, %d %b %Y %H:%M:%S %1%2"),
     "rfc3339date": lambda x: util.datestr(x, "%Y-%m-%dT%H:%M:%S%1:%2"),
+    "hex": node.hex,
     "short": lambda x: x[:12],
     "shortdate": util.shortdate,
     "stringify": stringify,
     "strip": lambda x: x.strip(),
     "urlescape": lambda x: urllib.quote(x),
     "user": lambda x: util.shortuser(x),
     "stringescape": lambda x: x.encode('string_escape'),
     "xmlescape": xmlescape,
 }