====
mach
====

Mach (German for *do*) is a generic command dispatcher for the command
line.

To use mach, you install the mach core (a Python package), create an
executable *driver* script (named whatever you want), and write mach
commands. When the *driver* is executed, mach dispatches to the
requested command handler automatically.

Features
========

On a high level, mach is similar to using argparse with subparsers (for
command handling). When you dig deeper, mach offers a number of
additional features:

Distributed command definitions
  With optparse/argparse, you have to define your commands on a central
  parser instance. With mach, you annotate your command methods with
  decorators and mach finds and dispatches to them automatically.

Command categories
  Mach commands can be grouped into categories when displayed in help.
  This is currently not possible with argparse.

Logging management
  Mach provides a facility for logging (both classical text and
  structured) that is available to any command handler.

Settings files
  Mach provides a facility for reading settings from an ini-like file
  format.

Components
==========

Mach is conceptually composed of the following components:

core
  The mach core is the core code powering mach. This is a Python package
  that contains all the business logic that makes mach work. The mach
  core is common to all mach deployments.

commands
  These are what mach dispatches to. Commands are simply Python methods
  registered as command names. The set of commands is unique to the
  environment mach is deployed in.

driver
  The *driver* is the entry-point to mach. It is simply an executable
  script that loads the mach core, tells it where commands can be found,
  then asks the mach core to handle the current request. The driver is
  unique to the deployed environment. But, it's usually based on an
  example from this source tree.

Project State
=============

mach was originally written as a command dispatching framework to aid
Firefox development. While the code is mostly generic, there are still
some pieces that closely tie it to Mozilla/Firefox. The goal is for
these to eventually be removed and replaced with generic features so
mach is suitable for anybody to use. Until then, mach may not be the
best fit for you.

.. toctree::
   :maxdepth: 1

   commands
   driver
   logging