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