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:

    1
    +++.-----

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