NAME

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

Object

Overview

The Object class is the wrapper around Perls RV* object, which is a variant of SV*. As with Sv, it might hold an underlying Perl SV* or might not.

The Object wrapper makes it possible to call various methods on the object.

Construction

    Object (std::nullptr_t = nullptr) {}
    template <class T, typename = one_of_t<T,SV,AV,HV,CV,GV>>
    Object (T* sv, bool policy = INCREMENT)

When the new non-empty Object is created, it checks whether underlying sv argument points to already blessed Perl object or not. If it not, then exception will be thrown. If the sv already points to undef, then empty object will be returned.

The copy and move constructors are also available:

    Object (const Object& oth)
    Object (Object&&      oth)
    Object (const Sv&     oth)
    Object (Sv&&          oth)

assignment operators

    template <class T, typename = one_of_t<T,SV,AV,HV,CV,GV>>
    Object& operator= (T* val)
    Object& operator= (const Object& oth)
    Object& operator= (Object&& oth)
    Object& operator= (const Sv& oth)
    Object& operator= (Sv&& oth)

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.

    template <class T, typename = one_of_t<T,SV,AV,HV,CV,GV>>
    void set (T* val)

The set method directly assigns the value to the underlying SV*, bypassing all checks. Use the method with caution.

stash()

    Stash stash () const
    void stash (const Stash&)

The stash method make it possible to retrive or set the current symbol table for the object.

This are null-unsafe methods.

rebless()

    void rebless (const Stash& stash);

Reblesses object into the specified stash.

This is null-unsafe method.

isa()

    bool isa (const panda::string_view& parent)
    bool isa (const Stash& parent)

works similar to isa Perl method, i.e.

    my $is_me = $obj->isa('My::Class')

Returns true if the current Object is blessed into parent argument, or if the current object belongs to parent class hierarchy (i.e. blessed into child-classs).

This are null-unsafe methods.

reset()

    void reset ()

Decrements refcounter in the undrerlying SV* and sets it to NULL.

This is NULL-safe method.

detach()

    SV* detach ()

Releases ownership on the underlying SV* (which might be NULL) and returns it. The refcounter is not touched.

This is NULL-unsafe method.

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 next_method        (const Sub& context) const
    Sub next_method_strict (const Sub& context) const

    Sub super_method        (const Sub& context) const
    Sub super_method_strict (const Sub& context) const

The method resolving can be performed either via panda::string_view or Sv name. If a method name cannot be found, the empty Sub is returned. To avoid that the method_strict should be invoked; if the method name cannot be found, then exception will be thrown.

The super_method takes the existing Sub and tries to find the corresponding method in the parent package of the current Stash. It uses the resolution order specified in the class (i.e. C3 if 'use mro c3' or DFS otherwise). The next_method tries to find the next method using C3, see mro. The _strict version throw exception if nothing is found.

This are null-unsafe methods.

Usage example:

    //Stash stash = Stash("my::derived");
    Object obj = ...;
    Sub m_child = obj.method("method");
    Sub m_parent = obj.super_method(m_child);
    m_parent.call(obj);

method invocation

    *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 name is known in a Stash; if method is not found, then an exception will be thrown. The call_SUPER / call_super / call_next will lookup for corresponding method in the parent or next class in the hierachy (see mro).

The diffence between call_SUPER / 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 class said 'use mro c3' or DFS otherwise).

The same methods with _maybe prefix do exist: if the corresponding metthod is not found, then empty result will be returned, i.e. no exception will be thrown.

A reference to the current Object is curried for all invocations as the first argument, i.e. object.call("method") is the same as

    $object->method();

in Perl.

This are null-unsafe methods.

SEE ALSO

XS::Framework

XS::Framework::Manual::SVAPI

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

XS::Framework::Manual::SVAPI::Ref

cpanm XS::Framework

perl -MCPAN -e shell
install XS::Framework