Miscellaneous

Various useful utilities defined in Glib.xs.

GPERL_CALL_BOOT(name)

call the boot code of a module by symbol rather than by name.

in a perl extension which uses several xs files but only one pm, you need to bootstrap the other xs files in order to get their functions exported to perl. if the file has MODULE = Foo::Bar, the boot symbol would be boot_Foo__Bar.

void _gperl_call_XS (pTHX_ void (*subaddr) (pTHX_ CV *), CV * cv, SV ** mark);

never use this function directly. see GPERL_CALL_BOOT.

for the curious, this calls a perl sub by function pointer rather than by name; call_sv requires that the xsub already be registered, but we need this to call a function which will register xsubs. this is an evil hack and should not be used outside of the GPERL_CALL_BOOT macro. it's implemented as a function to avoid code size bloat, and exported so that extension modules can pull the same trick.

gpointer gperl_alloc_temp (int nbytes)

Allocate and return a pointer to an nbytes-long, zero-initialized, temporary buffer that will be reaped at the next garbage collection sweep. This is handy for allocating things that need to be alloc'ed before a croak (since croak doesn't return and give you the chance to free them). The trick is that the memory is allocated in a mortal perl scalar. See the perl online manual for notes on using this technique.

Do not under any circumstances attempt to call g_free(), free(), or any other deallocator on this pointer, or you will crash the interpreter.

gchar *gperl_filename_from_sv (SV *sv)

Return a localized version of the filename in the sv, using g_filename_from_utf8 (and consequently this function might croak). The memory is allocated using gperl_alloc_temp.

SV *gperl_sv_from_filename (const gchar *filename)

Convert the filename into an utf8 string as used by gtk/glib and perl.

gboolean gperl_str_eq (const char * a, const char * b);

Compare a pair of ascii strings, considering '-' and '_' to be equivalent. Used for things like enum value nicknames and signal names.

guint gperl_str_hash (gconstpointer key)

Like g_str_hash(), but considers '-' and '_' to be equivalent.

GPerlArgv * gperl_argv_new ()

Creates a new Perl argv object whose members can then be passed to functions that request argc and argv style arguments.

If the called function(s) modified argv, you can call gperl_argv_update to update Perl's @ARGV in the same way.

Remember to call gperl_argv_free when you're done.

void gperl_argv_update (GPerlArgv *pargv)

Updates @ARGV to resemble the stored argv array.

void gperl_argv_free (GPerlArgv *pargv)

Frees any resources associated with pargv.

char * gperl_format_variable_for_output (SV * sv)

Formats the variable stored in sv for output in error messages. Like SvPV_nolen(), but ellipsizes real strings (i.e., not stringified references) at 20 chars to trim things down for error messages.

gboolean gperl_sv_is_defined (SV *sv)

Checks the SV sv for definedness just like Perl's defined() would do. Most importantly, it correctly handles "magical" SVs, unlike bare SvOK. It's also NULL-safe.

void gperl_hv_take_sv (HV *hv, const char *key, size_t key_length, SV *sv)

Tries to store sv in hv. Decreases sv's reference count if something goes wrong.