NAME

       Lucy::Object::Obj - Base class for all Lucy objects.

SYNOPSIS

           package MyObj;
           use base qw( Lucy::Object::Obj );

           # Inside-out member var.
           my %foo;

           sub new {
               my ( $class, %args ) = @_;
               my $foo = delete $args{foo};
               my $self = $class->SUPER::new(%args);
               $foo{$$self} = $foo;
               return $self;
           }

           sub get_foo {
               my $self = shift;
               return $foo{$$self};
           }

           sub DESTROY {
               my $self = shift;
               delete $foo{$$self};
               $self->SUPER::DESTROY;
           }

DESCRIPTION

       All objects in the Lucy:: hierarchy descend from Lucy::Object::Obj.  All classes are
       implemented as blessed scalar references, with the scalar storing a pointer to a C struct.

   Subclassing
       The recommended way to subclass Lucy::Object::Obj and its descendants is to use the
       inside-out design pattern.  (See Class::InsideOut for an introduction to inside-out
       techniques.)

       Since the blessed scalar stores a C pointer value which is unique per-object, $$self can
       be used as an inside-out ID.

           # Accessor for 'foo' member variable.
           sub get_foo {
               my $self = shift;
               return $foo{$$self};
           }

       Caveats:

       •   Inside-out aficionados will have noted that the "cached scalar id" stratagem
           recommended above isn't compatible with ithreads -- but Lucy doesn't support ithreads
           anyway, so it doesn't matter.

       •   Overridden methods must not return undef unless the API specifies that returning undef
           is permissible.  (Failure to adhere to this rule currently results in a segfault
           rather than an exception.)

CONSTRUCTOR

   new()
       Abstract constructor -- must be invoked via a subclass.  Attempting to instantiate objects
       of class "Lucy::Object::Obj" directly causes an error.

       Takes no arguments; if any are supplied, an error will be reported.

DESTRUCTOR

   DESTROY
       All Lucy classes implement a DESTROY method; if you override it in a subclass, you must
       call "$self->SUPER::DESTROY" to avoid leaking memory.

ABSTRACT METHODS

   to_i64()
       Convert the object to a 64-bit integer.

   to_f64()
       Convert the object to a double precision floating point number.

   load(dump)
       Create an object from the output of a call to dump().  Implementations must not reference
       the caller.

       •   dump - The output of dump().

METHODS

   to_string()
       Generic stringification: "ClassName@hex_mem_address".

   equals(other)
       Indicate whether two objects are the same.  By default, compares the memory address.

       •   other - Another Obj.

   dump()
       Return a representation of the object using only scalars, hashes, and arrays.  Some
       implementations support JSON serialization via dump() and its companion method, load();
       for others, dump() is only a debugging aid.  The default simply calls to_string().