CattleInterpreter

CattleInterpreter — Brainfuck interpreter

Synopsis

#include <cattle/cattle.h>

struct              CattleInterpreter;
CattleInterpreter * cattle_interpreter_new              (void);
gboolean            cattle_interpreter_run              (CattleInterpreter *interpreter,
                                                         GError **error);
void                cattle_interpreter_feed             (CattleInterpreter *interpreter,
                                                         const gchar *input);
void                cattle_interpreter_set_configuration
                                                        (CattleInterpreter *interpreter,
                                                         CattleConfiguration *configuration);
CattleConfiguration * cattle_interpreter_get_configuration
                                                        (CattleInterpreter *interpreter);
void                cattle_interpreter_set_program      (CattleInterpreter *interpreter,
                                                         CattleProgram *program);
CattleProgram *     cattle_interpreter_get_program      (CattleInterpreter *interpreter);
void                cattle_interpreter_set_tape         (CattleInterpreter *interpreter,
                                                         CattleTape *tape);
CattleTape *        cattle_interpreter_get_tape         (CattleInterpreter *interpreter);
gboolean            (*CattleInputHandler)               (CattleInterpreter *interpreter,
                                                         gpointer data,
                                                         GError **error);
void                cattle_interpreter_set_input_handler
                                                        (CattleInterpreter *interpreter,
                                                         CattleInputHandler handler,
                                                         gpointer user_data);
gboolean            (*CattleOutputHandler)              (CattleInterpreter *interpreter,
                                                         gchar output,
                                                         gpointer data,
                                                         GError **error);
void                cattle_interpreter_set_output_handler
                                                        (CattleInterpreter *interpreter,
                                                         CattleOutputHandler handler,
                                                         gpointer user_data);
gboolean            (*CattleDebugHandler)               (CattleInterpreter *interpreter,
                                                         gpointer data,
                                                         GError **error);
void                cattle_interpreter_set_debug_handler
                                                        (CattleInterpreter *interpreter,
                                                         CattleInputHandler handler,
                                                         gpointer user_data);

Object Hierarchy

  GObject
   +----CattleInterpreter

Properties

  "configuration"            CattleConfiguration*  : Read / Write
  "program"                  CattleProgram*        : Read / Write
  "tape"                     CattleTape*           : Read / Write

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.

Details

struct CattleInterpreter

struct CattleInterpreter;

Opaque data structure representing an interpreter. It should never be accessed directly; use the methods below instead.


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.

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,
                                                         const gchar *input);

Feed interpreter with more input.

This method is meant to be used inside an input handler assigned to interpreter; way is pointless, since the input is reset when cattle_interpreter_run() is called.

interpreter :

a CattleInterpreter

input :

more input to be used by interpreter, or NULL. [allow-none]

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.

interpreter :

a CattleInterpreter

configuration :

configuration for interpreter

cattle_interpreter_get_configuration ()

CattleConfiguration * cattle_interpreter_get_configuration
                                                        (CattleInterpreter *interpreter);

Get the configuration for interpreter. See cattle_interpreter_set_configuration().

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.

interpreter :

a CattleInterpreter

program :

a CattleProgram

cattle_interpreter_get_program ()

CattleProgram *     cattle_interpreter_get_program      (CattleInterpreter *interpreter);

Get the program for interpreter. See cattle_interpreter_set_program().

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.

interpreter :

a CattleInterpreter

tape :

a CattleTape

cattle_interpreter_get_tape ()

CattleTape *        cattle_interpreter_get_tape         (CattleInterpreter *interpreter);

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

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.

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.

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,
                                                         gchar output,
                                                         gpointer data,
                                                         GError **error);

Handler for an output operation.

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.

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.

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.

interpreter :

a CattleInterpreter

handler :

debug handler, or NULL. [scope notified][allow-none]

user_data :

user data for handler. [allow-none]

Property Details

The "configuration" property

  "configuration"            CattleConfiguration*  : Read / Write

Configuration used by the interpreter.

Changes to this property are not notified.


The "program" property

  "program"                  CattleProgram*        : Read / Write

Program executed by the interpreter.

Changes to this property are not notified.


The "tape" property

  "tape"                     CattleTape*           : Read / Write

Tape used to store the data needed by the program.

Changes to this property are not notified.