==============
gatherer specs
==============

WORK IN PROGRESS

/When a command is expected, the line "#X#" is printed, where X is the number of
/the request, starting a 0 and incremented after each processed request.
[test_incrementing_counter]

/Requests are spanned on multiple lines. The first line is the command, the
/following lines are parameters (one parameter per line unless stated otherwise).
[statement]

/Requests are all blocking. As they are read from stdin using readline(),
/they can be buffered in stdin.
[test_queuecommands]

/When the number of parameters or returns is variable, it should be indicated
/first.
/When a parameter or returned value is not one line of printable characters,
/its length as returned by len() should be indicated first.
[statement]

/When gatherer is expected to write in a file, its parent directory should exist
/and it will be opened with the "w" flag (unless stated otherwise).
[statement]

/No timeout handling should be implemented in gatherer.
[statement]

SIGINT should stop the current request parsing or execution,
write '#X# INTERRUPTED' to stderr where X is the number of the request,
then continue the normal flow of execution including incrementing the request
number.

/stderr is only used:
/- by Python to display exceptions;
/- to print "ALIVE" when SIGUSR1 is received or after a "ping" request;
/- to print "UNKNOWN COMMAND" when a command is unknown;
/- to print "INTERRUPTED #X#" when a command is interrupted with SIGINT.
[statement(easy to prove wrong, hard to prove right)]

Requests
--------

/Command: "noop"
/Params:
/- None
/Action:
/- None
/Returns:
/- Nothing
[test_basic_noop]

/Command: "ping"
/Params:
/- None
/Action:
/- Prints "ALIVE" on stderr
/Returns:
/- Nothing
[test_basic_ping NEED(stderr is being used)]

/Command: "exit"
/Params:
/- None
/Action:
/- The gatherer process returns 0
/Returns:
/- Nothing
[test_exit]

/Command: "glob"
/Params:
/- The globbing pattern
/Action:
/- Performs a glob.glob()
/Returns:
/- On the first line, a number of results, n
/- On the following n lines, filenames, line by line
[test_basic_glob, test_empty_glob]

Command: "exec"
Params:
- The command to send to a shell
Action:
- Executes the command in a shell using subprocess.Popen
Returns:
- The return code of the command
- The length of its stdout output as return by len(), in decimal.
- Its stdout output, followed by a trailing '\n'
- The length of its stderr output as return by len(), in decimal.
- Its stderr output, followed by a trailing '\n'

Command: "cp"
-- to be defined after staring at the current sosreport code.

Command: "globcp"
-- to be defined after staring at the current sosreport code.