/!\ This page is primarily intended for Mercurial's developers.

Generic Templating Plan

Adding advanced templating support to commands beyond log

1. Purpose

Ideally, we should be able to generate customizable output for all output-oriented commands. This will give users fine-grained control for numerous tasks without adding lots of new command line switches. Additionally, we should be able to generate output in common formats such as JSON, XML, and pickle for convenient parsing and automation without any additional code.

2. Interface

Here's what a simple use of templates might look like for a 'showfiles' command:

# create a templater from the command options
fm = ui.formatter('showfiles', opts)
wctx = repo[None]
for f in wctx:
    # start a new template item
    # pass data that's otherwise not shown to the templater
    # show some extra data with -v
    fm.condwrite(ui.verbose, 'flags', '%d %1s ', wctx[f].flags())
    # show the path
    fm.write('path', '%s\n', f)
# shut down the templater

Internally, template data is modeled as a list of dictionaries, which is well-matched to most of our output. Here, we construct a list of (size, flags, path) elements.

3. Specifying a format

There are several types of format we might want to specify:

We've added a single new command-line option -T/--template that gives us convenient access to all of these modes:

3.1. Per-command styles, legacy styles, and verbosity levels

The existing templating system for log doesn't envision support for more than just the log-like commands, but we'll need to continue to support template styles built for this scheme.

We'd also like to have single-file template maps that handle a variety of commands. This might be done by having one map key per command. Dealing with verbosity might be done either with template conditionals or with '.verbose' key suffixes.

4. JSON, XML, and encoding troubles

Given our simple schema, it's a relatively easy matter to construct outputs in standard marshalling formats. One trick here, however, is dealing with non-ASCII data. Given things like filenames may not be in UTF-8 and we often don't even know their encoding (see EncodingStrategy), we can't simply convert to Unicode. Instead, we'll use "UTF-8b", a scheme that can round-trip arbitrary binary data through UTF-8. This is used in various places which have encountered similar problems, for instance Python 3 uses this scheme for dealing with Unix filenames.

5. Steps

6. Sanity check output

A quick scan turns up the following problems:

Non-formatter stuff:

7. Dictionary

Note that this isn't an official list of what we want, it's merely things that are currently present (some of which should be changed).

8. Status

As of 4.6, Mercurial can generate manual templates in addition to JSON and pickle formats for:

$ hg log -r3.1 -Tjson
  "rev": 23089,
  "node": "3178e49892020336491cdc6945885c4de26ffa8b",
  "branch": "stable",
  "phase": "public",
  "user": "Pierre-Yves David <pierre-yves.david@fb.com>",
  "date": [1406923295, 25200],
  "desc": "status: do not reverse deleted and unknown\n\nWhen reversing a status, trading \"added\" and \"removed\" make sense.\nReversing \"deleted\" and \"unknown\" does not. We stop doing it.\n\nThe reversing is documented in place for the poor soul not even able to remember\nthe index of all status elements by heart.",
  "bookmarks": [],
  "tags": ["3.1"],
  "parents": ["8864528874f77272742551223b8265ff4d125534"]


GenericTemplatingPlan (last edited 2018-05-31 12:49:48 by YuyaNishihara)