CattleInstruction

CattleInstruction — Brainfuck instruction

Synopsis

#include <cattle/cattle.h>

enum                CattleInstructionValue;
struct              CattleInstruction;
CattleInstruction * cattle_instruction_new              (void);
void                cattle_instruction_set_value        (CattleInstruction *instruction,
                                                         CattleInstructionValue value);
CattleInstructionValue cattle_instruction_get_value     (CattleInstruction *instruction);
void                cattle_instruction_set_quantity     (CattleInstruction *instruction,
                                                         gint quantity);
gint                cattle_instruction_get_quantity     (CattleInstruction *instruction);
void                cattle_instruction_set_next         (CattleInstruction *instruction,
                                                         CattleInstruction *next);
CattleInstruction * cattle_instruction_get_next         (CattleInstruction *instruction);
void                cattle_instruction_set_loop         (CattleInstruction *instruction,
                                                         CattleInstruction *loop);
CattleInstruction * cattle_instruction_get_loop         (CattleInstruction *instruction);

Object Hierarchy

  GObject
   +----CattleInstruction

Properties

  "loop"                     CattleInstruction*    : Read / Write
  "next"                     CattleInstruction*    : Read / Write
  "quantity"                 gint                  : Read / Write
  "value"                    CattleInstructionValue  : Read / Write

Description

A CattleInstruction represents a single Brainfuck instruction, repeated one or more times in a row.

Multiple instructions of the same type (i.e. multiple increment instruction) are grouped together to reduce memory usage and speed up execution.

Consider the following piece of Brainfuck code:

+++.-----

There are nine instructions: three increment instructions, a print instruction, and five decrement instructions.

Instead of creating nine separate objects, with all the involved overhead, Cattle creates just three objects (one with value CATTLE_INSTRUCTION_INCREASE, one with value CATTLE_INSTRUCTION_PRINT, and one with value CATTLE_INSTRUCTION_DECREASE) and set their quantity to three, one and five respectively.

Each instruction maintains a reference to the next instruction in the execution flow. If the instruction starts a loop (its value is CATTLE_INSTRUCTION_LOOP_BEGIN) it also holds a reference to the first instruction in the loop.

Details

enum CattleInstructionValue

typedef enum {
	CATTLE_INSTRUCTION_NONE        = 0x5F,
	CATTLE_INSTRUCTION_MOVE_LEFT   = 0x3C,
	CATTLE_INSTRUCTION_MOVE_RIGHT  = 0x3E,
	CATTLE_INSTRUCTION_INCREASE    = 0x2B,
	CATTLE_INSTRUCTION_DECREASE    = 0x2D,
	CATTLE_INSTRUCTION_LOOP_BEGIN  = 0x5B,
	CATTLE_INSTRUCTION_LOOP_END    = 0x5D,
	CATTLE_INSTRUCTION_READ        = 0x2C,
	CATTLE_INSTRUCTION_PRINT       = 0x2E,
	CATTLE_INSTRUCTION_DEBUG       = 0x23
} CattleInstructionValue;

Brainfuck instructions supported by Cattle, as gunichars.

CATTLE_INSTRUCTION_DEBUG is not part of the Brainfuck language, but it's often used for debugging and implemented in many interpreters, so it's included in Cattle as well.

CATTLE_INSTRUCTION_NONE

Do nothing

CATTLE_INSTRUCTION_MOVE_LEFT

Move the tape to the left

CATTLE_INSTRUCTION_MOVE_RIGHT

Move the tape to the right

CATTLE_INSTRUCTION_INCREASE

Increase the current value

CATTLE_INSTRUCTION_DECREASE

Decrease the current value

CATTLE_INSTRUCTION_LOOP_BEGIN

Execute the loop until the current value is zero, then proceed to the next instruction

CATTLE_INSTRUCTION_LOOP_END

Exit from the currently-executing loop

CATTLE_INSTRUCTION_READ

Get one character from the input and save its value at the current position

CATTLE_INSTRUCTION_PRINT

Send the current value to the output.

CATTLE_INSTRUCTION_DEBUG

Show debugging information. This usually means dumping the contents of the tape.

struct CattleInstruction

struct CattleInstruction;

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


cattle_instruction_new ()

CattleInstruction * cattle_instruction_new              (void);

Create and initialize a new instruction.

The newly-created instruction has a "quantity" of one, and its "value" is CATTLE_INSTRUCTION_NONE.

Returns :

a new CattleInstruction. [transfer full]

cattle_instruction_set_value ()

void                cattle_instruction_set_value        (CattleInstruction *instruction,
                                                         CattleInstructionValue value);

Set the value of instruction. Accepted values are from the CattleInstructionValue enumeration.

instruction :

a CattleInstruction

value :

value of instruction

cattle_instruction_get_value ()

CattleInstructionValue cattle_instruction_get_value     (CattleInstruction *instruction);

Get the value of instruction. See cattle_instruction_set_value().

instruction :

a CattleInstruction

Returns :

the value of instruction

cattle_instruction_set_quantity ()

void                cattle_instruction_set_quantity     (CattleInstruction *instruction,
                                                         gint quantity);

Set the number of times instruction has to be executed.

This value is used at runtime for faster execution, and allows to use less memory for storing the code.

instruction :

a CattleInstruction

quantity :

quantity of instruction

cattle_instruction_get_quantity ()

gint                cattle_instruction_get_quantity     (CattleInstruction *instruction);

Get the quantity of instruction. See cattle_instruction_set_quantity().

instruction :

a CattleInstruction

Returns :

the quantity of instruction

cattle_instruction_set_next ()

void                cattle_instruction_set_next         (CattleInstruction *instruction,
                                                         CattleInstruction *next);

Set the next instruction to be executed.

If instruction has value CATTLE_INSTRUCTION_LOOP_BEGIN, next will be executed only after the loop has returned.

instruction :

a CattleInstruction

next :

next CattleInstruction to execute, or NULL. [allow-none]

cattle_instruction_get_next ()

CattleInstruction * cattle_instruction_get_next         (CattleInstruction *instruction);

Get the next instruction.

Please note that the returned instruction might not be the next instruction in the execution flow: if instruction marks the beginning of a loop (its value is CATTLE_INSTRUCTION_LOOP_BEGIN), the returned instruction will be executed only after the loop has ended.

instruction :

a CattleInstruction

Returns :

the next instruction, or NULL. [transfer full]

cattle_instruction_set_loop ()

void                cattle_instruction_set_loop         (CattleInstruction *instruction,
                                                         CattleInstruction *loop);

Set the instructions to be executed in the loop.

This method should only be called on instructions whose value is CATTLE_INSTRUCTION_LOOP_BEGIN.

instruction :

a CattleInstruction

loop :

first CattleInstruction in the loop, or NULL. [allow-none]

cattle_instruction_get_loop ()

CattleInstruction * cattle_instruction_get_loop         (CattleInstruction *instruction);

Get the first instruction of the loop.

This method should only be called on instructions whose value is CATTLE_INSTRUCTION_LOOP_BEGIN.

instruction :

a CattleInstruction

Returns :

a CattleInstruction, or NULL. [transfer full]

Property Details

The "loop" property

  "loop"                     CattleInstruction*    : Read / Write

Instructions to be executed in the loop. Should be NULL unless the value of the instruction is CATTLE_INSTRUCTION_LOOP_BEGIN.

Changes to this property are not notified.


The "next" property

  "next"                     CattleInstruction*    : Read / Write

Next instruction in the execution flow. Can be NULL if there are no more instructions to be executed.

Changes to this property are not notified.


The "quantity" property

  "quantity"                 gint                  : Read / Write

Number of times the instruction has to be executed.

Changes to this property are not notified.

Allowed values: >= 0

Default value: 1


The "value" property

  "value"                    CattleInstructionValue  : Read / Write

Value of the instruction. Accepted values are in the CattleInstructionValue enumeration.

Changes to this property are not notified.

Default value: CATTLE_INSTRUCTION_NONE