bionic (3) Lucy::Object::Obj.3pm.gz

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().