NAME
XS::Framework::Manual::SVAPI::Sub - XS::Framework Sub C++ class reference
Sub
Overview
Sub is C++ wrapper around callable Perl subroutine. It inherits all methods from Sv and disables a few ones, which have no sense for the class, e.g. construction of Sub object from array AV* or coercion to AV*.
As the Sv it might hold the underlying Perl SV* or may not.
Construction
static Sub noinc (SV* val)
static Sub noinc (CV* val)
Sub (std::nullptr_t = nullptr) {}
Sub (SV* sv, bool policy = INCREMENT)
Sub (CV* sv, bool policy = INCREMENT)The Sub object can be constructed either from Perl CV* or from SV*, which is perl subroutine pointer. If the supplied SV*/SV* points to NULL or undef, then the object will held NULL. Otherwise, on all other invalid SV* an exception will be thrown. The valid SV* should be either CV* or reference to CV* or undef.
explicit Sub (std::string_view subname, I32 flags = 0)The Perl subroutine reference can be get via string literal, please refer get_cvn_flags in perlapi. In other words, if the named Perl subroutine subname is found, than non-empty Sub object will be created, e.g.
Sub sub("MyPackage::my_fun");Copy and move-constructors are also available:
Sub (const Sub& oth)
Sub (Sub&& oth)
Sub (const Sv& oth)
Sub (Sv&& oth)
Sub (const CallProxy& p)assignment operators
Sub& operator= (SV* val)
Sub& operator= (CV* val)
Sub& operator= (const Sub& oth)
Sub& operator= (Sub&& oth)
Sub& operator= (const Sv& oth)
Sub& operator= (Sv&& oth)
Sub& operator= (const CallProxy& p)The assignment operators are complementaty to the constructors above. They inherit behaviour from Sv, including NULL-safety. The previously held SV* will be dec-remented.
void set (SV* val)The set method directly assigns the value to the underlying SV*, bypassing all checks. Use the method with caution.
getters
Theere are zero-cost NULL-safe getters:
CV* operator-> () const
template <typename T = SV> one_of_t<T,SV,CV>* get () constThis are NULL-safe methods.
stash()
Stash stash () constReturns stash object, i.e. package / symbol table, where underlying subroutine belongs to. This is NULL-unsafe method.
glob()
Glob glob () const;Returns glob object. This is NULL-unsafe method.
name()
std::string_view name () const;Returns subroutine name. This is NULL-unsafe method.
bool named()
bool named () constReturns true if the underlying subroutine points to named subrouitene, and false for anonymous one. This is NULL-unsafe method.
SUPER ()
SUPER_strict ()
Sub SUPER () const
Sub SUPER_strict () constThis methods return Sub object, which represends the same subroutine but for base class of the current one. They differ in behaviour, when the SUPER subroutine cannot be found. The SUPER() method just returns empty Sub, while SUPER_strict() throwns exception.
The method resolution is performed via DFS algorithm (see mro).
This are NULL-unsafe methods.
call()
operator()
CallProxy call () const
CallProxy call (const Scalar& arg) const
CallProxy call (SV*const* args, size_t items) const
CallProxy call (const Scalar& arg0, SV*const* args, size_t items) const
CallProxy call (std::initializer_list<Scalar> l) const
CallProxy call (const Scalar& arg0, std::initializer_list<Scalar> l) const
CallProxy operator() () const
CallProxy operator() (const Scalar& arg) const
CallProxy operator() (SV*const* args, size_t items) const
CallProxy operator() (const Scalar& arg0, SV*const* args, size_t items) const
CallProxy operator() (std::initializer_list<Scalar> l) const
CallProxy operator() (const Scalar& arg0, std::initializer_list<Scalar> l) constThis methods just curry call invocation, i.e. remember the Perl subroutine and arguments. The actuall call is performed by CallProxy later, once it's result being accessed. The rationale behind that is that Oerl subroutine can be invoked in list or in scalar context and that context is not known yet (in C++ place of invocation). Here are a few examples:
Sub sub = ...;
Scalar p1 = sub.call();
Scalar p2 = sub.call(Simple(123));
Simple arg1(1), arg2(2), arg3(3);
SV* args[] = {arg1, arg2, arg3};
List p3 = sub(args, 3);
// invoked in void context
sub.call({Simple(2), Scalar(Simple(3)), Sv(Simple(4))});