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
|
.\" Copyright (C) 2011 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.)
.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 file syntax.
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"
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 line,
separated by commas.
This is a non-standard extension to the INI file syntax.
There is no way to escape commas.
.PP
Example:
.IP
.nf
[config]
pattern = foo, bar, foobar
.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.
|
