1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.36">
<style type="text/css">
.equationcontainer{position:relative;}
.equationnumber{float:right;left:auto;position:absolute;right:0}
.equationnumber-valign{float:right;left:auto;position:absolute;right:0;margin-top:-0.5em;}
.floatrule{background-color: black; border: none; height: 1px; width: 80%}
.phantom{display: inline-block; visibility: hidden}
.hphantom{display: inline-block; height: 0; visibility: hidden}
.vphantom{display: inline-block; visibility: hidden; width: 0}
.smash{display: inline-block; height: 0; line-height: 0}
.li-itemize{margin:1ex 0ex;}
.li-enumerate{margin:1ex 0ex;}
.dd-description{margin:0ex 0ex 1ex 4ex;}
.dt-description{margin:0ex;}
.toc{list-style:none;}
.footnotetext{margin:0ex; padding:0ex;}
div.footnotetext P{margin:0px; text-indent:1em;}
.thefootnotes{text-align:left;margin:0ex;}
.dt-thefootnotes{margin:0em;}
.dd-thefootnotes{margin:0em 0em 0em 2em;}
.footnoterule{background-color: black; border: none; height: 1px; margin: 1em auto 1em 0px; width: 40%}
.caption{padding-left:2ex; padding-right:2ex; margin-left:auto; margin-right:auto}
.title{margin:2ex auto;text-align:center}
.titlemain{margin:1ex 2ex 2ex 1ex;}
.titlerest{margin:0ex 2ex;}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
div table{margin-left:inherit;margin-right:inherit;margin-bottom:2px;margin-top:2px}
td table{margin:auto;}
table{border-collapse:collapse;}
td{padding:0;}
.cellpadding0 tr td{padding:0;}
.cellpadding1 tr td{padding:1px;}
pre{text-align:left;margin-left:0ex;margin-right:auto;}
blockquote{margin-left:4ex;margin-right:4ex;text-align:left;}
td p{margin:0px;}
.quote{margin-left:3em;margin-right:3em;text-align:inherit;text-indent:0pt}
.quotation{margin-left:3em;margin-right:3em;text-align:inherit;text-indent:1.5em}
.verse{margin-left:3em;margin-right:3em;text-indent:1.5em hanging each-line}
.parbox{box-sizing: border-box;
display: inline-block;
text-indent: 0;
}
.rule-rect{fill: black;}
.lrbox{box-sizing:border-box;display:inline-block;overflow:visible;white-space:nowrap;}
.center-lrbox{display:inline-block;margin-left:50%;transform:translateX(-50%);}
.makebox{}
.framebox{border:1px solid black;padding:0.25em;}
.vertical-rule{border:none;width:2px;background-color:black;}
.horizontal-rule{border:none;background-color:black;}
.hrule{border:none;height:2px;width:100%;background-color:black;}
.hfill{border:none;height:1px;width:200%;background-color:black;}
.vdisplay{border-collapse:separate;border-spacing:2px;line-height:1.1;width:auto; empty-cells:show; border:2px solid red;}
.vdcell{white-space:nowrap;padding:0px; border:2px solid green;}
.display{border-collapse:separate;border-spacing:2px;line-height:1.1;width:auto; border:none;}
.dcell{white-space:nowrap;padding:0px; border:none;}
.dcenter{margin:0ex auto;}
.vdcenter{border:solid #FF8000 2px; margin:0ex auto;}
.minipage{text-align:left; margin-left:0em; margin-right:auto;}
.marginpar{border:solid thin black; margin-bottom:1ex; width:20%; text-align:left;}
.marginparleft{float:left; clear:left; margin-left:0ex; margin-right:1ex;}
.marginparright{float:right; clear:right; margin-left:1ex; margin-right:0ex;}
.theorem{text-align:left;margin:1ex auto 1ex 0ex;}
.part{margin:2ex auto;text-align:center}
</style>
<title>`headache`
</title>
</head>
<body >
<!--HEVEA command line is: hevea -o manual.html manual.tex -->
<!--CUT STYLE article--><!--CUT DEF section 1 --><table class="title"><tr><td style="padding:1ex"><h1 class="titlemain">‘<span style="font-family:monospace">headache</span>‘</h1><h3 class="titlerest">Vincent Simonet</h3><h3 class="titlerest">November, 2002</h3></td></tr>
</table><p>This manual is also available in <a href="manual.txt">plain text</a>,
<a href="manual.ps.gz">PostScript</a> and <a href="manual.pdf">PDF</a>.</p>
<!--TOC section id="sec1" Overview-->
<h2 id="sec1" class="section">1 Overview</h2><!--SEC END --><p>It is a common usage to put at the beginning of source code files a
short header giving, for instance, some copyright informations.
‘<span style="font-family:monospace">headache</span>‘ is a simple and lightweight tool for managing easily these
headers. Among its functionalities, one may mention:
</p><ul class="itemize"><li class="li-itemize">Headers must generally be generated as <em>comments</em> in source
code files. ‘<span style="font-family:monospace">headache</span>‘ deals with different file types and generates
for each of them headers in an appropriate format.
</li><li class="li-itemize">‘<span style="font-family:monospace">headache</span>‘ automatically detects existing headers and removes them.
Thus, you can use it to update headers in a set of files.
</li></ul><p>‘<span style="font-family:monospace">headache</span>‘ is distributed under the terms of the <em>GNU Library General
Public License</em>. See file ‘<span style="font-family:monospace">LICENSE</span>‘ of the distribution for
more information.</p>
<!--TOC section id="sec2" Compilation and installation-->
<h2 id="sec2" class="section">2 Compilation and installation</h2><!--SEC END --><p>Building ‘<span style="font-family:monospace">headache</span>‘ requires <em>Objective Caml</em> (available at
<span style="font-family:monospace">http://caml.inria.fr/</span>) and <em>GNU Make</em>.
In addition, from version <span style="font-family:monospace">1.03-utf8</span>, the build requires the Unicode library <em>Camomile</em> and, from version <span style="font-family:monospace">1.04</span>, <em>Dune</em>.</p>
<!--TOC paragraph id="sec3" Instructions-->
<h4 id="sec3" class="paragraph">Instructions</h4><!--SEC END --><p>‘<span style="font-family:monospace">headache</span>‘ is available through <em>OPAM</em> (available at
<span style="font-family:monospace">http://opam.ocaml.org/</span>), the <em>OCaml Package Manager</em>.
This is the preferred installation method.
Then the following sequence of commands should install the package:
</p><pre>
opam init
opam install headache
</pre><p>Alternatively, you can use these commands (<em>Dune</em> must be installed):</p><pre>
make && sudo make INSTALLDIR=/usr/local/bin install
</pre><p>
Build the executable and install it into the specified directory.</p>
<!--TOC section id="sec4" Usage-->
<h2 id="sec4" class="section">3 Usage</h2><!--SEC END --><p>Let us illustrate the use of this tool with a small example. Assume
you have a small project mixing C and Caml code consisting in three
files ‘<span style="font-family:monospace">foo.c</span>‘, ‘<span style="font-family:monospace">bar.ml</span>‘ and ‘<span style="font-family:monospace">bar.mli</span>‘, and you want to
equip them with some header. First of all, write a <em>header
file</em>, i.e. a plain text file including the information headers
must mention. An example of such a file is given in
figure <a href="#figure%3Aheader">1</a>. In the following, we assume this file is
named ‘<span style="font-family:monospace">myheader</span>‘ and is in the same directory as source files.</p><p>Then, in order to generate headers, just run the command:
</p><pre>
headache -h myheader foo.c bar.ml bar.mli
</pre><p>
Each file is equipped with a header including the text given in the
header file ‘<span style="font-family:monospace">myheader</span>‘, surrounded by some extra characters
depending on its format making it a comment (e.g. ‘<span style="font-family:monospace">(*</span>‘ and
‘<span style="font-family:monospace">*)</span>‘ in ‘<span style="font-family:monospace">.ml</span>‘ files). If you update informations in the
header file ‘<span style="font-family:monospace">myheader</span>‘, you simply need to re-run the above
command to update headers in source code files: existing ones are
automatically removed.</p><p>Similarly, running:
</p><pre>
headache -r foo.c bar.ml bar.mli
</pre><p>
removes any existing in files ‘<span style="font-family:monospace">foo.c</span>‘, ‘<span style="font-family:monospace">bar.ml</span>‘ and
‘<span style="font-family:monospace">bar.mli</span>‘. Files which do not have a header are kept unchanged.</p><p>The current headers of files can be extracted:
</p><pre>
headache -e foo.c bar.ml bar.mli
</pre><p>
prints on the standard output the current headers of the files ‘<span style="font-family:monospace">foo.c</span>‘,
‘<span style="font-family:monospace">bar.ml</span>‘ and ‘<span style="font-family:monospace">bar.mli</span>‘. All files are kept unchanged.</p><blockquote class="figure"><div class="center"><hr class="floatrule"></div>
<table style="border:1px;border-spacing:0" class="cellpadding1"><tr><td style="text-align:left"><pre class="verbatim">
Headache
Automatic generation of files headers
Vincent Simonet, Projet Cristal, INRIA Rocquencourt
Copyright 2002
Institut National de Recherche en Informatique et en Automatique.
All rights reserved. This file is distributed under the terms of
the GNU Library General Public License.
Vincent.Simonet@inria.fr http://cristal.inria.fr/~simonet/
</pre></td></tr>
</table>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 1: An example of header file</td></tr>
</table></div>
<a id="figure:header"></a>
<div class="center"><hr class="floatrule"></div></blockquote>
<!--TOC section id="sec5" Configuration file-->
<h2 id="sec5" class="section">4 Configuration file</h2><!--SEC END --><p>File types and format of header may be specified by a
<em>configuration file</em>. By default, the default builtin
configuration file given in figure <a href="#figure%3Aconfig">2</a> is used. You
can also use your own configuration file thanks to the ‘<span style="font-family:monospace">-c</span>‘
option:
</p><pre>
headache -c myconfig -h myheader foo.c bar.ml bar.mli
</pre><p>In order to write your own configuration, you can follow the example
given in figure <a href="#figure%3Aconfig">2</a>. A configuration file consists in
a list of <em>entries</em> separated by the character ‘<span style="font-family:monospace">|</span>‘. Each
of them is made of two parts separated by an ‘<span style="font-family:monospace">-></span>‘:
</p><ul class="itemize"><li class="li-itemize">The first one is a <em>regular expression</em>. Regular
expression are enclosed within double quotes and have the same
syntax as in Gnu Emacs. ‘<span style="font-family:monospace">headache</span>‘ determines file types according to
file basenames; thus, each file is dealt with using the first line
its name matches.
</li><li class="li-itemize">The second one describes the format of headers for files of this
type. It consists of the name of a <em>model</em> (e.g.
‘<span style="font-family:monospace">frame</span>‘), possibly followed by a list of arguments. Arguments
are named: ‘<span style="font-family:monospace">open:"(*"</span>‘ means that the value of the argument
‘<span style="font-family:monospace">open</span>‘ is ‘<span style="font-family:monospace">(*</span>‘.
</li></ul><p>
‘<span style="font-family:monospace">headache</span>‘ currently supports three <em>models</em>:
</p><ul class="itemize"><li class="li-itemize">‘<span style="font-family:monospace">frame</span>‘. With this model, headers are generated in a
frame. This model requires three arguments: ‘<span style="font-family:monospace">open</span>‘ and
‘<span style="font-family:monospace">close</span>‘ (the opening and closing sequences for comments) and
‘<span style="font-family:monospace">line</span>‘ (the character used to make the horizontal lines of the
frame). Two optional arguments may be used: ‘<span style="font-family:monospace">margin</span>‘ (a string
printed between the left and right side of the frame and the border,
by default two spaces) and ‘<span style="font-family:monospace">width</span>‘ (the width of the inside of
the frame, default is 68).
</li><li class="li-itemize">‘<span style="font-family:monospace">lines</span>‘. Headers are typeset between two lines. Three
arguments must be provided: ‘<span style="font-family:monospace">open</span>‘ and ‘<span style="font-family:monospace">close</span>‘ (the
opening and closing sequences for comments), ‘<span style="font-family:monospace">line</span>‘ (the
character used to make the horizontal lines). Three optional
arguments are allowed: ‘<span style="font-family:monospace">begin</span>‘ (a string typeset at the
beginning of each line, by default two spaces), ‘<span style="font-family:monospace">last</span>‘ (a
string typeset at the beginning of the last line) and ‘<span style="font-family:monospace">width</span>‘
(the width of the lines, default is 70).
</li><li class="li-itemize">‘<span style="font-family:monospace">no</span>‘. This model generates no header and has no argument.
</li></ul><p>It is possible to change the default builtin configuration file at
compile time. For this, just edit the file ‘<span style="font-family:monospace">config_builtin.txt</span>‘
present in the source distribution before building the software.</p><blockquote class="figure"><div class="center"><hr class="floatrule"></div>
<table style="border:1px;border-spacing:0" class="cellpadding1"><tr><td style="text-align:left"><pre class="verbatim">
# Objective Caml source
".*\\.ml[il]?" -> frame open:"(*" line:"*" close:"*)"
| ".*\\.fml[i]?" -> frame open:"(*" line:"*" close:"*)"
| ".*\\.mly" -> frame open:"/*" line:"*" close:"*/"
# C source
| ".*\\.[chy]" -> frame open:"/*" line:"*" close:"*/"
# Latex
| ".*\\.tex" -> frame open:"%" line:"%" close:"%"
# Misc
| ".*Makefile.*" -> frame open:"#" line:"#" close:"#"
| ".*README.*" -> frame open:"*" line:"*" close:"*"
| ".*LICENSE.*" -> frame open:"*" line:"*" close:"*"
</pre></td></tr>
</table>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 2: The default builtin configuration file</td></tr>
</table></div>
<a id="figure:config"></a>
<div class="center"><hr class="floatrule"></div></blockquote><p>It is also possible to add entries into your own configuration file that
specify when the initial lines of the processed file have to be skipped.
As previously, these <em>entries</em> are separated by the character ‘<span style="font-family:monospace">|</span>‘
and each of them is made of two parts separated by an ‘<span style="font-family:monospace">-></span>‘:
</p><ul class="itemize"><li class="li-itemize">Again, the first part is a <em>regular expression</em> used by ‘<span style="font-family:monospace">headache</span>‘
to determine the file type. But here, it is according to
its full filename (including the pathname).
</li><li class="li-itemize">The second part specifies when the initial lines must be skipped.
It consists of the keyword ‘<span style="font-family:monospace">skip</span>‘ followed by one of the named
arguments ‘<span style="font-family:monospace">multiline_match:</span>‘ or ‘<span style="font-family:monospace">match:</span>‘, then a <em>regular expression</em>.
As long as the lines match a ‘<span style="font-family:monospace">multiline_match</span>‘ parameter,
‘<span style="font-family:monospace">headache</span>‘ skips them and checks the next line.
If the current line matches only a ‘<span style="font-family:monospace">match</span>‘ parameter,
‘<span style="font-family:monospace">headache</span>‘ skips the current line and breaks the iteration there (of course,
if nothing matches, ‘<span style="font-family:monospace">headache</span>‘ puts the header before the current line).</li></ul><blockquote class="figure"><div class="center"><hr class="floatrule"></div>
<table style="border:1px;border-spacing:0" class="cellpadding1"><tr><td style="text-align:left"><pre class="verbatim"># Script file
| ".*\\.sh" -> frame open:"#" line:"#" close:"#"
| ".*\\.sh" -> skip match:"#!.*"
</pre></td></tr>
</table>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 3: Example of a configuration file for skipping the shebang line of shell scripts</td></tr>
</table></div>
<a id="figure:example"></a>
<div class="center"><hr class="floatrule"></div></blockquote><p>Figure <a href="#figure%3Aexample">3</a> shows an example of configuration file
that can used to skip the shebang line of shell scripts:
when the first line of ‘<span style="font-family:monospace">.sh</span>‘ files starts with ‘<span style="font-family:monospace">#!</span>‘,
‘<span style="font-family:monospace">headache</span>‘ does not modify that line and considers that the header must
start at the second line.</p><blockquote class="figure"><div class="center"><hr class="floatrule"></div>
<table style="border:1px;border-spacing:0" class="cellpadding1"><tr><td style="text-align:left"><pre class="verbatim"># SWI Prolog file
| ".*\\.pl" -> frame open:"%" line:"%" close:"%"
| ".*\\.pl" -> skip multiline_match:"#!.*" multiline_match:":-.*"
</pre></td></tr>
</table>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 4: Example of a configuration file for skipping the shebang line,
as well as lines containing Prolog directives, such as Unicode usage.</td></tr>
</table></div>
<a id="figure:python-example"></a>
<div class="center"><hr class="floatrule"></div></blockquote><p>Figure <a href="#figure%3Apython-example">4</a> shows an example of configuration file
that can used for ‘<span style="font-family:monospace">SWI prolog</span>‘ files:
for a ‘<span style="font-family:monospace">.pl</span>‘ file starting with the following three first lines,
‘<span style="font-family:monospace">headache</span>‘ considers that the header must start just after the first two lines:
</p><pre>
#!/usr/bin/env swipl
:- encoding(utf8).
% remainder of the file, that can be after the header
</pre><!--CUT END -->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<hr class="horizontal-rule" style="height:2px"><blockquote class="quote"><em>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</em><a href="http://hevea.inria.fr/index.html"><em>H</em><em><span style="font-size:small"><sup>E</sup></span></em><em>V</em><em><span style="font-size:small"><sup>E</sup></span></em><em>A</em></a><em>.</em></blockquote></body>
</html>
|
