summaryrefslogtreecommitdiff
path: root/cliapp.5
blob: 21ad2f6cc988cd693ad3e1a74b731ca1af575aca (plain)
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
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
.\" Copyright (C) 2011, 2012  Lars Wirzenius
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write to the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.TH CLIAPP 5
.SH NAME
cliapp \- config file and option conventions for Python command line framework
.SH DESCRIPTION
.B cliapp
is a Python programming framework for writing command line applications
for Unix-like operating systems.
This manual page describes the conventions for configuration files and
command line parsing provided by
.BR cliapp .
.PP
.I "Configuration file variables"
and
.I "command line options"
are handled by
.B cliapp
under a uniform abstraction:
every setting is available both in configuration files and command
line options.
There are a few settings,
provided by the framework itself,
which are only available on the command line.
For example,
.B \-\-help
outputs a short help text,
listing all the available options,
and
.B \-\-dump\-config
outputs a list of current configuration settings.
.PP
.I "Command line parsing"
follows GNU conventions:
short options start with a single dash,
long options with two dashes,
and options may be used anywhere on the command line.
The order of options versus non-options does not matter.
The exception is some of the options provided by the framework,
which are executed immediately when found,
and may be prevent the rest of the options from being parsed.
.RB ( \-\-dump\-config
is one of these,
so use it at the end of the command line only.)
Use
.B --
on the command line to signal the end of options:
no arguments after that are considered to be option.
.PP
Some settings may have aliases,
which can be only a single character,
and in that case they're parsed as single-character option names.
.PP
Some applications have
.IR subcommands ,
which means that the first non-option argument is used to tell the
application what to do.
This is similar to what many version control systems do, for example
CVS, svn, bzr, and git.
Options are global,
and are not specific to subcommands.
Thus,
.B \-\-foo
means the same thing,
regardless of what subcommand is being used.
.SS "Configuration files"
Configuration files use INI or YAML file syntax.
Files named
.I something.yaml
are in YAML syntax.
Everything else are in INI syntax.
An INI file might look like this:
.IP
.nf
[config]
foo = bar

[extra section]
yo = yoyo
.fi
.PP
The same file in YAML syntax would be:
.IP
.nf
config:
  foo: bar
"extra section":
  yo: yoyo
.fi
.PP
All the settings are in the
.B [config]
section.
Other sections are allowed,
but it is up to the application to give meaning to them.
.PP
Multiple configuration files may be read.
Settings from later ones override settings from earlier ones.
Options override settings from the configuration files.
.SS "String list settings in INI files"
Some settings may be a list of values (each value being a string).
For example,
there might be a setting for patterns to search for,
and multiple patterns are allowed.
On the command line,
that happens by using the option multiple times.
In the configuration file,
all values are given on one logical line,
separated by commas.
.PP
This is a non-standard extension to the INI file syntax.
.PP
To include an item that itself contains a comma,
surround the item with double quotes.
There is no way to escape double quotes.
.PP
Example:
.IP
.nf
[config]
pattern = foo, bar, foobar, "hello, world"
.fi
.PP
Note than in versions of cliapp prior to 1.20150829,
the command line option would also break values with commas.
This has since been fixed.
.PP
Configuration files in YAML use standard YAML syntax to express lists.
.SS "Expressing sizes in bytes"
Some options take a value that gives the size as bytes.
These take an optional unit suffix.
A plain integer is the size in bytes.
The following units are supported:
.TS
tab(:);
lb lb rb rb
l l n n.
suffix:meaning:factor:
_
k, kb:kilobyte:10**3:1000
m, mb:megabyte:10**6:1000000
g, gb:gigabyte:10**9:1000000000
t, tb:terabyte:10**12:1000000000000
_
ki, kib:kibibyte:2**10:1024
mi, mib:mebibyte:2**20:1048576
gi, gib:gibibyte:2**30:1073741824
ti, tib:tebibyte:2**40:1099511627776
.TE
.PP
Suffixes may be upper or lower case,
without change in meaning.
Note that "b" and "B" are identical,
and both mean byte, not bit.
.SS "Boolean (true/false or on/off or yes/no) settings"
When a setting can be either on or off,
it's called a Boolean setting.
Such settings are turned off by default,
and turned on if used on the command line.
In a configuration file,
they need to be set to a value:
if the value is one of
.BR yes ,
.BR on ,
.BR true ,
or the number 1,
the setting is turned on.
Any other value means it is turned off.
.PP
.IP
.nf
[config]
verbose = true
attack-kittens = no
.fi
.PP
This turns the verbose setting on,
but does not launch attack kittens.
.PP
For every boolean setting,
two command line options are added.
If the setting is called
.IR foo ,
the option
.I \-\-foo
will turn the setting on,
and
.I \-\-no\-foo
will turn it off.
The negation is only usable on the command line:
its purpose is to allow the command line to override a setting from the
configuration file.
.SS "Logging and log files"
Programs using
.B cliapp
automatically support several options for configuring the Python
.B logging
module.
See the
.B \-\-help
output for options starting with
.BR "log"
for details.
Logging can happen to a file or the system log.
Log files can be rotated automatically based on size.
.PP
The
.B \-\-trace
option enables additional debug logging,
which is usually only useful for programmers.
The option configures the
.B tracing
library for Python,
by Lars Wirzenius,
which allows logging values of variables and other debug information in a
way that is very lightweight when the tracing is turned off.
The option specifies for which source code files to turn on tracing.
The actual logging happens via the normal Python logging facilities,
at the debug level.
.SS "Python profiling support"
You can run the application under the Python profiler
.RB ( cProfile )
by setting an environment variable.
The name of the variable is
.BR FOO_PROFILE ,
where
.B FOO
is the name of the program,
as set by the application code or determined by
.B cliapp
automatically.
The value of the environment variable is the name of the file to which the
resulting profile is to be written.
.SS "Manual page generation"
.B cliapp
can generate parts of a manual page:
the
.I SYNOPSIS
and
.I OPTIONS
sections.
It fills these in automatically based on the subcommand and settings
that a program supports.
Use the
.BR \-\-generate\-manpage =\fIFILE
option,
which is added automatically by
.BR cliapp .
The
.I FILE
is a manual page marked up using
the
.B -man
macros for
.BR troff (1).
It should have empty
.I SYNOPSIS
and
.I OPTIONS
sections,
and
.B cliapp
will fill them in.
The output it to the standard output.
.PP
For example:
.PP
.RS
foo --generate-manpage=foo.1.in > foo.1
.RE
.PP
You would keep the source code for the manual page in
.I foo.1.in
and have your Makefile produce
.I foo.1
as shown above.
.SS "Subcommands"
.BR cliapp
provides a way for the application to have
.IR subcommands ,
in the style of
.BR git (1),
for example.
If the application is called
.IR foo ,
then it can have subcommands such as
.IR "foo search" ,
and
.IR "foo print" .
The application gets to define the name and meaning of each subcommand.
However,
all settings (options and configuration files) are global,
and can be used with all subcommands.
It is up to each subcommand what settings it obeys.
.PP
If there are any subcommands,
.B cliapp
automatically adds the
.B help
subcommand.
It allows you to get the help text for a specific subommand:
.IR "foo help print" ,
for example.
.SH FILES
.B cliapp
reads a list of configuration files at startup,
on behalf of the application.
The name of the application is included in the name.
In the filenames below,
the application name is
.IR progname .
.TP
.BR /etc/progname.conf
Global configuration file.
.TP
.BR /etc/progname/*.conf
More global configuration files.
These are read in ASCII sorted order.
.TP
.BR ~/.progname.conf
Per-user configuration file.
.TP
.BR ~/.config/progname/*.conf
More per-user configuration files.
Again, ASCII sorted order.
.PP
In addition, the XDG Base Directory specification is followed,
if the Python
.B python-xdg
library is installed.
In that case, environment variables can be set to set additional location
in which files are search for.
The fixed names above are always search;
the XDG ones are search additionally.