This library is a toolbox that assists with creation & maintenance of Perl XS code.
Make this repository a git submodule of your own XS module.
Replace the standard XS includes (
XSUB.h) with just
… and that’s it! You now have a suite of tools that’ll make writing XS easier and safer.
Perl’s C API makes lots of things possible without making them easy (or safe).
This library attempts to provide shims around that API that make it easy and safe (or, at least, safe-er!) to write XS code … maybe even fun! :-)
init.h includes the standard boilerplate code you normally stick at the
top of a
*.xs file. It also includes a fix for the
torrent of warnings that clang 12 throws
in pre-5.36 perls.
easyxs.h brings this in, but you can also
#include "easyxs/init.h" on its own.
init.h also includes a fairly up-to-date
void exs_call_sv_void(SV* callback, SV** args)
Like the Perl API’s
call_sv() but handles argument-passing for you.
args points to a NULL-terminated array of
SV*s. (It may also be NULL.)
The method is called in void context, so nothing is returned.
This does not trap exceptions.
IMPORTANT: This mortalizes each
args member. That means Perl
will reduce each of those SVs’ reference counts at some point “soon” after.
This is often desirable, but not always; to counteract it, do
around whichever arguments you want to be unaffected by the mortalization.
(They’ll still be mortalized, but the eventual reference-count reduction will
just have zero net effect.)
void exs_call_method_void(SV* object, const char* methname, SV** args)
exs_call_sv_void() but for calling object methods. See
the Perl API’s
call_method() for more details.
SV* exs_call_method_scalar(SV* object, const char* methname, SV** args)
exs_call_method_void() but calls the method in scalar context.
The result is returned.
UV* exs_SvUV(SV* sv)
SvUV, but if the SV’s content can’t be an unsigned integer
(e.g., the IV is negative, or the string has non-numeric characters)
an exception is thrown.
char* exs_SvPVbyte_nolen(SV* sv)
Like the Perl API’s
SvPVbyte_nolen, but if there are any NULs in the
PV then an exception is thrown.
char* exs_SvPVutf8_nolen(SV* sv)
exs_SvPVbyte_nolen() but returns the code points as UTF-8 rather
Writes a visual representation of the SV’s contents to
NO trailing newline is written.
exs_debug_showstack(const char *pattern, ...)
Writes a visual representation of Perl’s argument stack
If you use GitHub Actions or similar, ensure that you grab the submodule as part of your workflow’s checkout. If you use GitHub’s own checkout workflow, that’s:
- with: submodules: true # (or `recursive`)
git submodule init && git submodule update
during the workflow’s repository setup.
License & Copyright
Copyright 2022 by Gasper Software Consulting. All rights reserved.
This library is released under the terms of the MIT License.