Introduction
============

This document describes the calling interface ("driver") to guitone which can
be used to script guitone's dialog system.

The general calling convention is the following:

    $ <binary> exec <path> <function> [<args>]

where

    <binary>    is the path to the guitone binary (on Mac OS X the binary inside
                the application bundle, in guitone.app/Contents/MacOS)

    <path>      is the database file or workspace path you want guitone operate
                on (use "-" to denote that you want to call a dialog without a
                database / workspace affinity, f.e. the preferences dialog)

    <function>  is the name of the function you like to call

    <args>      are optional arguments to this function

There is a calling hierarchy which makes it possible to call all dialogs without
path affinity from a call with database affinity and likewise all dialogs with
database affinity from a call with workspace affinity. So the following three
calls lead to the same results, i.e. the preferences dialog is displayed,
(though for the latter two the given database file or workspace path must be
valid):

    $ guitone exec - showPreferences
    $ guitone exec database.mtn showPreferences
    $ guitone exec ~/workspace showPreferences


Available Dialogs
=================

If you call

    $ guitone exec

you'll receive a basic help message with all implemented methods and their
arguments. For now there is no further documentation available.


Known Bugs
==========

The dialog system might signal certain data back to the caller, f.e. the ID
of a committed revision or the path of a checked out workspace. These
information are logged as informative messages into the output, f.e.

21:54:01.807: info: src/GuitoneDriver.cpp:signalWithOneStringArgument:309: signalled, value: /Users/tommyd/foo

Currently there is no way to find out which signal actually dropped this
value, which is actually a Qt nuisance. I hope I can fix this in later
revisions.