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.

    Object (const CallProxy& p)

The Object instance can be created from function call result CallProxy.Please note, that the CallProxy will be called in scalar context.

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)
    Object& 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.

    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 std::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 std::string_view& name) const
    Sub method_strict (const Sv& name) const
    Sub method_strict (const std::string_view& name) const

    Sub next_method        (const Sub& current) const
    Sub next_method_strict (const Sub& current) const

    Sub super_method        (const Sub& current) const
    Sub super_method_strict (const Sub& current) const

The method resolving can be performed either via std::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. use mro 'c3'). The next_method tries to find the next method using method resolution order, 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

    CallProxy call (const Sv& name)                                                const
    CallProxy call (const std::string_view& name)                                  const
    CallProxy call (const Sv& name,               const Scalar& arg)               const
    CallProxy call (const std::string_view& name, const Scalar& arg)               const
    CallProxy call (const Sv& name,               SV*const* args, size_t items)    const
    CallProxy call (const std::string_view& name, SV*const* args, size_t items)    const
    CallProxy call (const Sv& name,               std::initializer_list<Scalar> l) const
    CallProxy call (const std::string_view& name, std::initializer_list<Scalar> l) const

    CallProxy call_SUPER (const Sub& current)                                  const
    CallProxy call_SUPER (const Sub& current, const Scalar& arg)               const
    CallProxy call_SUPER (const Sub& current, SV*const* args, size_t items)    const
    CallProxy call_SUPER (const Sub& current, std::initializer_list<Scalar> l) const

    CallProxy call_next (const Sub& current)                                  const
    CallProxy call_next (const Sub& current, const Scalar& arg)               const
    CallProxy call_next (const Sub& current, SV*const* args, size_t items)    const
    CallProxy call_next (const Sub& current, std::initializer_list<Scalar> l) const

    CallProxy call_next_maybe (const Sub& current)                                  const
    CallProxy call_next_maybe (const Sub& current, const Scalar& arg)               const
    CallProxy call_next_maybe (const Sub& current, SV*const* args, size_t items)    const
    CallProxy call_next_maybe (const Sub& current, std::initializer_list<Scalar> l) const

    CallProxy call_super (const Sub& current)                                  const
    CallProxy call_super (const Sub& current, const Scalar& arg)               const
    CallProxy call_super (const Sub& current, SV*const* args, size_t items)    const
    CallProxy call_super (const Sub& current, std::initializer_list<Scalar> l) const

    CallProxy call_super_maybe (const Sub& current)                                  const
    CallProxy call_super_maybe (const Sub& current, const Scalar& arg)               const
    CallProxy call_super_maybe (const Sub& current, SV*const* args, size_t items)    const
    CallProxy call_super_maybe (const Sub& current, std::initializer_list<Scalar> l) 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. use mro 'c3' for using C3-resolution).

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. (Actually we discourage using of them, as this is leads do pefromance penalities without any actual job to be done. Why you use XS::Framework at all, then?).

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.

The CallProxy object is returned to peform actuall method call.

This are null-unsafe methods.

SEE ALSO

XS::Framework

XS::Framework::Manual::SVAPI

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

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