CattleInstruction: Cattle Reference Manual

CattleInstruction

CattleInstruction — Brainfuck instruction

Functions

CattleInstruction *	cattle_instruction_new ()
void	cattle_instruction_set_value ()
CattleInstructionValue	cattle_instruction_get_value ()
void	cattle_instruction_set_quantity ()
gulong	cattle_instruction_get_quantity ()
void	cattle_instruction_set_next ()
CattleInstruction *	cattle_instruction_get_next ()
void	cattle_instruction_set_loop ()
CattleInstruction *	cattle_instruction_get_loop ()

Properties

CattleInstruction *	loop	Read / Write
CattleInstruction *	next	Read / Write
gulong	quantity	Read / Write
CattleInstructionValue	value	Read / Write

Types and Values

enum	CattleInstructionValue
struct	CattleInstruction

Object Hierarchy

    GEnum
    ╰── CattleInstructionValue
    GObject
    ╰── CattleInstruction

Includes

#include <cattle/cattle.h>

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.

Functions

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.

Parameters

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().

Parameters

instruction

a CattleInstruction

Returns

the value of instruction

cattle_instruction_set_quantity ()

void
cattle_instruction_set_quantity (CattleInstruction *instruction,
                                 gulong 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.

Parameters

instruction	a CattleInstruction
quantity	quantity of `instruction`

cattle_instruction_get_quantity ()

gulong
cattle_instruction_get_quantity (CattleInstruction *instruction);

Get the quantity of instruction . See cattle_instruction_set_quantity().

Parameters

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.

Parameters

instruction	a CattleInstruction
next	next CattleInstruction to execute, or `NULL`.	[allow-none][transfer full]

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.

Parameters

instruction

a CattleInstruction

Returns

the next instruction, or NULL.

[allow-none][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.

Parameters

instruction	a CattleInstruction
loop	first CattleInstruction in the loop, or `NULL`.	[allow-none][transfer full]

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.

Parameters

instruction

a CattleInstruction

Returns

a CattleInstruction, or NULL.

[allow-none][transfer full]

Types and Values

enum 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.

Members

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.

Property Details

The `“loop”` property

  “loop”                     CattleInstruction *

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.

Owner: CattleInstruction

Flags: Read / Write

The `“next”` property

  “next”                     CattleInstruction *

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.

Owner: CattleInstruction

Flags: Read / Write

The `“quantity”` property

  “quantity”                 gulong

Number of times the instruction has to be executed.

Changes to this property are not notified.

Owner: CattleInstruction

Flags: Read / Write

The `“value”` property

  “value”                    CattleInstructionValue

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

Changes to this property are not notified.

Owner: CattleInstruction

Flags: Read / Write

Default value: CATTLE_INSTRUCTION_NONE