Patchwork [1,of,3] help: add documentation for new template functions

login
register
mail settings
Submitter Sean Farley
Date Jan. 23, 2013, 6:28 a.m.
Message ID <a7d9ae27dce66975b899.1358922499@laptop.local>
Download mbox | patch
Permalink /patch/714/
State Accepted
Commit 3aa8b4b36b6487ae5690ac62561536a7ed30cb6b
Headers show

Comments

Sean Farley - Jan. 23, 2013, 6:28 a.m.
# HG changeset patch
# User Sean Farley <sean.michael.farley@gmail.com>
# Date 1358901623 21600
# Branch stable
# Node ID a7d9ae27dce66975b899147b5ff8ffb679fc951b
# Parent  a2e9fe93d9eaba4ad2727d6bcde3afe3985ac00b
help: add documentation for new template functions

Patch

diff --git a/mercurial/help/templates.txt b/mercurial/help/templates.txt
--- a/mercurial/help/templates.txt
+++ b/mercurial/help/templates.txt
@@ -36,5 +36,63 @@ 
    2008-08-21 18:22 +0000
 
 List of filters:
 
 .. filtersmarker
+
+Note that a filters is nothing more than a function call, i.e. ``expr|filter``
+is equivalent to ``filter(expr)``.
+
+In addition to filters, there are some basic built-in functions:
+
+- if(expr, then[, else])
+
+- ifeq(expr, expr, then[, else])
+
+- sub(pat, repl, expr)
+
+- join(list, sep)
+
+- label(label, expr)
+
+- date(date[, fmt])
+
+- fill(text[, width])
+
+Also, for any expression that returns a list, there is a list operator:
+
+- expr % "{template}"
+
+Some sample command line templates:
+
+- Format lists, e.g. files::
+
+   $ hg log -r 0 --template "files:\n{files % '  {file}\n'}"
+
+- Join the list of files with a ", "::
+
+   $ hg log -r 0 --template "files: {join(files, ', ')}\n"
+
+- Format date::
+
+   $ hg log -r 0 --template "{date(date, '%Y')}\n"
+
+- Output the description set to a fill-width of 30::
+
+   $ hg log -r 0 --template "{fill(desc, '30')}"
+
+- Use a conditional to test for the default branch::
+
+   $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
+   'on branch {branch}')}\n"
+
+- Append a newline if not empty::
+
+   $ hg tip --template "{if(author, '{author}\n')}"
+
+- Label the output for use with the color extension::
+
+   $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
+
+- Invert the firstline filter, i.e. everything but the first line::
+
+   $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"