==============
Using *behave*
==============

The command-line tool *behave* has a bunch of `command-line arguments`_ and is
also configurable using `configuration files`_.

Values defined in the configuration files are used as defaults which the
command-line arguments may override.


Command-Line Arguments
======================

You may see the same information presented below at any time using ``behave
-h``.

{cmdline}


Tag Expression
--------------

{tag_expression}


Configuration Files
===================

Configuration files for *behave* are called either ".behaverc" or
"behave.ini" (your preference) and are located in one of three places:

1. the current working directory (good for per-project settings),
2. your home directory ($HOME), or
3. on Windows, in the %APPDATA% directory.

If you are wondering where *behave* is getting its configuration defaults
from you can use the "-v" command-line argument and it'll tell you.

Confuguration files **must** start with the label "[behave]" and are
formatted in the Windows INI style, for example:

.. code-block:: ini
  
  [behave]
  format=plain
  logging_clear_handlers=yes
  logging_filter=-suds

The types possible are:

**text**
  This just assigns whatever text you supply to the configuration setting.

**boolean**
  This assigns a boolean value to the configuration setting. True values
  are "1", "yes", "true", and "on". False values are "0", "no", "false",
  and "off".

**text (multiple allowed)**
  These fields accept one or more values on new lines, for example a tag
  expression might look like:

  .. code-block:: ini

    tags=@foo,~@bar
         @zap

  which is the equivalent of the command-line usage::

    --tags @foo,~@bar --tags @zap.


Recognised Settings
-------------------

{config}


