Patchwork help: add documentation for new template functions

login
register
mail settings
Submitter Sean Farley
Date Jan. 22, 2013, 6:31 a.m.
Message ID <2decebe0c3d08d0c2c9e.1358836284@laptop.local>
Download mbox | patch
Permalink /patch/707/
State Superseded
Commit 3aa8b4b36b6487ae5690ac62561536a7ed30cb6b
Headers show

Comments

Sean Farley - Jan. 22, 2013, 6:31 a.m.
# HG changeset patch
# User Sean Farley <sean.michael.farley@gmail.com>
# Date 1358836271 21600
# Branch stable
# Node ID 2decebe0c3d08d0c2c9e915b72d88220da0fa01e
# Parent  9d793a83323921bc6213fce8ea2cb79a16d37955
help: add documentation for new template functions
Matt Mackall - Jan. 22, 2013, 11:42 p.m.
On Tue, 2013-01-22 at 00:31 -0600, Sean Farley wrote:
> # HG changeset patch
> # User Sean Farley <sean.michael.farley@gmail.com>
> # Date 1358836271 21600
> # Branch stable
> # Node ID 2decebe0c3d08d0c2c9e915b72d88220da0fa01e
> # Parent  9d793a83323921bc6213fce8ea2cb79a16d37955
> help: add documentation for new template functions

This looks great, but..

> +   $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
> +   Add back links from file revisions to changeset revisions
> +   Add simple transaction support
> +   Add hg verify
> +   Improve caching in revlog
> +   Fix a bunch of bugs
> +   Self-hosting now that the metadata is close to finalized

..I think we should drop the example output. It's not necessarily going
to make sense to people not familiar with Mercurial's own repo. And on
this particular example, it even confused me (since it predates me being
strict about one change at a time).
Sean Farley - Jan. 23, 2013, 12:17 a.m.
On Tue, Jan 22, 2013 at 5:42 PM, Matt Mackall <mpm@selenic.com> wrote:
> On Tue, 2013-01-22 at 00:31 -0600, Sean Farley wrote:
>> # HG changeset patch
>> # User Sean Farley <sean.michael.farley@gmail.com>
>> # Date 1358836271 21600
>> # Branch stable
>> # Node ID 2decebe0c3d08d0c2c9e915b72d88220da0fa01e
>> # Parent  9d793a83323921bc6213fce8ea2cb79a16d37955
>> help: add documentation for new template functions
>
> This looks great, but..
>
>> +   $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
>> +   Add back links from file revisions to changeset revisions
>> +   Add simple transaction support
>> +   Add hg verify
>> +   Improve caching in revlog
>> +   Fix a bunch of bugs
>> +   Self-hosting now that the metadata is close to finalized
>
> ..I think we should drop the example output. It's not necessarily going
> to make sense to people not familiar with Mercurial's own repo. And on
> this particular example, it even confused me (since it predates me being
> strict about one change at a time).

Sure, no problem. I can drop all the example output and resend.

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,99 @@ 
    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'}"
+   files:
+     PKG-INFO
+     README
+     hg
+     mercurial/__init__.py
+     mercurial/byterange.py
+     mercurial/fancyopts.py
+     mercurial/hg.py
+     mercurial/mdiff.py
+     mercurial/revlog.py
+     mercurial/transaction.py
+     notes.txt
+     setup.py
+     tkmerge
+
+- Join the list of files with a ", "::
+
+   $ hg log -r 0 --template "files: {join(files, ', ')}\n"
+   files: PKG-INFO, README, hg, mercurial/__init__.py,
+   mercurial/byterange.py, mercurial/fancyopts.py, mercurial/hg.py,
+   mercurial/mdiff.py, mercurial/revlog.py, mercurial/transaction.py,
+   notes.txt, setup.py, tkmerge
+
+- Format date::
+
+   $ hg log -r 0 --template "{date(date, '%Y')}\n"
+   2005
+
+- Output the description set to a fill-width of 30::
+
+   $ hg log -r 0 --template "{fill(desc, '30')}"
+   Add back links from file
+   revisions to changeset
+   revisions Add simple
+   transaction support Add hg
+   verify Improve caching in
+   revlog Fix a bunch of bugs
+   Self-hosting now that the
+   metadata is close to finalized
+
+- 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"
+   on the main branch
+
+- Append a newline if not empty::
+
+   $ hg tip --template "{if(author, '{author}\n')}"
+   Matt Mackall <mpm@selenic.com>
+
+- Label the output for use with the color extension::
+
+   $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
+   9117c6561b0b
+
+- Invert the firstline filter, i.e. everything but the first line::
+
+   $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
+   Add back links from file revisions to changeset revisions
+   Add simple transaction support
+   Add hg verify
+   Improve caching in revlog
+   Fix a bunch of bugs
+   Self-hosting now that the metadata is close to finalized