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 ()
gboolean | xb_machine_run_with_bindings ()
void | xb_machine_add_opcode_fixup ()
void | xb_machine_add_text_handler ()
void | xb_machine_add_method ()
void | xb_machine_add_operator ()
gboolean | xb_machine_opcode_func_init ()
gboolean | xb_machine_stack_pop ()
gboolean | xb_machine_stack_push ()
gboolean | xb_machine_stack_push_text ()
gboolean | xb_machine_stack_push_text_static ()
gboolean | xb_machine_stack_push_text_steal ()
gboolean | 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);

`xb_machine_run` has been deprecated since version 0.3.0 and should not be used in newly-written code.

Use `xb_machine_run_with_bindings()` instead.

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

    gboolean
    xb_machine_run_with_bindings (XbMachine *self,
                                  XbStack *opcodes,
                                  XbValueBindings *bindings,
                                  gboolean *result,
                                  gpointer exec_data,
                                  GError **error);

Runs a set of opcodes on the virtual machine, using the bound values given in `bindings` to substitute for bound opcodes.

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 |
bindings | values bound to opcodes of type `XB_OPCODE_KIND_BOUND_INTEGER` or `XB_OPCODE_KIND_BOUND_TEXT`, or `NULL` if the query doesn’t need any bound values. | [nullable][transfer none]
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.3.0

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

The `method_cb` must not modify the stack it’s passed unless it’s going to succeed. In particular, if a method call is not optimisable, it must not modify the stack it’s passed.

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

    gboolean
    xb_machine_opcode_func_init (XbMachine *self,
                                 XbOpcode *opcode,
                                 const gchar *func_name);

Initialises a stack allocated XbOpcode for a registered function. Some standard functions are registered by default, for instance `eq` or `ge`. Other functions have to be added using `xb_machine_add_method()`.

#### Parameters

self | a XbMachine |
opcode | a stack allocated XbOpcode to initialise. | [out caller-allocates]
func_name | function name, e.g. `eq` |

#### Returns

`TRUE` if the function was found and the opcode initialised, `FALSE` otherwise

Since: 0.2.0

### xb_machine_stack_pop ()

    gboolean
    xb_machine_stack_pop (XbMachine *self,
                          XbStack *stack,
                          XbOpcode *opcode_out,
                          GError **error);

Pops an opcode from the stack.

#### Parameters

self | a XbMachine |
stack | a XbStack |
opcode_out | return location for the popped XbOpcode. | [out caller-allocates][optional]
error | a GError, or `NULL` |

#### Returns

`TRUE` if popping succeeded, `FALSE` if the stack was empty already

Since: 0.2.0

### xb_machine_stack_push ()

    gboolean
    xb_machine_stack_push (XbMachine *self,
                           XbStack *stack,
                           XbOpcode **opcode_out,
                           GError **error);

Pushes a new empty opcode onto the end of the stack. A pointer to the opcode is returned in `opcode_out` so that the caller can initialise it.

If the stack reaches its maximum size, `G_IO_ERROR_NO_SPACE` will be returned.

#### Parameters

self | a XbMachine |
stack | a XbStack |
opcode_out | return location for the new XbOpcode. | [out][nullable]
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if a new empty opcode was returned, or `FALSE` if the stack has reached its maximum size

Since: 0.2.0

### xb_machine_stack_push_text ()

    gboolean
    xb_machine_stack_push_text (XbMachine *self,
                                XbStack *stack,
                                const gchar *str,
                                GError **error);

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

Errors are as for `xb_machine_stack_push()`.

#### Parameters

self | a XbMachine |
stack | a XbStack |
str | text literal |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` otherwise

Since: 0.2.0

### xb_machine_stack_push_text_static ()

    gboolean
    xb_machine_stack_push_text_static (XbMachine *self,
                                       XbStack *stack,
                                       const gchar *str,
                                       GError **error);

Adds static text literal to the stack.

Errors are as for `xb_machine_stack_push()`.

#### Parameters

self | a XbMachine |
stack | a XbStack |
str | text literal |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` otherwise

Since: 0.2.0

### xb_machine_stack_push_text_steal ()

    gboolean
    xb_machine_stack_push_text_steal (XbMachine *self,
                                      XbStack *stack,
                                      gchar *str,
                                      GError **error);

Adds a stolen text literal to the stack.

Errors are as for `xb_machine_stack_push()`.

#### Parameters

self | a XbMachine |
stack | a XbStack |
str | text literal. | [transfer full]
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` otherwise

Since: 0.2.0

### xb_machine_stack_push_integer ()

    gboolean
    xb_machine_stack_push_integer (XbMachine *self,
                                   XbStack *stack,
                                   guint32 val,
                                   GError **error);

Adds an integer literal to the stack.

Errors are as for `xb_machine_stack_push()`.

#### Parameters

self | a XbMachine |
stack | a XbStack |
val | integer literal |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` otherwise

Since: 0.2.0

### 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 |  |
XB_MACHINE_DEBUG_FLAG_SHOW_SLOW_PATH |  |

### 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;