XbMachine: libxmlb Reference Manual

## XbMachine XbMachine |

## Functions

gboolean | (*XbMachineOpcodeFixupFunc) ()
gboolean | (*XbMachineTextHandlerFunc) ()
gboolean | (*XbMachineMethodFunc) ()
XbMachine * | xb_machine_new ()
void | xb_machine_set_debug_flags ()
XbStack * | xb_machine_parse ()
XbStack * | xb_machine_parse_full ()
gboolean | xb_machine_run ()
void | xb_machine_add_opcode_fixup ()
void | xb_machine_add_text_handler ()
void | xb_machine_add_method ()
void | xb_machine_add_operator ()
XbOpcode * | xb_machine_opcode_func_new ()
gchar * | xb_machine_opcode_to_string ()
gchar * | xb_machine_opcodes_to_string ()
XbOpcode * | xb_machine_stack_pop ()
void | xb_machine_stack_push ()
void | xb_machine_stack_push_steal ()
void | xb_machine_stack_push_text ()
void | xb_machine_stack_push_text_static ()
void | xb_machine_stack_push_text_steal ()
void | xb_machine_stack_push_integer ()
void | xb_machine_set_stack_size ()
guint | xb_machine_get_stack_size ()

## Types and Values

#define | XB_TYPE_MACHINE
struct | XbMachineClass
enum | XbMachineDebugFlags
enum | XbMachineParseFlags
| XbMachine

## Description

## Functions

### XbMachineOpcodeFixupFunc ()

    gboolean
    (*XbMachineOpcodeFixupFunc) (XbMachine *self,
                                 XbStack *opcodes,
                                 gpointer user_data,
                                 GError **error);

### XbMachineTextHandlerFunc ()

    gboolean
    (*XbMachineTextHandlerFunc) (XbMachine *self,
                                 XbStack *opcodes,
                                 const gchar *text,
                                 gboolean *handled,
                                 gpointer user_data,
                                 GError **error);

### XbMachineMethodFunc ()

    gboolean
    (*XbMachineMethodFunc) (XbMachine *self,
                            XbStack *stack,
                            gboolean *result_unused,
                            gpointer exec_data,
                            gpointer user_data,
                            GError **error);

### xb_machine_new ()

    XbMachine *
    xb_machine_new (void);

Creates a new virtual machine.

#### Returns

a new XbMachine

Since: 0.1.1

### xb_machine_set_debug_flags ()

    void
    xb_machine_set_debug_flags (XbMachine *self,
                                XbMachineDebugFlags flags);

Sets the debug level of the virtual machine.

#### Parameters

self | a XbMachine |
flags | XbMachineDebugFlags, e.g. `XB_MACHINE_DEBUG_FLAG_SHOW_STACK` |

Since: 0.1.1

### xb_machine_parse ()

    XbStack *
    xb_machine_parse (XbMachine *self,
                      const gchar *text,
                      gssize text_len,
                      GError **error);

`xb_machine_parse` is deprecated and should not be used in newly-written code.

Parses an XPath predicate. Not all of XPath 1.0 or XPath 1.0 is supported, and new functions and mnemonics can be added using `xb_machine_add_method()` and `xb_machine_add_text_handler()`.

#### Parameters

self | a XbMachine |
text | predicate to parse, e.g. `contains(`text()`,'xyx')` |
text_len | length of `text` , or -1 if `text` is `NUL` terminated |
error | a GError, or `NULL` |

#### Returns

opcodes, or `NULL` on error.

[transfer full]

Since: 0.1.1

### xb_machine_parse_full ()

    XbStack *
    xb_machine_parse_full (XbMachine *self,
                           const gchar *text,
                           gssize text_len,
                           XbMachineParseFlags flags,
                           GError **error);

Parses an XPath predicate. Not all of XPath 1.0 or XPath 1.0 is supported, and new functions and mnemonics can be added using `xb_machine_add_method()` and `xb_machine_add_text_handler()`.

#### Parameters

self | a XbMachine |
text | predicate to parse, e.g. `contains(`text()`,'xyx')` |
text_len | length of `text` , or -1 if `text` is `NUL` terminated |
flags | XbMachineParseFlags, e.g. `XB_MACHINE_PARSE_FLAG_OPTIMIZE` |
error | a GError, or `NULL` |

#### Returns

opcodes, or `NULL` on error.

[transfer full]

Since: 0.1.4

### xb_machine_run ()

    gboolean
    xb_machine_run (XbMachine *self,
                    XbStack *opcodes,
                    gboolean *result,
                    gpointer exec_data,
                    GError **error);

Runs a set of opcodes on the virtual machine.

It is safe to call this function from a different thread to the one that created the XbMachine.

#### Parameters

self | a XbMachine |
opcodes | a XbStack of opcodes |
result | return status after running `opcodes` . | [out]
exec_data | per-run user data that is passed to all the XbMachineMethodFunc functions |
error | a GError, or `NULL` |

#### Returns

a new XbOpcode, or `NULL`

Since: 0.1.1

### xb_machine_add_opcode_fixup ()

    void
    xb_machine_add_opcode_fixup (XbMachine *self,
                                 const gchar *opcodes_sig,
                                 XbMachineOpcodeFixupFunc fixup_cb,
                                 gpointer user_data,
                                 GDestroyNotify user_data_free);

Adds an opcode fixup. Fixups can be used to optimize the stack of opcodes or to add support for a nonstandard feature, for instance supporting missing attributes to functions.

#### Parameters

self | a XbMachine |
opcodes_sig | signature, e.g. `INTE,TEXT` |
fixup_cb | callback |
user_data | user pointer to pass to `fixup_cb` |
user_data_free | a function which gets called to free `user_data` , or `NULL` |

Since: 0.1.1

### xb_machine_add_text_handler ()

    void
    xb_machine_add_text_handler (XbMachine *self,
                                 XbMachineTextHandlerFunc handler_cb,
                                 gpointer user_data,
                                 GDestroyNotify user_data_free);

Adds a text handler. This allows the virtual machine to support nonstandard encoding or shorthand mnemonics for standard functions.

#### Parameters

self | a XbMachine |
handler_cb | callback |
user_data | user pointer to pass to `handler_cb` |
user_data_free | a function which gets called to free `user_data` , or `NULL` |

Since: 0.1.1

### xb_machine_add_method ()

    void
    xb_machine_add_method (XbMachine *self,
                           const gchar *name,
                           guint n_opcodes,
                           XbMachineMethodFunc method_cb,
                           gpointer user_data,
                           GDestroyNotify user_data_free);

Adds a new function to the virtual machine. Registered functions can then be used as methods.

You need to add a custom function using `xb_machine_add_method()` before using methods that may reference it, for example `xb_machine_add_opcode_fixup()`.

#### Parameters

self | a XbMachine |
name | function name, e.g. `contains` |
n_opcodes | minimum number of opcodes required on the stack |
method_cb | function to call |
user_data | user pointer to pass to `method_cb` , or `NULL` |
user_data_free | a function which gets called to free `user_data` , or `NULL` |

Since: 0.1.1

### xb_machine_add_operator ()

    void
    xb_machine_add_operator (XbMachine *self,
                             const gchar *str,
                             const gchar *name);

Adds a new operator to the virtual machine. Operators can then be used instead of explicit methods like ``eq()``.

You need to add a custom operator using `xb_machine_add_operator()` before using `xb_machine_parse()`. Common operators like `&lt;=` and `=` are built-in and do not have to be added manually.

#### Parameters

self | a XbMachine |
str | operator string, e.g. `==` |
name | function name, e.g. `contains` |

Since: 0.1.1

### xb_machine_opcode_func_new ()

    XbOpcode *
    xb_machine_opcode_func_new (XbMachine *self,
                                const gchar *func_name);

Creates a new opcode for a registered function. Some standard opcodes are registered by default, for instance `eq` or `ge`. Other opcodes have to be added using `xb_machine_add_method()`.

#### Parameters

self | a XbMachine |
func_name | function name, e.g. `eq` |

#### Returns

a new XbOpcode, or `NULL`

Since: 0.1.1

### xb_machine_opcode_to_string ()

    gchar *
    xb_machine_opcode_to_string (XbMachine *self,
                                 XbOpcode *opcode);

`xb_machine_opcode_to_string` is deprecated and should not be used in newly-written code.

Returns a string representing the specific opcode.

#### Parameters

self | a XbMachine |
opcode | a XbOpcode |

#### Returns

text

Since: 0.1.1

### xb_machine_opcodes_to_string ()

    gchar *
    xb_machine_opcodes_to_string (XbMachine *self,
                                  XbStack *opcodes);

`xb_machine_opcodes_to_string` is deprecated and should not be used in newly-written code.

Returns a string representing a set of opcodes.

#### Parameters

self | a XbMachine |
opcodes | a XbStack of opcodes |

#### Returns

text

Since: 0.1.1

### xb_machine_stack_pop ()

    XbOpcode *
    xb_machine_stack_pop (XbMachine *self,
                          XbStack *stack);

Pops an opcode from the stack.

#### Parameters

self | a XbMachine |
stack | a XbStack |

#### Returns

a new XbOpcode, or `NULL`.

[transfer full]

Since: 0.1.1

### xb_machine_stack_push ()

    void
    xb_machine_stack_push (XbMachine *self,
                           XbStack *stack,
                           XbOpcode *opcode);

Adds an opcode to the stack.

#### Parameters

self | a XbMachine |
stack | a XbStack |
opcode | a XbOpcode |

Since: 0.1.1

### xb_machine_stack_push_steal ()

    void
    xb_machine_stack_push_steal (XbMachine *self,
                                 XbStack *stack,
                                 XbOpcode *opcode);

Adds an stolen opcode to the stack.

#### Parameters

self | a XbMachine |
stack | a XbStack |
opcode | a XbOpcode |

Since: 0.1.4

### xb_machine_stack_push_text ()

    void
    xb_machine_stack_push_text (XbMachine *self,
                                XbStack *stack,
                                const gchar *str);

Adds a text literal to the stack, copying `str` .

#### Parameters

self | a XbMachine |
stack | a XbStack |
str | text literal |

Since: 0.1.1

### xb_machine_stack_push_text_static ()

    void
    xb_machine_stack_push_text_static (XbMachine *self,
                                       XbStack *stack,
                                       const gchar *str);

Adds static text literal to the stack.

#### Parameters

self | a XbMachine |
stack | a XbStack |
str | text literal |

Since: 0.1.1

### xb_machine_stack_push_text_steal ()

    void
    xb_machine_stack_push_text_steal (XbMachine *self,
                                      XbStack *stack,
                                      gchar *str);

Adds a stolen text literal to the stack.

#### Parameters

self | a XbMachine |
stack | a XbStack |
str | text literal |

Since: 0.1.1

### xb_machine_stack_push_integer ()

    void
    xb_machine_stack_push_integer (XbMachine *self,
                                   XbStack *stack,
                                   guint32 val);

Adds an integer literal to the stack.

#### Parameters

self | a XbMachine |
stack | a XbStack |
val | integer literal |

Since: 0.1.1

### xb_machine_set_stack_size ()

    void
    xb_machine_set_stack_size (XbMachine *self,
                               guint stack_size);

Sets the maximum stack size used for the machine.

The stack size will be affective for new jobs started with `xb_machine_run()` and `xb_machine_parse()`.

#### Parameters

self | a XbMachine |
stack_size | integer |

Since: 0.1.3

### xb_machine_get_stack_size ()

    guint
    xb_machine_get_stack_size (XbMachine *self);

Gets the maximum stack size used for the machine.

#### Parameters

self | a XbMachine |

#### Returns

integer

Since: 0.1.3

## Types and Values

### XB_TYPE_MACHINE

    #define             XB_TYPE_MACHINE

### struct XbMachineClass

    struct XbMachineClass {
    	GObjectClass			 parent_class;
    };

### enum XbMachineDebugFlags

The flags to control the amount of debugging is generated.

#### Members

XB_MACHINE_DEBUG_FLAG_NONE |  |
XB_MACHINE_DEBUG_FLAG_SHOW_STACK |  |
XB_MACHINE_DEBUG_FLAG_SHOW_PARSING |  |
XB_MACHINE_DEBUG_FLAG_SHOW_OPTIMIZER |  |

### enum XbMachineParseFlags

The flags to control the parsing behaviour.

#### Members

XB_MACHINE_PARSE_FLAG_NONE |  |
XB_MACHINE_PARSE_FLAG_OPTIMIZE |  |

### XbMachine

    typedef struct _XbMachine XbMachine;