=head1 NAME

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

=head1 Object

=head2 Overview

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

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

=head2 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 C<sv> argument
points to already blessed Perl object or not. If it not, then exception will be thrown.
If the C<sv> already points to C<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)

=head2 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 C<Sv>, including NULL-safety. The previously held
C<SV*> will be C<dec>-remented.

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

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

=head2 stash()

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

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

This are null-unsafe methods.

=head2 rebless()

    void rebless (const Stash& stash);

Reblesses object into the specified stash.

This is null-unsafe method.

=head2 isa()

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

works similar to C<isa> Perl method, i.e.

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

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

This are null-unsafe methods.


=head2 reset()

    void reset ()

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

This is NULL-safe method.


=head2 detach()

    SV* detach ()

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

This is NULL-unsafe method.

=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 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 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. C3 if 'use mro c3' or DFS otherwise). The C<next_method>
tries to find the next method using C3, 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");
    Object obj = ...;
    Sub m_child = obj.method("method");
    Sub m_parent = obj.super_method(m_child);
    m_parent.call(obj);


=head2 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
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 class said '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.

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

    $object->method();

in Perl.

This are null-unsafe methods.

=head1 SEE ALSO

L<XS::Framework>

L<XS::Framework::Manual::SVAPI>

L<XS::Framework::Manual::SVAPI::Sv>

L<XS::Framework::Manual::SVAPI::Ref>

=cut
