hgbook
view en/template.tex @ 80:ea951cfb5cd9
Much template-related content.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Wed Sep 06 23:36:47 2006 -0700 (2006-09-06) |
| parents | df88df78288d |
| children | b476081a9c04 |
line source
1 \chapter{Customising the output of Mercurial}
2 \label{chap:template}
4 Mercurial provides a powerful mechanism to let you control how it
5 displays information. The mechanism is based on templates. You can
6 use templates to generate specific output for a single command, or to
7 customise the entire appearance of the built-in web interface.
9 \section{Using precanned output styles}
10 \label{sec:style}
12 Packaged with Mercurial are some output styles that you can use
13 immediately. A style is simply a precanned template that someone
14 wrote.
16 Before we take a look at Mercurial's bundled styles, let's review its
17 normal output.
19 \interaction{template.simple.normal}
21 This is somewhat informative, but it takes up a lot of space---five
22 lines of output per changeset. The \texttt{compact} style reduces
23 this to three lines, presented in a sparse manner.
25 \interaction{template.simple.compact}
27 The \texttt{changelog} style hints at the expressive power of
28 Mercurial's templating engine. This style attempts to follow the GNU
29 Project's changelog guidelines\cite{web:changelog}.
31 \interaction{template.simple.changelog}
33 You will not be shocked to learn that Mercurial's default output style
34 is named \texttt{default}.
36 \subsection{Setting an output style to use}
38 You can modify the output style that Mercurial will use for every
39 command by editing your \hgrc\ file, naming the style you would
40 prefer to use.
42 \begin{codesample2}
43 [ui]
44 style = compact
45 \end{codesample2}
47 If you write a style of your own, you can use it by either providing
48 the path to your style file, or copying your style file into a
49 location where Mercurial can find it (typically the \texttt{templates}
50 subdirectory of your Mercurial install directory).
52 \section{Commands that support styles and templates}
54 All of Mercurial's ``\texttt{log}-like'' commands let you use styles
55 and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and
56 \hgcmd{tip}.
58 As I write this manual, these are so far the only commands that
59 support styles and templates. Since these are the most important
60 commands that need customisable output, there has been little pressure
61 from the Mercurial user community to add style and template support to
62 other commands.
64 \section{The basics of templating}
66 At its simplest, a Mercurial template is a piece of text. Some of the
67 text never changes, while other parts are \emph{expanded}, or replaced
68 with new text, when necessary.
70 Before we continue, let's look again at a simple example of
71 Mercurial's normal output.
73 \interaction{template.simple.normal}
75 Now, let's run the same command, but using a template to change its
76 output.
78 \interaction{template.simple.simplest}
80 The example above illustrates the simplest possible template; it's
81 just a piece of static text, printed once for each changeset. The
82 \hgopt{log}{--template} option to the \hgcmd{log} command tells
83 Mercurial to use the given text as the template when printing each
84 changeset.
86 Notice that the template string above ends with the text
87 ``\Verb+\n+''. This is an \emph{escape sequence}, telling Mercurial
88 to print a newline at the end of each template item. If you omit this
89 newline, Mercurial will run each piece of output together. See
90 section~\ref{sec:template:escape} for more details of escape sequences.
92 A template that prints a fixed string of text all the time isn't very
93 useful; let's try something a bit more complex.
95 \interaction{template.simple.simplesub}
97 As you can see, the string ``\Verb+{desc}+'' in the template has been
98 replaced in the output with the description of each changeset. Every
99 time Mercurial finds text enclosed in curly braces (``\texttt{\{}''
100 and ``\texttt{\}}''), it will try to replace the braces and text with
101 the expansion of whatever is inside. To print a literal curly brace,
102 you must escape it, as described in section~\ref{sec:template:escape}.
104 \section{Basic template keywords}
105 \label{sec:template:keyword}
107 You can start writing simple templates immediately using the keywords
108 below.
110 \begin{itemize}
111 \item[\tplkword{author}] String. The unmodified author of the changeset.
112 \item[\tplkword{date}] Date information. The date when the changeset
113 was committed. This is \emph{not} human-readable; you must pass it
114 through a filter that will render it appropriately. See
115 section~\ref{sec:template:filter} for more information on filters.
116 The date is expressed as a pair of numbers. The first number is a
117 Unix UTC timestamp (seconds since January 1, 1970); the second is
118 the offset of the committer's timezone from UTC, in seconds.
119 \item[\tplkword{desc}] String. The text of the changeset description.
120 \item[\tplkword{files}] List of strings. All files modified, added, or
121 removed by this changeset.
122 \item[\tplkword{file\_adds}] List of strings. Files added by this
123 changeset.
124 \item[\tplkword{file\_dels}] List of strings. Files removed by this
125 changeset.
126 \item[\tplkword{node}] String. The changeset identification hash, as a
127 40-character hexadecimal string.
128 \item[\tplkword{parents}] List of strings. The parents of the
129 changeset.
130 \item[\tplkword{rev}] Integer. The repository-local changeset revision
131 number.
132 \item[\tplkword{tags}] List of strings. Any tags associated with the
133 changeset.
134 \end{itemize}
136 A few simple experiments will show us what to expect when we use these
137 keywords; you can see the results in
138 figure~\ref{fig:template:keywords}.
140 \begin{figure}
141 \interaction{template.simple.keywords}
142 \caption{Template keywords in use}
143 \label{fig:template:keywords}
144 \end{figure}
146 As we noted above, the date keyword does not produce human-readable
147 output, so we must treat it specially. This involves using a
148 \emph{filter}, about which more in section~\ref{sec:template:filter}.
150 \interaction{template.simple.datekeyword}
152 \section{Escape sequences}
153 \label{sec:template:escape}
155 Mercurial's templating engine recognises the most commonly used escape
156 sequences in strings. When it sees a backslash (``\Verb+\+'')
157 character, it looks at the following character and substitutes the two
158 characters with a single replacement, as described below.
160 \begin{itemize}
161 \item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
162 ASCII~134.
163 \item[\Verb+\textbackslash n+] Newline, ASCII~12.
164 \item[\Verb+\textbackslash r+] Carriage return, ASCII~15.
165 \item[\Verb+\textbackslash t+] Tab, ASCII~11.
166 \item[\Verb+\textbackslash v+] Vertical tab, ASCII~13.
167 \item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173.
168 \item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175.
169 \end{itemize}
171 As indicated above, if you want the expansion of a template to contain
172 a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
173 must escape it.
175 \section{Filtering expanded keywords}
176 \label{sec:template:filter}
178 Some of the results of template expansion are not entirely easy to
179 use. Mercurial lets you specify an optional chain of \emph{filters}
180 to modify the result of expanding a keyword. You have already seen a
181 common filter, \tplkwfilt{date}{isodate}, in action above, to make a
182 date readable.
184 \begin{itemize}
185 \item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+''
186 tag before the end of every line except the last. For example,
187 ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''.
188 \item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the
189 age of the date, relative to the current time. Yields a string like
190 ``\Verb+10 minutes+''.
191 \item[\tplfilter{basename}] Any text, but most useful for the
192 \tplkword{files} keyword and its relatives. Treat the text as a
193 path, and return the basename. For example, ``\Verb+foo/bar/baz+''
194 becomes ``\Verb+baz+''.
195 \item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date
196 in a similar format to the Unix \tplkword{date} command, but with
197 timezone included. Yields a string like
198 ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
199 \item[\tplkwfilt{author}{domain}] Any text, but most useful for the
200 \tplkword{author} keyword. Finds the first string that looks like
201 an email address, and extract just the domain component. For
202 example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
203 ``\Verb+serpentine.com+''.
204 \item[\tplkwfilt{author}{email}] Any text, but most useful for the
205 \tplkword{author} keyword. Extract the first string that looks like
206 an email address. For example,
207 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
208 ``\Verb+bos@serpentine.com+''.
209 \item[\tplfilter{escape}] Any text. Replace the special XML/XHTML
210 characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with
211 XML entities.
212 \item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68
213 columns. This is useful before you pass text through the
214 \tplfilter{tabindent} filter, and still want it to fit in an
215 80-column fixed-font window.
216 \item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76
217 columns.
218 \item[\tplfilter{firstline}] Any text. Yield the first line of text,
219 without any trailing newlines.
220 \item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the
221 date as a pair of readable numbers. Yields a string like
222 ``\Verb+1157407993 25200+''.
223 \item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the
224 date as a text string in ISO~8601 format. Yields a string like
225 ``\Verb+2006-09-04 15:13:13 -0700+''.
226 \item[\tplfilter{obfuscate}] Any text, but most useful for the
227 \tplkword{author} keyword. Yield the input text rendered as a
228 sequence of XML entities. This helps to defeat some particularly
229 stupid screen-scraping email harvesting spambots.
230 \item[\tplkwfilt{author}{person}] Any text, but most useful for the
231 \tplkword{author} keyword. Yield the text before an email address.
232 For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+''
233 becomes ``\Verb+Bryan O'Sullivan+''.
234 \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a
235 date using the same format used in email headers. Yields a string
236 like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
237 \item[\tplkwfilt{node}{short}] Changeset hash. Yield the short form
238 of a changeset hash, i.e.~a 12-byte hexadecimal string.
239 \item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render
240 the year, month, and day of the date. Yields a string like
241 ``\Verb+2006-09-04+''.
242 \item[\tplfilter{strip}] Any text. Strip all leading and trailing
243 whitespace from the string.
244 \item[\tplfilter{tabindent}] Any text. Yield the text, with every line
245 except the first starting with a tab character.
246 \item[\tplfilter{urlescape}] Any text. Escape all characters that are
247 considered ``special'' by URL parsers. For example, \Verb+foo bar+
248 becomes \Verb+foo%20bar+.
249 \item[\tplkwfilt{author}{user}] Any text, but most useful for the
250 \tplkword{author} keyword. Return the ``user'' portion of an email
251 address. For example,
252 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
253 ``\Verb+bos+''.
254 \end{itemize}
256 \begin{figure}
257 \interaction{template.simple.manyfilters}
258 \caption{Template filters in action}
259 \label{fig:template:filters}
260 \end{figure}
262 \begin{note}
263 If you try to apply a filter to a piece of data that it cannot
264 process, Mercurial will fail and print a Python exception. For
265 example, trying to run the output of the \tplkword{desc} keyword
266 into the \tplkwfilt{date}{isodate} filter is not a good idea.
267 \end{note}
269 \subsection{Combining filters}
271 It is easy to combine filters to yield output in the form you would
272 like. The following chain of filters tidies up a description, then
273 makes sure that it fits cleanly into 68 columns, then indents it by a
274 further 8~characters (at least on Unix-like systems, where a tab is
275 conventionally 8~characters wide).
277 \interaction{template.simple.combine}
279 Note the use of ``\Verb+\t+'' (a tab character) in the template to
280 force the first line to be indented; this is necessary since
281 \tplkword{tabindent} indents all lines \emph{except} the first.
283 Keep in mind that the order of filters in a chain is significant.
284 Using \Verb+fill68|tabindent+ gives very different results from
285 \Verb+tabindent|fill68+.
287 %%% Local Variables:
288 %%% mode: latex
289 %%% TeX-master: "00book"
290 %%% End: