CattleInterpreter: Cattle Reference Manual

## CattleInterpreter CattleInterpreter — Brainfuck interpreter |

## Functions

CattleInterpreter * | cattle_interpreter_new ()
gboolean | cattle_interpreter_run ()
void | cattle_interpreter_feed ()
void | cattle_interpreter_set_configuration ()
CattleConfiguration * | cattle_interpreter_get_configuration ()
void | cattle_interpreter_set_program ()
CattleProgram * | cattle_interpreter_get_program ()
void | cattle_interpreter_set_tape ()
CattleTape * | cattle_interpreter_get_tape ()
gboolean | (*CattleInputHandler) ()
void | cattle_interpreter_set_input_handler ()
gboolean | (*CattleOutputHandler) ()
void | cattle_interpreter_set_output_handler ()
gboolean | (*CattleDebugHandler) ()
void | cattle_interpreter_set_debug_handler ()

## Properties

CattleConfiguration * | configuration | Read / Write
CattleProgram * | program | Read / Write
CattleTape * | tape | Read / Write

## Types and Values

struct | CattleInterpreter

## Object Hierarchy

        GObject
        ╰── CattleInterpreter

## Includes

    #include <cattle/cattle.h>

## Description

An instance of CattleInterpreter represents a Brainfuck interpreter, that is, an object which is capable of executing a CattleProgram.

CattleInterpreter handles all the aspects of execution, including input and output. It also hides all the details to the user, who only needs to initialize the interpreter and call `cattle_interpreter_run()` to execute a Brainfuck program.

The behaviour of an interpreter can be modified by providing a suitable CattleConfiguration object.

Once initialized, a CattleInterpreter can run the assigned program as many times as needed; the memory tape, however, is not automatically cleared between executions.

## Functions

### cattle_interpreter_new ()

    CattleInterpreter *
    cattle_interpreter_new (void);

Create and initialize a new interpreter.

#### Returns

a new CattleInterpreter.

[transfer full]

### cattle_interpreter_run ()

    gboolean
    cattle_interpreter_run (CattleInterpreter *interpreter,
                            GError **error);

Make the interpreter run the loaded program.

#### Parameters

interpreter | a CattleInterpreter |
error | return location for a GError. | [allow-none]

#### Returns

`TRUE` on success, `FALSE` otherwise

### cattle_interpreter_feed ()

    void
    cattle_interpreter_feed (CattleInterpreter *interpreter,
                             CattleBuffer *input);

Feed `interpreter` with more input.

This method is meant to be used inside an input handler assigned to `interpreter` ; calling it in any other context is pointless, since the input is reset each time `cattle_interpreter_run()` is called.

#### Parameters

interpreter | a CattleInterpreter |
input | more input to be used by `interpreter` . | [transfer full]

### cattle_interpreter_set_configuration ()

    void
    cattle_interpreter_set_configuration (CattleInterpreter *interpreter,
                                          CattleConfiguration *configuration);

Set the configuration for `interpreter` .

The same configuration can be used for several interpreters, but modifying it after it has been assigned to an interpreter may result in undefined behaviour, and as such is discouraged.

#### Parameters

interpreter | a CattleInterpreter |
configuration | configuration for `interpreter` . | [transfer full]

### cattle_interpreter_get_configuration ()

    CattleConfiguration *
    cattle_interpreter_get_configuration (CattleInterpreter *interpreter);

Get the configuration for `interpreter` . See `cattle_interpreter_set_configuration()`.

#### Parameters

interpreter | a CattleInterpreter |

#### Returns

configuration for `interpreter` .

[transfer full]

### cattle_interpreter_set_program ()

    void
    cattle_interpreter_set_program (CattleInterpreter *interpreter,
                                    CattleProgram *program);

Set the program to be executed by `interpreter` .

A single program can be shared between multiple interpreters, as long as care is taken not to modify it after it has been assigned to any of them.

#### Parameters

interpreter | a CattleInterpreter |
program | a CattleProgram. | [transfer full]

### cattle_interpreter_get_program ()

    CattleProgram *
    cattle_interpreter_get_program (CattleInterpreter *interpreter);

Get the program for `interpreter` . See `cattle_interpreter_set_program()`.

#### Parameters

interpreter | a CattleInterpreter |

#### Returns

the program for `interpreter` .

[transfer full]

### cattle_interpreter_set_tape ()

    void
    cattle_interpreter_set_tape (CattleInterpreter *interpreter,
                                 CattleTape *tape);

Set the memory tape used by `interpreter` .

#### Parameters

interpreter | a CattleInterpreter |
tape | a CattleTape. | [transfer full]

### cattle_interpreter_get_tape ()

    CattleTape *
    cattle_interpreter_get_tape (CattleInterpreter *interpreter);

Get the memory tape used by `interpreter` . See `cattle_interpreter_set_tape()`.

#### Parameters

interpreter | a CattleInterpreter |

#### Returns

the memory tape for `interpreter` .

[transfer full]

### CattleInputHandler ()

    gboolean
    (*CattleInputHandler) (CattleInterpreter *interpreter,
                           gpointer data,
                           GError **error);

Handler for an input operation.

#### Parameters

interpreter | a CattleInterpreter |
data | user data passed to the handler |
error | return location for a GError |

#### Returns

`TRUE` on success, `FALSE` otherwise

### cattle_interpreter_set_input_handler ()

    void
    cattle_interpreter_set_input_handler (CattleInterpreter *interpreter,
                                          CattleInputHandler handler,
                                          gpointer user_data);

Set the input handler for `interpreter` .

The handler will be invoked every time `interpreter` needs to perform an input action; if `handler` is `NULL`, the default input handler will be used.

#### Parameters

interpreter | a CattleInterpreter |
handler | input handler, or `NULL`. | [scope notified][allow-none]
user_data | user data for `handler` . | [allow-none]

### CattleOutputHandler ()

    gboolean
    (*CattleOutputHandler) (CattleInterpreter *interpreter,
                            gint8 output,
                            gpointer data,
                            GError **error);

Handler for an output operation.

#### Parameters

interpreter | a CattleInterpreter |
output | a gchar to output |
data | user data passed to the handler |
error | return location for a GError |

#### Returns

`TRUE` on success, `FALSE` otherwise

### cattle_interpreter_set_output_handler ()

    void
    cattle_interpreter_set_output_handler (CattleInterpreter *interpreter,
                                           CattleOutputHandler handler,
                                           gpointer user_data);

Set the output handler for `interpreter` .

The handler will be invoked every time `interpreter` needs to perform an output action; if `handler` is `NULL`, the default output handler will be used.

#### Parameters

interpreter | a CattleInterpreter |
handler | output handler, or `NULL`. | [scope notified][allow-none]
user_data | user data for `handler` . | [allow-none]

### CattleDebugHandler ()

    gboolean
    (*CattleDebugHandler) (CattleInterpreter *interpreter,
                           gpointer data,
                           GError **error);

Handler for a debug operation.

#### Parameters

interpreter | a CattleInterpreter |
data | user data passed to the handler |
error | return location for a GError |

#### Returns

`TRUE` on success, `FALSE` otherwise

### cattle_interpreter_set_debug_handler ()

    void
    cattle_interpreter_set_debug_handler (CattleInterpreter *interpreter,
                                          CattleInputHandler handler,
                                          gpointer user_data);

Set the debug handler for `interpreter` .

The handler will be invoked every time `interpreter` needs to perform a debug action; if `handler` is `NULL`, the default debug handler will be used.

#### Parameters

interpreter | a CattleInterpreter |
handler | debug handler, or `NULL`. | [scope notified][allow-none]
user_data | user data for `handler` . | [allow-none]

## Types and Values

### struct CattleInterpreter

    struct CattleInterpreter;

Opaque data structure representing an interpreter. It should never be accessed directly.

## Property Details

### The `“configuration”` property

      “configuration”            CattleConfiguration *

Configuration used by the interpreter.

Changes to this property are not notified.

Owner: CattleInterpreter

Flags: Read / Write

### The `“program”` property

      “program”                  CattleProgram *

Program executed by the interpreter.

Changes to this property are not notified.

Owner: CattleInterpreter

Flags: Read / Write

### The `“tape”` property

      “tape”                     CattleTape *

Tape used to store the data needed by the program.

Changes to this property are not notified.

Owner: CattleInterpreter

Flags: Read / Write