The most important part of LuaGnome is the ability to call almost any function provided by the supported libraries. This section explains how to do this.
Using a syntax very similar to the C API, you can call a function like in the following example:
<%= inline_code [[ require "glib" print(glib.get_user_name()) print(glib.build_filename("one", "two", "three")) ]] %>
Note how the glib
object is used. It is a module that provides
the bindings to GLib, and has a prefix for functions built in, in this case
"g_". While you could also call glib.g_get_user_name()
, the
preferred usage is without that prefix.
Most of the supported functions can be considered methods, with their first argument being the object to manipulate. The following examples demonstrate how such methods are called:
<%= copy_file "doc/en/call1.lua" %>
When calling a method on an object, the library function to call is computed
using the object's type name and the method name. In the example above,
from the type GMatchInfo
and the method name
get_string
, the computed function name is
g_match_info_get_string
.
Fortunately most of the GLib/GDK/Gtk/... functions have consistent names, always starting with the mangled type name and a method name. In some cases aliases have been defined where this pattern is not followed.
See also the page on Objects.
Refer to the official C API documentation of the library for the specification of the argument list. Most of the C types are supported by LuaGnome, which has to convert Lua values to C before calling a library function. Even multiple indirections (pointer to pointer to something) are supported.
Simple data types like strings, numbers, but also objects are quite easy to convert. Other types like function pointers, boxed values, void pointers and others are more involved and are explained in detail on separate pages.
Each function may have none, one or multiple return values. The called C function can have only one "real" return value, of course. Multiple values can, however, be returned by providing a pointer as argument, and the library function stores additional values at this location, as in the following example:
// this is C code.
gchar *endptr = NULL;
gint64 val = g_ascii_stroll("123foo", &endptr, 0);
// endptr now points to the "f" in the given string.
A one-to-one emulation of this in Lua might look like this ugly contraption:
<%= inline_code [[ require "glib" -- this is NOT how it is done endptr = gnome.pointer "char*" val = glib.ascii_stroll("123foo", endptr, 0) print(val, endptr.content) ]] %>Instead, Lua's ability to return multiple values from functions is used. You only have to provide the initialization as argument, and the return values are returned in order. LuaGnome is fairly adept at figuring out which arguments are used as output, and which are not.
As a special case, a double pointer argument like char**
or GError**
is an output argument; that is, the called function
will place a pointer at the given location. If you specify nil, then no
output is generated. If you want the function to receive a valid pointer to
a location that contains NULL, and whose content is returned, you have to
use gnome.NIL
.