add doc comments to template code.
--- a/mercurial/commands.py Mon Feb 27 13:25:40 2006 -0800
+++ b/mercurial/commands.py Mon Feb 27 15:07:25 2006 -0800
@@ -338,15 +338,20 @@
return user
class changeset_templater(object):
+ '''use templater module to format changeset information.'''
+
def __init__(self, ui, repo, mapfile):
self.t = templater.templater(mapfile, templater.common_filters)
self.ui = ui
self.repo = repo
def use_template(self, t):
+ '''set template string to use'''
self.t.cache['template'] = t
def write(self, thing):
+ '''write expanded template.
+ uses in-order recursive traverse of iterators.'''
for t in thing:
if hasattr(t, '__iter__'):
self.write(t)
@@ -354,7 +359,7 @@
self.ui.write(t)
def show(self, rev=0, changenode=None, brinfo=None):
- """show a single changeset or file revision"""
+ '''show a single changeset or file revision'''
log = self.repo.changelog
if changenode is None:
changenode = log.node(rev)
@@ -364,6 +369,25 @@
changes = log.read(changenode)
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'.
+ '''
if plural: names = plural
else: names = name + 's'
if not values:
@@ -371,13 +395,13 @@
if noname in self.t:
yield self.t(noname, **args)
return
- vargs = args.copy()
if name not in self.t:
yield ' '.join(values)
return
startname = 'start_' + names
if startname in self.t:
yield self.t(startname, **args)
+ vargs = args.copy()
def one(v, tag=name):
try:
vargs.update(v)
@@ -464,12 +488,14 @@
raise util.Abort(_('%s: %s') % (self.t.mapfile, inst.args[0]))
class changeset_printer(object):
+ '''show changeset information when templating not requested.'''
+
def __init__(self, ui, repo):
self.ui = ui
self.repo = repo
def show(self, rev=0, changenode=None, brinfo=None):
- """show a single changeset or file revision"""
+ '''show a single changeset or file revision'''
log = self.repo.changelog
if changenode is None:
changenode = log.node(rev)
@@ -530,6 +556,9 @@
self.ui.status("\n")
def show_changeset(ui, repo, opts):
+ '''show one changeset. uses template or regular display. caller
+ can pass in 'map_file' and 'template' options in opts.'''
+
tmpl = opts.get('template')
if tmpl:
tmpl = templater.parsestring(tmpl, quoted=False)
--- a/mercurial/templater.py Mon Feb 27 13:25:40 2006 -0800
+++ b/mercurial/templater.py Mon Feb 27 15:07:25 2006 -0800
@@ -1,3 +1,10 @@
+# templater.py - template expansion for output
+#
+# Copyright 2005, 2006 Matt Mackall <mpm@selenic.com>
+#
+# This software may be used and distributed according to the terms
+# of the GNU General Public License, incorporated herein by reference.
+
import re
from demandload import demandload
from i18n import gettext as _
@@ -12,6 +19,8 @@
}
def parsestring(s, quoted=True):
+ '''parse a string using simple c-like syntax.
+ string must be in quotes if quoted is True.'''
fp = cStringIO.StringIO()
if quoted:
first = s[0]
@@ -31,7 +40,30 @@
return fp.getvalue()
class templater(object):
+ '''template expansion engine.
+
+ template expansion works like this. a map file contains key=value
+ pairs. if value is quoted, it is treated as string. otherwise, it
+ is treated as name of template file.
+
+ templater is asked to expand a key in map. it looks up key, and
+ looks for atrings like this: {foo}. it expands {foo} by looking up
+ foo in map, and substituting it. expansion is recursive: it stops
+ when there is no more {foo} to replace.
+
+ expansion also allows formatting and filtering.
+
+ format uses key to expand each item in list. syntax is
+ {key%format}.
+
+ filter uses function to transform value. syntax is
+ {key|filter1|filter2|...}.'''
+
def __init__(self, mapfile, filters={}, defaults={}):
+ '''set up template engine.
+ mapfile is name of file to read map definitions from.
+ filters is dict of functions. each transforms a value into another.
+ defaults is dict of default map definitions.'''
self.mapfile = mapfile or 'template'
self.cache = {}
self.map = {}
@@ -64,6 +96,9 @@
return key in self.cache
def __call__(self, t, **map):
+ '''perform expansion.
+ t is name of map element to expand.
+ map is added elements to use during expansion.'''
m = self.defaults.copy()
m.update(map)
try:
@@ -127,7 +162,9 @@
agescales.reverse()
-def age(x):
+def age(date):
+ '''turn a (timestamp, tzoff) tuple into an age string.'''
+
def plural(t, c):
if c == 1:
return t
@@ -136,7 +173,7 @@
return "%d %s" % (c, plural(t, c))
now = time.time()
- then = x[0]
+ then = date[0]
delta = max(1, int(now - then))
for t, s in agescales:
@@ -145,15 +182,18 @@
return fmt(t, n)
def isodate(date):
+ '''turn a (timestamp, tzoff) tuple into an iso 8631 date.'''
return util.datestr(date, format='%Y-%m-%d %H:%M')
def nl2br(text):
+ '''replace raw newlines with xhtml line breaks.'''
return text.replace('\n', '<br/>\n')
def obfuscate(text):
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:]
@@ -162,6 +202,7 @@
return author
def person(author):
+ '''get name of author, or else username.'''
f = author.find('<')
if f == -1: return util.shortuser(author)
return author[:f].rstrip()
@@ -185,6 +226,8 @@
}
def templatepath(name=None):
+ '''return location of template file or directory (if no name).
+ returns None if not found.'''
for f in 'templates', '../templates':
fl = f.split('/')
if name: fl.append(name)