Basics

Cattle uses an I/O mechanism which allows a huge degree of flexibility, while remaining relatively simple.

Input, output and debug are triggered by a CattleInterpreter with the emission of a signal: "input-request", "output-request" and "debug-request" respectively. Suitable callbacks can be connected to the emission of these signals to customize the way I/O is performed.

Default signal handlers are builtin for all the I/O operations, removing the need to write custom routines if one doesn't have specific needs.

Only the first connected handler will be executed on signal emission. Connecting a custom handler, on the other hand, prevents the default signal handler from running.

All signal handlers take a GError as last argument, and are required to fill it with a detailed error message in case of failed operation.

Input

gboolean
input_request_handler (CattleInterpreter    *interpreter,
                       gchar               **input,
                       GError              **error,
                       gpointer              data)
        

Input works on a per-line basis: the signal handler must retrieve a full, null-terminated line of input, including the trailing newline character, and feed it to the interpreter.

If it is not possible to retrieve the whole line in a single step, a part of it can be passed to the interpreter. The string must be null-terminated anyway.

The interpreter doesn't make a copy of the passed-in string, so the handler must make sure it will be accessible as long as the interpreter needs it.

No allocator choice is forced on the user; however, the handler is responsible of releasing the allocated buffer when the interpreter is done processing it. This condition is notified to the handler passing a non-null pointer as the second argument.

When the whole input has been consumed, the handler must set to NULL the pointer to let the interpreter know no more input is available.

Output

gboolean
output_request_handler (CattleInterpreter    *interpreter,
                        gchar                 output,
                        GError              **error,
                        gpointer              data)
        

Output is performed one character at time, even though the user might choose to buffer a line or even the whole output if it makes sense to do so.

Debug

gboolean
debug_request_handler (CattleInterpreter    *interpreter,
                       GError              **error,
                       gpointer              data)
        

The debug handler is required to dump the content of the tape; the tape can be obtained from the interpreter using the cattle_interpreter_get_tape() method.

After the handler has run, the tape must be in the same exact state it was before the signal emission, including the position. The best way to ensure it is to use cattle_tape_push_bookmark() and cattle_tape_pop_bookmark().

Caveats

The default signal handlers use the stdio I/O functions, so if you are not overriding all of them with custom implementations, you should not use raw I/O functions on stdin, stdout and stderr.