## OrcProgram OrcProgram — Creating and manipulating Orc programs |

## Synopsis

                        OrcProgram;
    #define             ORC_N_CONSTANTS
    #define             ORC_N_RULE_SETS
    #define             ORC_N_TARGETS
    #define             ORC_PROGRAM_ERROR                   (program,
                                                             ...)
    OrcProgram *        orc_program_new                     (void);
    OrcProgram *        orc_program_new_dss                 (int size1,
                                                             int size2,
                                                             int size3);
    OrcProgram *        orc_program_new_as                  (int size1,
                                                             int size2);
    OrcProgram *        orc_program_new_ass                 (int size1,
                                                             int size2,
                                                             int size3);
    OrcProgram *        orc_program_new_ds                  (int size1,
                                                             int size2);
    void                orc_program_free                    (OrcProgram *program);
    const char *        orc_program_get_name                (OrcProgram *program);
    void                orc_program_set_name                (OrcProgram *program,
                                                             const char *name);
    int                 orc_program_add_temporary           (OrcProgram *program,
                                                             int size,
                                                             const char *name);
    int                 orc_program_add_source              (OrcProgram *program,
                                                             int size,
                                                             const char *name);
    int                 orc_program_add_destination         (OrcProgram *program,
                                                             int size,
                                                             const char *name);
    int                 orc_program_add_constant            (OrcProgram *program,
                                                             int size,
                                                             int value,
                                                             const char *name);
    int                 orc_program_add_accumulator         (OrcProgram *program,
                                                             int size,
                                                             const char *name);
    int                 orc_program_add_parameter           (OrcProgram *program,
                                                             int size,
                                                             const char *name);
    void                orc_program_append                  (OrcProgram *p,
                                                             const char *opcode,
                                                             int arg0,
                                                             int arg1,
                                                             int arg2);
    void                orc_program_append_str              (OrcProgram *p,
                                                             const char *opcode,
                                                             const char *arg0,
                                                             const char *arg1,
                                                             const char *arg2);
    void                orc_program_append_ds               (OrcProgram *program,
                                                             const char *opcode,
                                                             int arg0,
                                                             int arg1);
    void                orc_program_append_ds_str           (OrcProgram *p,
                                                             const char *opcode,
                                                             const char *arg0,
                                                             const char *arg1);
    OrcCompileResult    orc_program_compile                 (OrcProgram *p);
    OrcCompileResult    orc_program_compile_for_target      (OrcProgram *p,
                                                             OrcTarget *target);
    OrcCompileResult    orc_program_compile_full            (OrcProgram *p,
                                                             OrcTarget *target,
                                                             unsigned int flags);
    const char *        orc_program_get_asm_code            (OrcProgram *program);

    int                 orc_program_find_var_by_name        (OrcProgram *program,
                                                             const char *name);
    int                 orc_program_allocate_register       (OrcProgram *program,
                                                             int is_data);
    int                 orc_program_dup_temporary           (OrcProgram *program,
                                                             int i,
                                                             int j);

## Description

## Details

### OrcProgram

    typedef struct {
    } OrcProgram;

The OrcProgram structure has no public members

### ORC_N_CONSTANTS

    #define ORC_N_CONSTANTS 20

### ORC_N_RULE_SETS

    #define ORC_N_RULE_SETS 10

### ORC_N_TARGETS

    #define ORC_N_TARGETS 10

### ORC_PROGRAM_ERROR()

    #define             ORC_PROGRAM_ERROR(program, ...)

`program` : |
`...` : |

### orc_program_new ()

    OrcProgram *        orc_program_new                     (void);

Create a new OrcProgram. The program should be freed using @`orc_program_free()`.

Returns : | a pointer to an OrcProgram structure

### orc_program_new_dss ()

    OrcProgram *        orc_program_new_dss                 (int size1,
                                                             int size2,
                                                             int size3);

Create a new OrcProgram, with a destination named "d1" and two sources named "s1" and "s2".

`size1` : | size of destination array members
`size2` : | size of first source array members
`size3` : | size of second source array members
Returns : | a pointer to an OrcProgram structure

### orc_program_new_as ()

    OrcProgram *        orc_program_new_as                  (int size1,
                                                             int size2);

Create a new OrcProgram, with an accumulator named "a1" and one source named "s1".

`size1` : | size of destination array members
`size2` : | size of source array members
Returns : | a pointer to an OrcProgram structure

### orc_program_new_ass ()

    OrcProgram *        orc_program_new_ass                 (int size1,
                                                             int size2,
                                                             int size3);

Create a new OrcProgram, with an accumulator named "a1" and two source named "s1" and "s2".

`size1` : | size of destination array members
`size2` : | size of first source array members
`size3` : | size of second source array members
Returns : | a pointer to an OrcProgram structure

### orc_program_new_ds ()

    OrcProgram *        orc_program_new_ds                  (int size1,
                                                             int size2);

Create a new OrcProgram, with a destination named "d1" and one source named "s1".

`size1` : | size of destination array members
`size2` : | size of source array members
Returns : | a pointer to an OrcProgram structure

### orc_program_free ()

    void                orc_program_free                    (OrcProgram *program);

Frees an OrcProgram.

`program` : | a pointer to an OrcProgram structure

### orc_program_get_name ()

    const char *        orc_program_get_name                (OrcProgram *program);

Gets the name of the program. The string is valid until the name is changed or the program is freed.

`program` : | a pointer to an OrcProgram structure
Returns : | a character string

### orc_program_set_name ()

    void                orc_program_set_name                (OrcProgram *program,
                                                             const char *name);

Sets the name of the program. The string is copied.

`program` : | a pointer to an OrcProgram structure
`name` : | string to set the name to

### orc_program_add_temporary ()

    int                 orc_program_add_temporary           (OrcProgram *program,
                                                             int size,
                                                             const char *name);

Creates a new variable holding temporary values.

`program` : | a pointer to an OrcProgram structure
`size` : | size of data values
`name` : | name of variable
Returns : | the index of the new variable

### orc_program_add_source ()

    int                 orc_program_add_source              (OrcProgram *program,
                                                             int size,
                                                             const char *name);

Creates a new variable representing a source array.

`program` : | a pointer to an OrcProgram structure
`size` : | size of data values
`name` : | name of variable
Returns : | the index of the new variable

### orc_program_add_destination ()

    int                 orc_program_add_destination         (OrcProgram *program,
                                                             int size,
                                                             const char *name);

Creates a new variable representing a destination array.

`program` : | a pointer to an OrcProgram structure
`size` : | size of data values
`name` : | name of variable
Returns : | the index of the new variable

### orc_program_add_constant ()

    int                 orc_program_add_constant            (OrcProgram *program,
                                                             int size,
                                                             int value,
                                                             const char *name);

Creates a new variable representing a constant value.

`program` : | a pointer to an OrcProgram structure
`size` : | size of data value
`value` : | the value
`name` : | name of variable
Returns : | the index of the new variable

### orc_program_add_accumulator ()

    int                 orc_program_add_accumulator         (OrcProgram *program,
                                                             int size,
                                                             const char *name);

Creates a new variable representing an accumulator.

`program` : | a pointer to an OrcProgram structure
`size` : | size of data value
`name` : | name of variable
Returns : | the index of the new variable

### orc_program_add_parameter ()

    int                 orc_program_add_parameter           (OrcProgram *program,
                                                             int size,
                                                             const char *name);

Creates a new variable representing a scalar parameter.

`program` : | a pointer to an OrcProgram structure
`size` : | size of data value
`name` : | name of variable
Returns : | the index of the new variable

### orc_program_append ()

    void                orc_program_append                  (OrcProgram *p,
                                                             const char *opcode,
                                                             int arg0,
                                                             int arg1,
                                                             int arg2);

`p` : |
`opcode` : |
`arg0` : |
`arg1` : |
`arg2` : |

### orc_program_append_str ()

    void                orc_program_append_str              (OrcProgram *p,
                                                             const char *opcode,
                                                             const char *arg0,
                                                             const char *arg1,
                                                             const char *arg2);

Appends an instruction to the program, with arguments `arg0`, `arg1`, and `arg2`. The instruction must take 3 operands.

`p` : |
`opcode` : |
`arg0` : | name of first variable
`arg1` : | name of second variable
`arg2` : | name of third variable

### orc_program_append_ds ()

    void                orc_program_append_ds               (OrcProgram *program,
                                                             const char *opcode,
                                                             int arg0,
                                                             int arg1);

Appends an instruction to the program, with arguments `arg0`, `arg1`, and `arg2`. The instruction must take 3 operands.

`program` : | a pointer to an OrcProgram structure
`opcode` : |
`arg0` : | index of first variable
`arg1` : | index of second variable

### orc_program_append_ds_str ()

    void                orc_program_append_ds_str           (OrcProgram *p,
                                                             const char *opcode,
                                                             const char *arg0,
                                                             const char *arg1);

Appends an instruction to the program, with arguments `arg0` and `arg2`. The instruction must take 2 operands.

`p` : |
`opcode` : |
`arg0` : | name of first variable
`arg1` : | name of second variable

### orc_program_compile ()

    OrcCompileResult    orc_program_compile                 (OrcProgram *p);

Compiles an Orc program for the current CPU. If successful, executable code for the program was generated and can be executed.

The return value indicates various levels of success or failure. Success can be determined by checking for a true value of the macro `ORC_COMPILE_RESULT_IS_SUCCESSFUL()` on the return value. This indicates that executable code was generated. If the macro `ORC_COMPILE_RESULT_IS_FATAL()` on the return value evaluates to true, then there was a syntactical error in the program. If the result is neither successful nor fatal, the program can still be emulated.

`p` : |
Returns : | an OrcCompileResult

### orc_program_compile_for_target ()

    OrcCompileResult    orc_program_compile_for_target      (OrcProgram *p,
                                                             OrcTarget *target);

Compiles an Orc program for the given target, using the default target flags for that target.

`p` : |
`target` : |
Returns : | an OrcCompileResult

### orc_program_compile_full ()

    OrcCompileResult    orc_program_compile_full            (OrcProgram *p,
                                                             OrcTarget *target,
                                                             unsigned int flags);

Compiles an Orc program for the given target, using the given target flags.

`p` : |
`target` : |
`flags` : |
Returns : | an OrcCompileResult

### orc_program_get_asm_code ()

    const char *        orc_program_get_asm_code            (OrcProgram *program);

Returns a character string containing the assembly code created by compiling the program. This string is valid until the program is compiled again or the program is freed.

`program` : | a pointer to an OrcProgram structure
Returns : | a character string

### orc_program_find_var_by_name ()

    int                 orc_program_find_var_by_name        (OrcProgram *program,
                                                             const char *name);

Finds the variable with the name `name`. If no variable with the given name exists in the program, -1 is returned.

`program` : | a pointer to an OrcProgram structure
`name` : | name of instruction
Returns : | the index of the variable

### orc_program_allocate_register ()

    int                 orc_program_allocate_register       (OrcProgram *program,
                                                             int is_data);

`program` : |
`is_data` : |
Returns : |

### orc_program_dup_temporary ()

    int                 orc_program_dup_temporary           (OrcProgram *program,
                                                             int i,
                                                             int j);

Internal function.

`program` : | a pointer to an OrcProgram structure
`i` : |
`j` : | index
Returns : | the index of the new variable