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

This are NULL-safe methods.

stash()

    Stash stash () const

Returns 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 () const

Returns 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 () const

This 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) const

This 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))});

SEE ALSO

XS::Framework

XS::Framework::Manual::SVAPI

XS::Framework::Manual::SVAPI::Sv

cpanm XS::Framework

perl -MCPAN -e shell
install XS::Framework