=head1 NAME
XS::Framework::Manual::SVAPI::Stash - XS::Framework Stash C++ class reference
=head1 Stash
=head2 Overview
The C<Stash> class extension of C<Hash> class, which provides convenient access
to perl symbol table as well as symbol resolution via C<call>, C<call_SUPER>
and C<call_next> methods.
Stash may be empty, i.e. contain C<NULL> C<SV*>.
=head2 Construction
static Stash root ()
Returns Perl's default stash.
Stash (std::nullptr_t = nullptr)
Creates an empty stash.
static Stash from_name (SV* fqn, I32 flags = 0)
Stash (const panda::string_view& package, I32 flags = 0)
Looks up for the specified fully-qualified package name and returns, may be empty,
C<Stash> object for the result. The C<flags> are additional parameters for lookup, e.g.
C<GV_ADD> will create new symbol table. See C<gv_stashpvn> in L<perlapi>.
Stash (SV* sv, bool policy = INCREMENT)
Stash (HV* sv, bool policy = INCREMENT)
Upgrades hash C<HV*>, which already refers to symbol table, or reference to it (C<SV*>)
into <Stash> object. If the supplied agrument is invalid, the exception will be
thrown. It is possible that the first agrument be C<NULL> or C<undef>, in that case
empty stash will be crated.
Copy and move-constructore are also available:
Stash (const Stash& oth)
Stash (const Hash& oth)
Stash (const Sv& oth)
Stash (Stash&& oth)
Stash (Hash&& oth)
Stash (Sv&& oth)
=head2 assignment operators
Stash& operator= (SV* val)
Stash& operator= (HV* val)
Stash& operator= (const Stash& oth)
Stash& operator= (Stash&& oth)
Stash& operator= (const Hash& oth)
Stash& operator= (Hash&& oth)
Stash& operator= (const Sv& oth)
Stash& operator= (Sv&& oth)
The assignment operators are complementaty to the constructors above. They
inherit behaviour from C<Hash>, including NULL-safety. The previously held
C<SV*> will be C<dec>-remented.
void set (HV* val)
The C<set> method directly assigns the value to the underlying C<SV*> in
the form of C<HV*>, I<bypassing all checks>. Use the method with caution.
=head2 element access
Glob fetch (const panda::string_view& key)
Glob at (const panda::string_view& key)
Glob operator[] (const panda::string_view& key)
op_proxy operator[] (const panda::string_view& key)
The first three methods return C<Glob> type via the C<key> string.
C<fetch> provides safe access to the elements, i.e. in case of absence of a key
empty C<Glob> will be returned. The C<at> method will throw error of the
specified C<key> is not found in the current symbol table. The
C<operator[] fetch> is the alias for C<fetch> method.
The non-const C<operator[]> allows in-place fast modification of underlying
element, i.e.
Stash stash = Stash("my::package", GV_ADD);
stash["PI"] = Simple(3.14);
All the methods above are NULL-safe; the assingment of empty stash leads
to thrown exception.
void store (const panda::string_view& key, SV* v)
void store (const panda::string_view& key, AV* v)
void store (const panda::string_view& key, HV* v)
void store (const panda::string_view& key, CV* v)
void store (const panda::string_view& key, GV* v)
void store (const panda::string_view& key, IO* v)
void store (const panda::string_view& key, const Sv& v)
void store (const panda::string_view& key, const Scalar& v)
void store (const panda::string_view& key, const Array& v)
void store (const panda::string_view& key, const Hash& v)
void store (const panda::string_view& key, const Sub& v)
void store (const panda::string_view& key, const Glob& v)
void store (const panda::string_view& key, const Io& v)
The NULL-safe C<store> method allows to inject the new value into the stash.
The exception will be thrown if the stash object is empty.
The following methods provide convenient access C<Stash> symbol
values, when the type is known:
Scalar scalar (const panda::string_view& name) const
Array array (const panda::string_view& name) const
Hash hash (const panda::string_view& name) const
Sub sub (const panda::string_view& name) const
Io io (const panda::string_view& name) const
void scalar (const panda::string_view& name, const Scalar& v)
void array (const panda::string_view& name, const Array& v)
void hash (const panda::string_view& name, const Hash& v)
void sub (const panda::string_view& name, const Sub& v)
void io (const panda::string_view& name, const Io& v)
The read-access is NULL-safe; the write-access (i.e assignment) on empty C<Stash>
throws exception. Usage example:
Stash stash = Stash("my::package");
auto pi = stash.scalar("pi");
stash.scalar("e", Simple(2.71)); // will throw if "my::package" is not known to Perl
=head2 method access
Sub method (const Sv& name) const
Sub method (const panda::string_view& name) const
Sub method_strict (const Sv& name) const
Sub method_strict (const panda::string_view& name) const
Sub super_method (const Sub& current) const
Sub super_method_strict (const Sub& current) const
Sub next_method (const Sub& current) const
Sub next_method_strict (const Sub& current) const
The method resolving can be performed either via C<panda::string_view> or C<Sv>
name. If a method name cannot be found, the empty C<Sub> is returned. To avoid
that the C<method_strict> should be invoked; if the method C<name> cannot be
found, then exception will be thrown.
The C<super_method> takes the existing C<Sub> and tries to find the corresponding
method in the B<parent> package of the current C<Stash>. It uses the resolution
order specified in the class (i.e. C<use mro 'c3'>). The C<next_method>
tries to find the next method using method resolution order, see L<mro>. The
C<_strict> version throw exception if nothing is found.
This are null-unsafe methods.
Usage example:
Stash stash = Stash("my::derived");
Sub m_child = stash.method("method");
Sub m_parent = stash.super_method(m_child);
m_parent.call();
=head2 method call
*depends* call (const Sv& name, Args&&...args) const
*depends* call (const panda::string_view& name, Args&&...args) const
*depends* call_SUPER (const Sub& context, Args&&...args) const
*depends* call_next (const Sub& context, Args&&...args) const
*depends* call_next_maybe (const Sub& context, Args&&...args) const
*depends* call_super (const Sub& context, Args&&...args) const
*depends* call_super_maybe (const Sub& context, Args&&...args) const
It is possible to invoke arbitrary method with arbitrary arguments if method
C<name> is known in a C<Stash>; if method is not found, then an exception will
be thrown. The C<call_SUPER> / C<call_super> / C<call_next> will lookup for
corresponding method in the parent or next class in the hierachy (see L<mro>).
The diffence between C<call_SUPER> / C<call_super> is how the parent method
is looked-up: either via classical DFS MRO resolution or via class-defined
resolution (i.e. C3 if 'use mro c3' or DFS otherwise).
The same methods with C<_maybe> prefix do exist: if the corresponding metthod
is not found, then empty result will be returned, i.e. no exception will be
thrown.
This are null-unsafe methods.
=head2 package name
panda::string_view name () const
HEK* name_hek () const
const Simple& name_sv () const
To know the name of the package, to which the current C<Stash> object points, the
C<name>, C<name_sv> and C<name_hek> methods can be used. For example:
Stash stash = Stash("my::package");
auto name = stash.name(); // returns "my::package"
If it is planned to let the package name be used in Perl in future, then prefer
to use C<name_sv> method.
panda::string_view effective_name () const
It is possible to have I<effective_name> of the current stash, if the stash
was aliased. See C<HvENAME> in L<perlapi>.
This are null-unsafe methods.
=head2 path()
panda::string path () const
Returns the file path for the current stash, i.e.
Stash s("A::B::C", GV_ADD);
s.path(); // returns A/B/C.pm
=head2 mark_as_loaded()
void mark_as_loaded (const Stash& source) const
void mark_as_loaded (const panda::string_view& source) const
Let the perl knows, where the current C<Stash> comes from, i.e. inserts into
the perl C<INC> variable the C<source> for the current C<Stash>. This is
useful, when writing multiple XS-bases packages in a single module.
L<XS::Framework> ships with a few useful macros, so, it is usually
used in the C<BOOT> section of the package like the following:
Stash(__PACKAGE__, GV_ADD).mark_as_loaded(__MODULE__);
The typical sympthom to use C<mark_as_loaded> is the following error:
Can't locate MyModule/MyClass.pm in @INC
=head2 inherit()
void inherit (const Stash& parent)
void inherit (const panda::string_view& parent)
Links the current symbol table as the descendant class for C<parent> C<Stash>.
In other words, it the following construct:
Stash child("MyPackage::Child"); // or, better Stash(__PACKAGE__, GV_ADD)
child.mark_as_loaded(__MODULE__);
Stash base("MyPackage::Base");
child.inherit(base);
is equivalent to perl code:
package MyPackage::Child;
use parent qw/MyPackage::Base/;
If the C<parent> package is defined as C<string_view>, it will be automatically
added to Perl via C<GV_ADD>.
The C<inherit> is NULL-safe method; the exception will be thrown if it is
invoked on empty C<Stash>.
=head2 isa()
bool isa (const panda::string_view& parent, U32 hash = 0, int flags = 0) const
bool isa (HEK* hek) const
bool isa (const Stash& parent) const
The C<isa> method returns C<true> if the current C<Stash> exactly matches C<parent>
C<Stash> or if the current C<Stash> is child class for the C<parent> C<Stash>.
The similar code in Perl is
child_CLASS->isa(parent_CLASS);
Under the hood the method uses C<hv_common> function (see C<perlapi>).
=head2 bless()
Object bless () const;
This method creates new C<Object>, which is blessed into to the current package
(C<Stash>).
Object bless (const Sv& what) const;
This C<bless> method version works somewhat similiar to the following Perl
construction
my $class = ...;
my $obj = ...;
return bless $obj => $class;
i.e. if C<what> is already an object, it is blessed into the C<Stash>,
otherwise new C<RV*> created from the C<what> argument, and the
blessed object returned.
=head2 add_const_sub()
void add_const_sub (const panda::string_view& name, const Sv& val);
Creates subroutine C<name> that returns constant C<val> eligible for compile-time inlining (like newCONSTSUB). C<val> is retained and made readonly.
C<val> can be either any C<Scalar> or <Array>. In latter case, const sub will return list containing array's values.
=head1 SEE ALSO
L<XS::Framework>
L<XS::Framework::Manual::SVAPI>
L<XS::Framework::Manual::SVAPI::Sv>
L<XS::Framework::Manual::SVAPI::Hash>
=cut