Note:

This page is primarily intended for developers of Mercurial.

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
    fm.startitem()
    # pass data that's otherwise not shown to the templater
    fm.data(size=wctx[f].size())
    # 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
fm.end()

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).

Changeset-oriented commands:

topic\keyword

bookmarks

branch

date

desc

node

parents

rev

tags

user

(others)

export

branch

date

desc

node

parents

user

diff

identity

bookmarks

branch

node

parents

tags

dirty, id

File history commands:

topic\keyword

(abs)path

date

node

rev

user

(data)

(others)

annotate

path

date

node

rev

user

lines{line}

lineno

grep

path

node

rev

texts{text, matched}

change, lineno

{|splitlines}

line

Directory-oriented commands:

topic\keyword

(abs)path

status

(data)

(others)

cat

path

data

files

path

flags, size

kwfiles

kwstatus

manifest

path

resolve

path

mergestatus

status

path

status

copy(source)

{file_copies}

path, name

source

{files}

path, file

Namespace commands:

topic\keyword

(name)

(active)

node

rev

(others)

bookmarks

bookmark

active

node

rev

branches

branch

active

node

rev

closed, current

showbookmarks

bookmark

active

node

longestbookmarklen, nodelen

tags

tag

node

rev

type

{bookmarks}

bookmark

active

current

{branches}

branch

{tags}

tag

Miscellaneous commands:

topic\keyword

(others)

config

source, name, value

histedit

nodechanges{oldnode, newnodes}

journal

command, date, newnodes, oldnodes, user

narrow

pat, /!\ (include/exclude)status

paths

name, pushurl, url

rebase

nodechanges{oldnode, newnodes}

sparse

profiles_added, include_rules_added, exclude_rules_added, files_added, files_dropped, files_conflicting

version

ver, extensions{name, bundled, ver}

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"]
 }
]


CategoryNewFeatures

GenericTemplatingPlan (last edited 2018-10-16 10:47:02 by YuyaNishihara)