NAME

XS::Framework::Manual::SVAPI::Glob - XS::Framework Glob C++ class reference

Glob

Overview

The Glob class is the wrapper around Perls GV* type, which is a variant of SV*. As with Scalar, it might hold an underlying Perl SV* or might not.

The Glob object does not holds undef; if undef is assigned or supplied in constructor, the object is considered empty. In other words the undef and NULL have the same meaning for the class.

A GV is a structure which corresponds to to a Perl typeglob, ie *foo. It is a structure that holds a pointer to a scalar, an array, a hash etc, corresponding to $foo, @foo, %foo.

GVs are usually found as values in stashes (symbol table hashes) where Perl stores its global variables.

Construction

To create a new GV* in Perl, the Stash object and the name should be provided:

    static Glob create (const Stash& stash, std::string_view name, U32 flags = 0);

For the flags description please refer gv_init_pvn in perlapi.

To create an wrapper around existing GV* the following constructors can be used:

    Glob (std::nullptr_t = nullptr)
    Glob (SV* sv, bool policy = INCREMENT)
    Glob (GV* sv, bool policy = INCREMENT)

If SV* or <GV*> are undef or NULL, the returned Glob object will be empty. Otherwise, if unappropriate SV* is supplied, then exception will be thrown.

Copy and move-constructore are also available:

    Glob (const Glob&   oth)
    Glob (Glob&&        oth)
    Glob (const Scalar& oth)
    Glob (Scalar&&      oth)
    Glob (const Sv&     oth)
    Glob (Sv&&          oth)

It it possible to create Glbo object from CallProxy invocation:

    Glob (const CallProxy& p) : Glob(p.sv()) {}

however, please note, that the CallProxy will be called in scalar context. If the CallProxy returns unacceptable SV* the execption will be thrown.

assignment operators

    Glob& operator= (SV* val)
    Glob& operator= (GV* val)
    Glob& operator= (const Glob& oth)
    Glob& operator= (Glob&& oth)
    Glob& operator= (const Scalar& oth)
    Glob& operator= (Scalar&& oth)
    Glob& operator= (const Sv& oth)
    Glob& operator= (Sv&& oth)
    Glob& operator= (const CallProxy& p)

The assignment operators are complementaty to the constructors above. They inherit behaviour from Scalar, including NULL-safety. The previously held SV* will be dec-remented.

The last operator performs proxy call in scalar context, the same as in appropriate constructor above.

    void set (SV* val)
    void set (GV* 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:

    operator GV* () const
    GV* operator->() const
    template <typename T = SV> one_of_t<T,SV,GV>* get () const

This are NULL-safe methods. The returned value, however, might be NULL.

slot ()

    template <typename T> one_of_t<T,Scalar,Array,Hash,Sub> slot () const
    void slot (SV*)
    void slot (AV*)
    void slot (HV*)
    void slot (CV*)
    void slot (const Scalar&)
    void slot (const Sv&     v)
    void slot (const Array&  v)
    void slot (const Hash&   v)
    void slot (const Sub&    v)
    void slot (const CallProxy& p)

This are read/write accessors for appropriate slot type in the Glob instance. For example:

    Stash s = ...;
    Glob o = s["some_name"];
    Sub sub = o.slot<Sub>();

The slot methods are NULL-unsafe.

scalar()

array()

hash()

sub()

    Scalar scalar () const
    Array  array  () const
    Hash   hash   () const
    Sub    sub    () const

    void scalar (const Scalar& val)
    void array  (const Array&  val)
    void hash   (const Hash&   val)
    void sub    (const Sub&    val)

This group of methods provide convenient access to scalar/array/hash/sub slot of the Glob. The read accessors are NULL-safe, while write-accessors are NULL-unsafe.

get_const()

    Sv get_const () const

If Sub-slot is eligible for inlining it returns the valuer returned by the Sub wrapped into Sv. Otherwise emptu Sv is returned.

This is NULL-unsafe method.

stash()

effective_stash

    Stash stash           () const
    Stash effective_stash () const

Returns the current or effective Stash associated with the Glob instance.

This are NULL-unsafe methods.

name()

effective_name ()

    std::string_view name           () const
    std::string_view effective_name () const

Returns the name of the current or effective Stash associated with the Glob instance.

This are NULL-unsafe methods.

SEE ALSO

XS::Framework

XS::Framework::Manual::SVAPI

XS::Framework::Manual::SVAPI::Scalar

XS::Framework::Manual::SVAPI::Stash