hgbook
view es/template.tex @ 421:93bd78a98b78
fixed typo
| author | Javier Rojas <jerojasro@devnull.li> |
|---|---|
| date | Sat Nov 15 20:08:40 2008 -0500 (2008-11-15) |
| parents | 04c08ad7e92e |
| children | 012631b248de |
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 and installed somewhere that Mercurial can find.
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 a default style}
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{Common 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{branches}] String. The name of the branch on which
113 the changeset was committed. Will be empty if the branch name was
114 \texttt{default}.
115 \item[\tplkword{date}] Date information. The date when the changeset
116 was committed. This is \emph{not} human-readable; you must pass it
117 through a filter that will render it appropriately. See
118 section~\ref{sec:template:filter} for more information on filters.
119 The date is expressed as a pair of numbers. The first number is a
120 Unix UTC timestamp (seconds since January 1, 1970); the second is
121 the offset of the committer's timezone from UTC, in seconds.
122 \item[\tplkword{desc}] String. The text of the changeset description.
123 \item[\tplkword{files}] List of strings. All files modified, added, or
124 removed by this changeset.
125 \item[\tplkword{file\_adds}] List of strings. Files added by this
126 changeset.
127 \item[\tplkword{file\_dels}] List of strings. Files removed by this
128 changeset.
129 \item[\tplkword{node}] String. The changeset identification hash, as a
130 40-character hexadecimal string.
131 \item[\tplkword{parents}] List of strings. The parents of the
132 changeset.
133 \item[\tplkword{rev}] Integer. The repository-local changeset revision
134 number.
135 \item[\tplkword{tags}] List of strings. Any tags associated with the
136 changeset.
137 \end{itemize}
139 A few simple experiments will show us what to expect when we use these
140 keywords; you can see the results in
141 figure~\ref{fig:template:keywords}.
143 \begin{figure}
144 \interaction{template.simple.keywords}
145 \caption{Template keywords in use}
146 \label{fig:template:keywords}
147 \end{figure}
149 As we noted above, the date keyword does not produce human-readable
150 output, so we must treat it specially. This involves using a
151 \emph{filter}, about which more in section~\ref{sec:template:filter}.
153 \interaction{template.simple.datekeyword}
155 \section{Escape sequences}
156 \label{sec:template:escape}
158 Mercurial's templating engine recognises the most commonly used escape
159 sequences in strings. When it sees a backslash (``\Verb+\+'')
160 character, it looks at the following character and substitutes the two
161 characters with a single replacement, as described below.
163 \begin{itemize}
164 \item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
165 ASCII~134.
166 \item[\Verb+\textbackslash n+] Newline, ASCII~12.
167 \item[\Verb+\textbackslash r+] Carriage return, ASCII~15.
168 \item[\Verb+\textbackslash t+] Tab, ASCII~11.
169 \item[\Verb+\textbackslash v+] Vertical tab, ASCII~13.
170 \item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173.
171 \item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175.
172 \end{itemize}
174 As indicated above, if you want the expansion of a template to contain
175 a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
176 must escape it.
178 \section{Filtering keywords to change their results}
179 \label{sec:template:filter}
181 Some of the results of template expansion are not immediately easy to
182 use. Mercurial lets you specify an optional chain of \emph{filters}
183 to modify the result of expanding a keyword. You have already seen a
184 common filter, \tplkwfilt{date}{isodate}, in action above, to make a
185 date readable.
187 Below is a list of the most commonly used filters that Mercurial
188 supports. While some filters can be applied to any text, others can
189 only be used in specific circumstances. The name of each filter is
190 followed first by an indication of where it can be used, then a
191 description of its effect.
193 \begin{itemize}
194 \item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+''
195 tag before the end of every line except the last. For example,
196 ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''.
197 \item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the
198 age of the date, relative to the current time. Yields a string like
199 ``\Verb+10 minutes+''.
200 \item[\tplfilter{basename}] Any text, but most useful for the
201 \tplkword{files} keyword and its relatives. Treat the text as a
202 path, and return the basename. For example, ``\Verb+foo/bar/baz+''
203 becomes ``\Verb+baz+''.
204 \item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date
205 in a similar format to the Unix \tplkword{date} command, but with
206 timezone included. Yields a string like
207 ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
208 \item[\tplkwfilt{author}{domain}] Any text, but most useful for the
209 \tplkword{author} keyword. Finds the first string that looks like
210 an email address, and extract just the domain component. For
211 example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
212 ``\Verb+serpentine.com+''.
213 \item[\tplkwfilt{author}{email}] Any text, but most useful for the
214 \tplkword{author} keyword. Extract the first string that looks like
215 an email address. For example,
216 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
217 ``\Verb+bos@serpentine.com+''.
218 \item[\tplfilter{escape}] Any text. Replace the special XML/XHTML
219 characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with
220 XML entities.
221 \item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68
222 columns. This is useful before you pass text through the
223 \tplfilter{tabindent} filter, and still want it to fit in an
224 80-column fixed-font window.
225 \item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76
226 columns.
227 \item[\tplfilter{firstline}] Any text. Yield the first line of text,
228 without any trailing newlines.
229 \item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the
230 date as a pair of readable numbers. Yields a string like
231 ``\Verb+1157407993 25200+''.
232 \item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the
233 date as a text string in ISO~8601 format. Yields a string like
234 ``\Verb+2006-09-04 15:13:13 -0700+''.
235 \item[\tplfilter{obfuscate}] Any text, but most useful for the
236 \tplkword{author} keyword. Yield the input text rendered as a
237 sequence of XML entities. This helps to defeat some particularly
238 stupid screen-scraping email harvesting spambots.
239 \item[\tplkwfilt{author}{person}] Any text, but most useful for the
240 \tplkword{author} keyword. Yield the text before an email address.
241 For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+''
242 becomes ``\Verb+Bryan O'Sullivan+''.
243 \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a
244 date using the same format used in email headers. Yields a string
245 like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
246 \item[\tplkwfilt{node}{short}] Changeset hash. Yield the short form
247 of a changeset hash, i.e.~a 12-byte hexadecimal string.
248 \item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render
249 the year, month, and day of the date. Yields a string like
250 ``\Verb+2006-09-04+''.
251 \item[\tplfilter{strip}] Any text. Strip all leading and trailing
252 whitespace from the string.
253 \item[\tplfilter{tabindent}] Any text. Yield the text, with every line
254 except the first starting with a tab character.
255 \item[\tplfilter{urlescape}] Any text. Escape all characters that are
256 considered ``special'' by URL parsers. For example, \Verb+foo bar+
257 becomes \Verb+foo%20bar+.
258 \item[\tplkwfilt{author}{user}] Any text, but most useful for the
259 \tplkword{author} keyword. Return the ``user'' portion of an email
260 address. For example,
261 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
262 ``\Verb+bos+''.
263 \end{itemize}
265 \begin{figure}
266 \interaction{template.simple.manyfilters}
267 \caption{Template filters in action}
268 \label{fig:template:filters}
269 \end{figure}
271 \begin{note}
272 If you try to apply a filter to a piece of data that it cannot
273 process, Mercurial will fail and print a Python exception. For
274 example, trying to run the output of the \tplkword{desc} keyword
275 into the \tplkwfilt{date}{isodate} filter is not a good idea.
276 \end{note}
278 \subsection{Combining filters}
280 It is easy to combine filters to yield output in the form you would
281 like. The following chain of filters tidies up a description, then
282 makes sure that it fits cleanly into 68 columns, then indents it by a
283 further 8~characters (at least on Unix-like systems, where a tab is
284 conventionally 8~characters wide).
286 \interaction{template.simple.combine}
288 Note the use of ``\Verb+\t+'' (a tab character) in the template to
289 force the first line to be indented; this is necessary since
290 \tplkword{tabindent} indents all lines \emph{except} the first.
292 Keep in mind that the order of filters in a chain is significant. The
293 first filter is applied to the result of the keyword; the second to
294 the result of the first filter; and so on. For example, using
295 \Verb+fill68|tabindent+ gives very different results from
296 \Verb+tabindent|fill68+.
299 \section{From templates to styles}
301 A command line template provides a quick and simple way to format some
302 output. Templates can become verbose, though, and it's useful to be
303 able to give a template a name. A style file is a template with a
304 name, stored in a file.
306 More than that, using a style file unlocks the power of Mercurial's
307 templating engine in ways that are not possible using the command line
308 \hgopt{log}{--template} option.
310 \subsection{The simplest of style files}
312 Our simple style file contains just one line:
314 \interaction{template.simple.rev}
316 This tells Mercurial, ``if you're printing a changeset, use the text
317 on the right as the template''.
319 \subsection{Style file syntax}
321 The syntax rules for a style file are simple.
323 \begin{itemize}
324 \item The file is processed one line at a time.
326 \item Leading and trailing white space are ignored.
328 \item Empty lines are skipped.
330 \item If a line starts with either of the characters ``\texttt{\#}'' or
331 ``\texttt{;}'', the entire line is treated as a comment, and skipped
332 as if empty.
334 \item A line starts with a keyword. This must start with an
335 alphabetic character or underscore, and can subsequently contain any
336 alphanumeric character or underscore. (In regexp notation, a
337 keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
339 \item The next element must be an ``\texttt{=}'' character, which can
340 be preceded or followed by an arbitrary amount of white space.
342 \item If the rest of the line starts and ends with matching quote
343 characters (either single or double quote), it is treated as a
344 template body.
346 \item If the rest of the line \emph{does not} start with a quote
347 character, it is treated as the name of a file; the contents of this
348 file will be read and used as a template body.
349 \end{itemize}
351 \section{Style files by example}
353 To illustrate how to write a style file, we will construct a few by
354 example. Rather than provide a complete style file and walk through
355 it, we'll mirror the usual process of developing a style file by
356 starting with something very simple, and walking through a series of
357 successively more complete examples.
359 \subsection{Identifying mistakes in style files}
361 If Mercurial encounters a problem in a style file you are working on,
362 it prints a terse error message that, once you figure out what it
363 means, is actually quite useful.
365 \interaction{template.svnstyle.syntax.input}
367 Notice that \filename{broken.style} attempts to define a
368 \texttt{changeset} keyword, but forgets to give any content for it.
369 When instructed to use this style file, Mercurial promptly complains.
371 \interaction{template.svnstyle.syntax.error}
373 This error message looks intimidating, but it is not too hard to
374 follow.
376 \begin{itemize}
377 \item The first component is simply Mercurial's way of saying ``I am
378 giving up''.
379 \begin{codesample4}
380 \textbf{abort:} broken.style:1: parse error
381 \end{codesample4}
383 \item Next comes the name of the style file that contains the error.
384 \begin{codesample4}
385 abort: \textbf{broken.style}:1: parse error
386 \end{codesample4}
388 \item Following the file name is the line number where the error was
389 encountered.
390 \begin{codesample4}
391 abort: broken.style:\textbf{1}: parse error
392 \end{codesample4}
394 \item Finally, a description of what went wrong.
395 \begin{codesample4}
396 abort: broken.style:1: \textbf{parse error}
397 \end{codesample4}
398 The description of the problem is not always clear (as in this
399 case), but even when it is cryptic, it is almost always trivial to
400 visually inspect the offending line in the style file and see what
401 is wrong.
402 \end{itemize}
404 \subsection{Uniquely identifying a repository}
406 If you would like to be able to identify a Mercurial repository
407 ``fairly uniquely'' using a short string as an identifier, you can
408 use the first revision in the repository.
409 \interaction{template.svnstyle.id}
410 This is not guaranteed to be unique, but it is nevertheless useful in
411 many cases.
412 \begin{itemize}
413 \item It will not work in a completely empty repository, because such
414 a repository does not have a revision~zero.
415 \item Neither will it work in the (extremely rare) case where a
416 repository is a merge of two or more formerly independent
417 repositories, and you still have those repositories around.
418 \end{itemize}
419 Here are some uses to which you could put this identifier:
420 \begin{itemize}
421 \item As a key into a table for a database that manages repositories
422 on a server.
423 \item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple.
424 Save this information away when you run an automated build or other
425 activity, so that you can ``replay'' the build later if necessary.
426 \end{itemize}
428 \subsection{Mimicking Subversion's output}
430 Let's try to emulate the default output format used by another
431 revision control tool, Subversion.
432 \interaction{template.svnstyle.short}
434 Since Subversion's output style is fairly simple, it is easy to
435 copy-and-paste a hunk of its output into a file, and replace the text
436 produced above by Subversion with the template values we'd like to see
437 expanded.
438 \interaction{template.svnstyle.template}
440 There are a few small ways in which this template deviates from the
441 output produced by Subversion.
442 \begin{itemize}
443 \item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep
444 2006}'' in the example output above) in parentheses. Mercurial's
445 templating engine does not provide a way to display a date in this
446 format without also printing the time and time zone.
447 \item We emulate Subversion's printing of ``separator'' lines full of
448 ``\texttt{-}'' characters by ending the template with such a line.
449 We use the templating engine's \tplkword{header} keyword to print a
450 separator line as the first line of output (see below), thus
451 achieving similar output to Subversion.
452 \item Subversion's output includes a count in the header of the number
453 of lines in the commit message. We cannot replicate this in
454 Mercurial; the templating engine does not currently provide a filter
455 that counts the number of items it is passed.
456 \end{itemize}
457 It took me no more than a minute or two of work to replace literal
458 text from an example of Subversion's output with some keywords and
459 filters to give the template above. The style file simply refers to
460 the template.
461 \interaction{template.svnstyle.style}
463 We could have included the text of the template file directly in the
464 style file by enclosing it in quotes and replacing the newlines with
465 ``\verb!\n!'' sequences, but it would have made the style file too
466 difficult to read. Readability is a good guide when you're trying to
467 decide whether some text belongs in a style file, or in a template
468 file that the style file points to. If the style file will look too
469 big or cluttered if you insert a literal piece of text, drop it into a
470 template instead.
472 %%% Local Variables:
473 %%% mode: latex
474 %%% TeX-master: "00book"
475 %%% End: