CLIAPP(5)							File Formats Manual							 CLIAPP(5)

NAME

       cliapp - config file and option conventions for Python command line framework

DESCRIPTION

       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 cliapp.

       Configuration file variables and command line options are handled by 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, --help outputs a short help text, listing all the available options, and --dump-config outputs a list  of  cur-
       rent configuration settings.

       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.  (--dump-config is
       one of these, so use it at the end of the command line only.)

       Some settings may have aliases, which can be only a single character, and in that case they're parsed as single-character option names.

       Some applications have 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 subcom-
       mands.  Thus, --foo means the same thing, regardless of what subcommand is being used.

   Configuration files
       Configuration files use INI file syntax.  All the settings are in the [config] section.	Other sections are allowed, but it is  up  to  the
       application to give meaning to them.

       Multiple  configuration	files  may be read.  Settings from later ones override settings from earlier ones.  Options override settings from
       the configuration files.

   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 val-
       ues 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  com-
       mas.

       Example:

	      [config]
	      pattern = foo, bar, foobar

   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 yes, on, true, or the number 1, the set-
       ting is turned on.  Any other value means it is turned off.

	      [config]
	      verbose = true
	      attack-kittens = no

       This turns the verbose setting on, but does not launch attack kittens.

   Logging and log files
       Programs  using	cliapp automatically support several options for configuring the Python logging module.  See the --help output for options
       starting with log for details.  Logging can happen to a file or the system log.	Log files can be rotated automatically based on size.

       The --trace option enables additional debug logging, which is usually only useful for  programmers.   The  option  configures  the  tracing
       library	for  Python,  by Lars Wirzenius, which allows logging values of variables and other debug information in a way that is very light-
       weight 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.

   Python profiling support
       You  can run the application under the Python profiler (cProfile) by setting an environment variable.  The name of the variable is FOO_PRO-
       FILE, where FOO is the name of the program, as set by the application code or determined by cliapp automatically.  The value of	the  envi-
       ronment variable is the name of the file to which the resulting profile is to be written.

FILES

       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 progname.

       /etc/progname.conf
	      Global configuration file.

       /etc/progname/*.conf
	      More global configuration files.	These are read in ASCII sorted order.

       ~/.progname.conf
	      Per-user configuration file.

       ~/.config/progname/*.conf
	      More per-user configuration files.  Again, ASCII sorted order.

																	 CLIAPP(5)