formatter.py
490 lines
| 16.7 KiB
| text/x-python
|
PythonLexer
/ mercurial / formatter.py
|
r16134 | # formatter.py - generic output formatting for mercurial | ||
# | ||||
# Copyright 2012 Matt Mackall <mpm@selenic.com> | ||||
# | ||||
# This software may be used and distributed according to the terms of the | ||||
# GNU General Public License version 2 or any later version. | ||||
|
r30560 | """Generic output formatting for Mercurial | ||
The formatter provides API to show data in various ways. The following | ||||
functions should be used in place of ui.write(): | ||||
- fm.write() for unconditional output | ||||
- fm.condwrite() to show some extra data conditionally in plain output | ||||
|
r31172 | - fm.context() to provide changectx to template output | ||
|
r30560 | - fm.data() to provide extra data to JSON or template output | ||
- fm.plain() to show raw text that isn't provided to JSON or template output | ||||
To show structured data (e.g. date tuples, dicts, lists), apply fm.format*() | ||||
beforehand so the data is converted to the appropriate data type. Use | ||||
fm.isplain() if you need to convert or format data conditionally which isn't | ||||
supported by the formatter API. | ||||
To build nested structure (i.e. a list of dicts), use fm.nested(). | ||||
See also https://www.mercurial-scm.org/wiki/GenericTemplatingPlan | ||||
fm.condwrite() vs 'if cond:': | ||||
In most cases, use fm.condwrite() so users can selectively show the data | ||||
in template output. If it's costly to build data, use plain 'if cond:' with | ||||
fm.write(). | ||||
fm.nested() vs fm.formatdict() (or fm.formatlist()): | ||||
fm.nested() should be used to form a tree structure (a list of dicts of | ||||
lists of dicts...) which can be accessed through template keywords, e.g. | ||||
"{foo % "{bar % {...}} {baz % {...}}"}". On the other hand, fm.formatdict() | ||||
exports a dict-type object to template, which can be accessed by e.g. | ||||
"{get(foo, key)}" function. | ||||
Doctest helper: | ||||
>>> def show(fn, verbose=False, **opts): | ||||
... import sys | ||||
... from . import ui as uimod | ||||
... ui = uimod.ui() | ||||
... ui.fout = sys.stdout # redirect to doctest | ||||
... ui.verbose = verbose | ||||
... return fn(ui, ui.formatter(fn.__name__, opts)) | ||||
Basic example: | ||||
>>> def files(ui, fm): | ||||
... files = [('foo', 123, (0, 0)), ('bar', 456, (1, 0))] | ||||
... for f in files: | ||||
... fm.startitem() | ||||
... fm.write('path', '%s', f[0]) | ||||
... fm.condwrite(ui.verbose, 'date', ' %s', | ||||
... fm.formatdate(f[2], '%Y-%m-%d %H:%M:%S')) | ||||
... fm.data(size=f[1]) | ||||
... fm.plain('\\n') | ||||
... fm.end() | ||||
>>> show(files) | ||||
foo | ||||
bar | ||||
>>> show(files, verbose=True) | ||||
foo 1970-01-01 00:00:00 | ||||
bar 1970-01-01 00:00:01 | ||||
>>> show(files, template='json') | ||||
[ | ||||
{ | ||||
"date": [0, 0], | ||||
"path": "foo", | ||||
"size": 123 | ||||
}, | ||||
{ | ||||
"date": [1, 0], | ||||
"path": "bar", | ||||
"size": 456 | ||||
} | ||||
] | ||||
>>> show(files, template='path: {path}\\ndate: {date|rfc3339date}\\n') | ||||
path: foo | ||||
date: 1970-01-01T00:00:00+00:00 | ||||
path: bar | ||||
date: 1970-01-01T00:00:01+00:00 | ||||
Nested example: | ||||
>>> def subrepos(ui, fm): | ||||
... fm.startitem() | ||||
... fm.write('repo', '[%s]\\n', 'baz') | ||||
... files(ui, fm.nested('files')) | ||||
... fm.end() | ||||
>>> show(subrepos) | ||||
[baz] | ||||
foo | ||||
bar | ||||
>>> show(subrepos, template='{repo}: {join(files % "{path}", ", ")}\\n') | ||||
baz: foo, bar | ||||
""" | ||||
|
r25950 | from __future__ import absolute_import | ||
|
r32838 | import collections | ||
|
r32574 | import contextlib | ||
|
r31807 | import itertools | ||
|
r25511 | import os | ||
|
r22428 | |||
|
r25950 | from .i18n import _ | ||
from .node import ( | ||||
hex, | ||||
short, | ||||
) | ||||
from . import ( | ||||
|
r26587 | error, | ||
|
r32159 | pycompat, | ||
|
r31782 | templatefilters, | ||
|
r29676 | templatekw, | ||
|
r25950 | templater, | ||
|
r29324 | util, | ||
|
r25950 | ) | ||
|
r29324 | pickle = util.pickle | ||
|
r29836 | class _nullconverter(object): | ||
'''convert non-primitive data types to be processed by formatter''' | ||||
@staticmethod | ||||
def formatdate(date, fmt): | ||||
'''convert date tuple to appropriate format''' | ||||
return date | ||||
@staticmethod | ||||
def formatdict(data, key, value, fmt, sep): | ||||
'''convert dict or key-value pairs to appropriate dict format''' | ||||
# use plain dict instead of util.sortdict so that data can be | ||||
# serialized as a builtin dict in pickle output | ||||
return dict(data) | ||||
@staticmethod | ||||
def formatlist(data, name, fmt, sep): | ||||
'''convert iterable to appropriate list format''' | ||||
return list(data) | ||||
|
r16134 | class baseformatter(object): | ||
|
r29836 | def __init__(self, ui, topic, opts, converter): | ||
|
r16134 | self._ui = ui | ||
self._topic = topic | ||||
self._style = opts.get("style") | ||||
self._template = opts.get("template") | ||||
|
r29836 | self._converter = converter | ||
|
r16134 | self._item = None | ||
|
r22701 | # function to convert node to string suitable for this output | ||
self.hexfunc = hex | ||||
|
r29882 | def __enter__(self): | ||
return self | ||||
def __exit__(self, exctype, excvalue, traceback): | ||||
if exctype is None: | ||||
self.end() | ||||
|
r16134 | def _showitem(self): | ||
'''show a formatted item once all data is collected''' | ||||
pass | ||||
def startitem(self): | ||||
'''begin an item in the format list''' | ||||
if self._item is not None: | ||||
self._showitem() | ||||
self._item = {} | ||||
|
r29836 | def formatdate(self, date, fmt='%a %b %d %H:%M:%S %Y %1%2'): | ||
|
r29678 | '''convert date tuple to appropriate format''' | ||
|
r29836 | return self._converter.formatdate(date, fmt) | ||
def formatdict(self, data, key='key', value='value', fmt='%s=%s', sep=' '): | ||||
|
r29794 | '''convert dict or key-value pairs to appropriate dict format''' | ||
|
r29836 | return self._converter.formatdict(data, key, value, fmt, sep) | ||
def formatlist(self, data, name, fmt='%s', sep=' '): | ||||
|
r29676 | '''convert iterable to appropriate list format''' | ||
|
r29836 | # name is mandatory argument for now, but it could be optional if | ||
# we have default template keyword, e.g. {item} | ||||
return self._converter.formatlist(data, name, fmt, sep) | ||||
|
r31172 | def context(self, **ctxs): | ||
'''insert context objects to be used to render template keywords''' | ||||
pass | ||||
|
r16134 | def data(self, **data): | ||
'''insert data into item that's not shown in default output''' | ||||
|
r32159 | data = pycompat.byteskwargs(data) | ||
|
r17630 | self._item.update(data) | ||
|
r16134 | def write(self, fields, deftext, *fielddata, **opts): | ||
'''do default text output while assigning data to item''' | ||||
|
r26372 | fieldkeys = fields.split() | ||
assert len(fieldkeys) == len(fielddata) | ||||
|
r26373 | self._item.update(zip(fieldkeys, fielddata)) | ||
|
r17909 | def condwrite(self, cond, fields, deftext, *fielddata, **opts): | ||
'''do conditional write (primarily for plain formatter)''' | ||||
|
r26372 | fieldkeys = fields.split() | ||
assert len(fieldkeys) == len(fielddata) | ||||
|
r26373 | self._item.update(zip(fieldkeys, fielddata)) | ||
|
r16134 | def plain(self, text, **opts): | ||
'''show raw text for non-templated mode''' | ||||
pass | ||||
|
r29949 | def isplain(self): | ||
'''check for plain formatter usage''' | ||||
return False | ||||
|
r29837 | def nested(self, field): | ||
'''sub formatter to store nested data in the specified field''' | ||||
self._item[field] = data = [] | ||||
return _nestedformatter(self._ui, self._converter, data) | ||||
|
r16134 | def end(self): | ||
'''end output for the formatter''' | ||||
if self._item is not None: | ||||
self._showitem() | ||||
|
r32575 | def nullformatter(ui, topic): | ||
'''formatter that prints nothing''' | ||||
return baseformatter(ui, topic, opts={}, converter=_nullconverter) | ||||
|
r29837 | class _nestedformatter(baseformatter): | ||
'''build sub items and store them in the parent formatter''' | ||||
def __init__(self, ui, converter, data): | ||||
baseformatter.__init__(self, ui, topic='', opts={}, converter=converter) | ||||
self._data = data | ||||
def _showitem(self): | ||||
self._data.append(self._item) | ||||
|
r29794 | def _iteritems(data): | ||
'''iterate key-value pairs in stable order''' | ||||
if isinstance(data, dict): | ||||
return sorted(data.iteritems()) | ||||
return data | ||||
|
r29836 | class _plainconverter(object): | ||
'''convert non-primitive data types to text''' | ||||
@staticmethod | ||||
def formatdate(date, fmt): | ||||
'''stringify date tuple in the given format''' | ||||
return util.datestr(date, fmt) | ||||
@staticmethod | ||||
def formatdict(data, key, value, fmt, sep): | ||||
'''stringify key-value pairs separated by sep''' | ||||
return sep.join(fmt % (k, v) for k, v in _iteritems(data)) | ||||
@staticmethod | ||||
def formatlist(data, name, fmt, sep): | ||||
'''stringify iterable separated by sep''' | ||||
return sep.join(fmt % e for e in data) | ||||
|
r16134 | class plainformatter(baseformatter): | ||
'''the default text output scheme''' | ||||
|
r32573 | def __init__(self, ui, out, topic, opts): | ||
|
r29836 | baseformatter.__init__(self, ui, topic, opts, _plainconverter) | ||
|
r22701 | if ui.debugflag: | ||
self.hexfunc = hex | ||||
else: | ||||
self.hexfunc = short | ||||
|
r32573 | if ui is out: | ||
self._write = ui.write | ||||
else: | ||||
self._write = lambda s, **opts: out.write(s) | ||||
|
r16134 | def startitem(self): | ||
pass | ||||
def data(self, **data): | ||||
pass | ||||
def write(self, fields, deftext, *fielddata, **opts): | ||||
|
r32573 | self._write(deftext % fielddata, **opts) | ||
|
r17909 | def condwrite(self, cond, fields, deftext, *fielddata, **opts): | ||
'''do conditional write''' | ||||
if cond: | ||||
|
r32573 | self._write(deftext % fielddata, **opts) | ||
|
r16134 | def plain(self, text, **opts): | ||
|
r32573 | self._write(text, **opts) | ||
|
r29949 | def isplain(self): | ||
return True | ||||
|
r29837 | def nested(self, field): | ||
# nested data will be directly written to ui | ||||
return self | ||||
|
r16134 | def end(self): | ||
pass | ||||
class debugformatter(baseformatter): | ||||
|
r31182 | def __init__(self, ui, out, topic, opts): | ||
|
r29836 | baseformatter.__init__(self, ui, topic, opts, _nullconverter) | ||
|
r31182 | self._out = out | ||
self._out.write("%s = [\n" % self._topic) | ||||
|
r16134 | def _showitem(self): | ||
|
r31182 | self._out.write(" " + repr(self._item) + ",\n") | ||
|
r16134 | def end(self): | ||
baseformatter.end(self) | ||||
|
r31182 | self._out.write("]\n") | ||
|
r16134 | |||
|
r22430 | class pickleformatter(baseformatter): | ||
|
r31182 | def __init__(self, ui, out, topic, opts): | ||
|
r29836 | baseformatter.__init__(self, ui, topic, opts, _nullconverter) | ||
|
r31182 | self._out = out | ||
|
r22430 | self._data = [] | ||
def _showitem(self): | ||||
self._data.append(self._item) | ||||
def end(self): | ||||
baseformatter.end(self) | ||||
|
r31182 | self._out.write(pickle.dumps(self._data)) | ||
|
r22430 | |||
|
r22428 | class jsonformatter(baseformatter): | ||
|
r31182 | def __init__(self, ui, out, topic, opts): | ||
|
r29836 | baseformatter.__init__(self, ui, topic, opts, _nullconverter) | ||
|
r31182 | self._out = out | ||
self._out.write("[") | ||||
|
r31298 | self._first = True | ||
|
r22428 | def _showitem(self): | ||
|
r31298 | if self._first: | ||
self._first = False | ||||
|
r22428 | else: | ||
|
r31182 | self._out.write(",") | ||
|
r22428 | |||
|
r31182 | self._out.write("\n {\n") | ||
|
r22428 | first = True | ||
for k, v in sorted(self._item.items()): | ||||
if first: | ||||
first = False | ||||
else: | ||||
|
r31182 | self._out.write(",\n") | ||
|
r31782 | u = templatefilters.json(v, paranoid=False) | ||
self._out.write(' "%s": %s' % (k, u)) | ||||
|
r31182 | self._out.write("\n }") | ||
|
r22428 | def end(self): | ||
baseformatter.end(self) | ||||
|
r31182 | self._out.write("\n]\n") | ||
|
r22428 | |||
|
r29836 | class _templateconverter(object): | ||
'''convert non-primitive data types to be processed by templater''' | ||||
@staticmethod | ||||
def formatdate(date, fmt): | ||||
'''return date tuple''' | ||||
return date | ||||
@staticmethod | ||||
def formatdict(data, key, value, fmt, sep): | ||||
'''build object that can be evaluated as either plain string or dict''' | ||||
data = util.sortdict(_iteritems(data)) | ||||
def f(): | ||||
yield _plainconverter.formatdict(data, key, value, fmt, sep) | ||||
|
r31925 | return templatekw.hybriddict(data, key=key, value=value, fmt=fmt, | ||
gen=f()) | ||||
|
r29836 | @staticmethod | ||
def formatlist(data, name, fmt, sep): | ||||
'''build object that can be evaluated as either plain string or list''' | ||||
data = list(data) | ||||
def f(): | ||||
yield _plainconverter.formatlist(data, name, fmt, sep) | ||||
|
r31924 | return templatekw.hybridlist(data, name=name, fmt=fmt, gen=f()) | ||
|
r29836 | |||
|
r25513 | class templateformatter(baseformatter): | ||
|
r31182 | def __init__(self, ui, out, topic, opts): | ||
|
r29836 | baseformatter.__init__(self, ui, topic, opts, _templateconverter) | ||
|
r31182 | self._out = out | ||
|
r32832 | spec = lookuptemplate(ui, topic, opts.get('template', '')) | ||
|
r32841 | self._tref = spec.ref | ||
|
r32840 | self._t = loadtemplater(ui, spec, cache=templatekw.defaulttempl) | ||
|
r31807 | self._counter = itertools.count() | ||
|
r31172 | self._cache = {} # for templatekw/funcs to store reusable data | ||
def context(self, **ctxs): | ||||
'''insert context objects to be used to render template keywords''' | ||||
assert all(k == 'ctx' for k in ctxs) | ||||
self._item.update(ctxs) | ||||
|
r25513 | def _showitem(self): | ||
|
r31172 | # TODO: add support for filectx. probably each template keyword or | ||
# function will have to declare dependent resources. e.g. | ||||
# @templatekeyword(..., requires=('ctx',)) | ||||
|
r31805 | props = {} | ||
|
r31172 | if 'ctx' in self._item: | ||
|
r31805 | props.update(templatekw.keywords) | ||
|
r31807 | props['index'] = next(self._counter) | ||
|
r31805 | # explicitly-defined fields precede templatekw | ||
props.update(self._item) | ||||
if 'ctx' in self._item: | ||||
|
r31172 | # but template resources must be always available | ||
props['templ'] = self._t | ||||
props['repo'] = props['ctx'].repo() | ||||
props['revcache'] = {} | ||||
|
r32841 | g = self._t(self._tref, ui=self._ui, cache=self._cache, **props) | ||
|
r31182 | self._out.write(templater.stringify(g)) | ||
|
r25513 | |||
|
r32838 | templatespec = collections.namedtuple(r'templatespec', | ||
|
r32840 | r'ref tmpl mapfile') | ||
|
r32838 | |||
|
r25511 | def lookuptemplate(ui, topic, tmpl): | ||
|
r32834 | """Find the template matching the given -T/--template spec 'tmpl' | ||
'tmpl' can be any of the following: | ||||
- a literal template (e.g. '{rev}') | ||||
- a map-file name or path (e.g. 'changelog') | ||||
- a reference to [templates] in config file | ||||
- a path to raw template file | ||||
A map file defines a stand-alone template environment. If a map file | ||||
selected, all templates defined in the file will be loaded, and the | ||||
template matching the given topic will be rendered. No aliases will be | ||||
loaded from user config. | ||||
|
r32875 | |||
If no map file selected, all templates in [templates] section will be | ||||
available as well as aliases in [templatealias]. | ||||
|
r32834 | """ | ||
|
r25511 | # looks like a literal template? | ||
if '{' in tmpl: | ||||
|
r32875 | return templatespec('', tmpl, None) | ||
|
r25511 | |||
# perhaps a stock style? | ||||
if not os.path.split(tmpl)[0]: | ||||
mapname = (templater.templatepath('map-cmdline.' + tmpl) | ||||
or templater.templatepath(tmpl)) | ||||
if mapname and os.path.isfile(mapname): | ||||
|
r32840 | return templatespec(topic, None, mapname) | ||
|
r25511 | |||
# perhaps it's a reference to [templates] | ||||
|
r32875 | if ui.config('templates', tmpl): | ||
return templatespec(tmpl, None, None) | ||||
|
r25511 | |||
if tmpl == 'list': | ||||
ui.write(_("available styles: %s\n") % templater.stylelist()) | ||||
|
r26587 | raise error.Abort(_("specify a template")) | ||
|
r25511 | |||
# perhaps it's a path to a map or a template | ||||
if ('/' in tmpl or '\\' in tmpl) and os.path.isfile(tmpl): | ||||
# is it a mapfile for a style? | ||||
if os.path.basename(tmpl).startswith("map-"): | ||||
|
r32840 | return templatespec(topic, None, os.path.realpath(tmpl)) | ||
|
r32829 | with util.posixfile(tmpl, 'rb') as f: | ||
|
r32827 | tmpl = f.read() | ||
|
r32875 | return templatespec('', tmpl, None) | ||
|
r25511 | |||
# constant string? | ||||
|
r32875 | return templatespec('', tmpl, None) | ||
|
r25511 | |||
|
r32840 | def loadtemplater(ui, spec, cache=None): | ||
|
r32831 | """Create a templater from either a literal template or loading from | ||
a map file""" | ||||
|
r32838 | assert not (spec.tmpl and spec.mapfile) | ||
if spec.mapfile: | ||||
return templater.templater.frommapfile(spec.mapfile, cache=cache) | ||||
|
r32876 | return maketemplater(ui, spec.tmpl, cache=cache) | ||
|
r28955 | |||
|
r32873 | def maketemplater(ui, tmpl, cache=None): | ||
|
r28955 | """Create a templater from a string template 'tmpl'""" | ||
|
r28957 | aliases = ui.configitems('templatealias') | ||
|
r31170 | t = templater.templater(cache=cache, aliases=aliases) | ||
|
r32875 | t.cache.update((k, templater.unquotestring(v)) | ||
for k, v in ui.configitems('templates')) | ||||
|
r25512 | if tmpl: | ||
|
r32876 | t.cache[''] = tmpl | ||
|
r25512 | return t | ||
|
r32573 | def formatter(ui, out, topic, opts): | ||
|
r22428 | template = opts.get("template", "") | ||
if template == "json": | ||||
|
r32573 | return jsonformatter(ui, out, topic, opts) | ||
|
r22430 | elif template == "pickle": | ||
|
r32573 | return pickleformatter(ui, out, topic, opts) | ||
|
r22428 | elif template == "debug": | ||
|
r32573 | return debugformatter(ui, out, topic, opts) | ||
|
r22428 | elif template != "": | ||
|
r32573 | return templateformatter(ui, out, topic, opts) | ||
|
r25838 | # developer config: ui.formatdebug | ||
|
r22428 | elif ui.configbool('ui', 'formatdebug'): | ||
|
r32573 | return debugformatter(ui, out, topic, opts) | ||
|
r25838 | # deprecated config: ui.formatjson | ||
|
r22428 | elif ui.configbool('ui', 'formatjson'): | ||
|
r32573 | return jsonformatter(ui, out, topic, opts) | ||
return plainformatter(ui, out, topic, opts) | ||||
|
r32574 | |||
@contextlib.contextmanager | ||||
def openformatter(ui, filename, topic, opts): | ||||
"""Create a formatter that writes outputs to the specified file | ||||
Must be invoked using the 'with' statement. | ||||
""" | ||||
with util.posixfile(filename, 'wb') as out: | ||||
with formatter(ui, out, topic, opts) as fm: | ||||
yield fm | ||||
@contextlib.contextmanager | ||||
def _neverending(fm): | ||||
yield fm | ||||
def maybereopen(fm, filename, opts): | ||||
"""Create a formatter backed by file if filename specified, else return | ||||
the given formatter | ||||
Must be invoked using the 'with' statement. This will never call fm.end() | ||||
of the given formatter. | ||||
""" | ||||
if filename: | ||||
return openformatter(fm._ui, filename, fm._topic, opts) | ||||
else: | ||||
return _neverending(fm) | ||||