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 current 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.)  Use -- on the  command  line  to  signal  the  end  of
       options: no arguments after that are considered to be option.

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

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

       For  every  boolean setting, two command line options are added.  If the setting is called
       foo, the option --foo will turn the setting on,  and  --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.

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

   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_PROFILE, where FOO is the name of the program,
       as set by the application code or determined by cliapp automatically.  The  value  of  the
       environment  variable  is  the  name  of  the file to which the resulting profile is to be
       written.

   Manual page generation
       cliapp can generate parts of a manual page: the SYNOPSIS and OPTIONS sections.   It  fills
       these  in automatically based on the subcommand and settings that a program supports.  Use
       the --generate-manpage=FILE option, which is added automatically by cliapp.  The FILE is a
       manual  page  marked up using the -man macros for troff(1).  It should have empty SYNOPSIS
       and OPTIONS sections, and cliapp will fill them in.  The output it to the standard output.

       For example:

              foo --generate-manpage=foo.1.in > foo.1

       You would keep the source code for the manual page in  foo.1.in  and  have  your  Makefile
       produce foo.1 as shown above.

   Subcommands
       cliapp provides a way for the application to have subcommands, in the style of git(1), for
       example.  If the application is called foo, then it  can  have  subcommands  such  as  foo
       search,  and  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.

       If  there  are  any subcommands, cliapp automatically adds the help subcommand.  It allows
       you to get the help text for a specific subommand: foo help print, for example.

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)