README.dialog

otopi -- Dialog
===============

ABOUT
-----

The dialog is the interface used to interact with manager.

This document outlines the 'machine' dialog which is design to interact
with software.

The interface is designed to be semi-human dialog to enable human
interaction.

The interface can be selected using the following environment:

 DIALOG/dialect=str:machine

COMMAND LINE
------------

The command line interface is prompted by using the following environment:

 DIALOG/customization=bool:True

List:

abort - Abort process
env-get - Get environment variable
env-query - Query environment variable
env-query-multi - Get multi string environment variable
env-set - Set environment variable
env-show - Display environment
exception-show - show exception information
help - Display available commands
install - Install software
log - Retrieve log file
noop - No operation
quit - Quit

Usage: env-get [options]

Options:
  -h, --help         This text
  -k KEY, --key=KEY  Environment key

Usage: env-query [options]

Options:
  -h, --help         This text
  -k KEY, --key=KEY  Environment key

Usage: env-query-multi [options]

Options:
  -h, --help         This text
  -k KEY, --key=KEY  Environment key

Usage: env-set [options]

Options:
  -h, --help            This text
  -k KEY, --key=KEY     Environment key
  -t TYPE, --type=TYPE  Variable type ('bool', 'int', 'str'), default 'str'
  -v VALUE, --value=VALUE
                        Variable value

ITERATIVE DIALOG VARIABLES
--------------------------

CUSTOMIZATION_COMMAND
    Query customization command.

TERMINATION_COMMAND
    Query termination command.

TIME
    Query current time.

INTERACTIVE CONFIRMATIONS
-------------------------

GPG_KEY
    Confirm trust of GPG key.

MACHINE DIALECT
---------------

Note

^#+ (.*)\n$
    Group1 - message.

Every line that begins with '#' is ignored by manager. Notes are
used to interact with humans.

Terminate

^***TERMINATE\n$

Terminate dialog.

Log

^\*\*\*L:INFO (.*)\n$
^\*\*\*L:WARNING (.*)\n$
^\*\*\*L:ERROR (.*)\n$
    Group1 - message.

Query

Each query is framed between
^\*\*\%QStart: (?P<NAME>.*)\n
and
^\*\*\%QEnd: (?P<NAME>.*)\n

The query frame will always include:
^\*\*\*Q:(?P<TYPE>STRING|MULTI-STRING|VALUE) (?P=NAME)\s?(?P<BOUNDARY>.*)\s?(?P<ABOUNDARY>.*)\n$
    NAME: Variable name
    TYPE: Query type

The query frame can contain additional query options like:
^\*\*\%QDefault: (?P<DValue>.*)\n$
    DValue: default value as string

^\*\*\%QValidValues: (?P<ValidValues>.*)\n$
    ValidValues: valid value list. '\\' in each value is replaced with '\\\\',
                 '|' is replaced with '\\|', and values are separated with '|'.

^\*\*\%QHidden: (?P<Hidden>.*)\n$
    Hidden: TRUE or FALSE. If TRUE, the reply should be hidden.

^\*\*\*Q:STRING (.*)\n$
    Group1: variable name.
    Single line response.

^\*\*\*Q:MULTI-STRING (.*) (.*) (.*)\n$
    Group1: variable name.
    Group2: boundary.
    Group3: abort boundary.
    Multiple line response.
    Boundary at own line marks end.

^\*\*\*Q:VALUE (.*)\n$
    Group1: variable name.
    Response:
        ^VALUE (.*)=(.*):(.*)\n$
        Group1: variable name.
        Group2: variable type.
        Group3: variable value.
    Response:
        ^ABORT (.*)\n$
        Group1: variable name.

The query frame may include other output, including a note to the user.
In practice, relevant notes to the user may also be output prior to the
query frame.

Confirm

^\*\*\*CONFIRM (.*) (.*)$
    Group1: id.
    Group2: description.
    Response:
        ^CONFIRM (.*)=(yes|no)\n$
        Group1: id
        Group2: response
    Response:
        ^ABORT (.*)\n$
        Group1: variable name.

Display

^\*\*\*D:VALUE (.*)=(.*):(.*)\n$
    Group1: variable name.
    Group2: type.
    Group3: value.

^\*\*\*D:MULTI-STRING (.*) (.*)\n$
(^.*\n$)*
^(.*)\n$
    Group1: variable name.
    Group2: boundary.
    Group3: content.
    Group4: boundary.