NAME

Devel::Ladybug::Object - Abstract object class

DESCRIPTION

Base abstract object class for the Devel::Ladybug framework. Extends Devel::Ladybug::Class with a constructor, getters, and setters.

PUBLIC CLASS METHODS

• $class->new()

  Returns a new object instance. Optionally accepts a hash or hash ref for use as a prototype object.

  #
  # File: Example.pm
  #
  # Implement a concrete class based on Devel::Ladybug::Object:
  #
  use Devel::Ladybug::Class;
  
  create "YourApp::Example" => {
    __BASE__ => "Devel::Ladybug::Object"
  };

  Meanwhile, in caller:

  #!/bin/env perl
  
  #
  # File: somecaller.pl
  #
  # New empty object:
  #
  my $obj = YourApp::Example->new();
  
  #
  # New object from an even list:
  #
  my $objFromList = YourApp::Example->new(
    foo => "whiskey",
    bar => "tango"
  );
  
  #
  # New object from HASH ref:
  #
  my $objFromRef = YourApp::Example->new( {
    foo => "whiskey",
    bar => "tango"
  } );

• $class->proto()

  Constructor method. Returns a new instance of self, populated with default values. The returned object may contain undefined values which must be populated before calling save().

• $class->attributes()

  Returns a flat list of allowed attributes, if any, for objects of this class.

  my @keys = $class->attributes();

• $class->isAttributeAllowed($key)

  Returns true if the received key is a valid attribute for instances of the current class, otherwise warns to STDERR and returns false.

  #
  # File: Example.pm
  #
  # Create a new class with two attrs, "foo" and "bar"
  #
  my $class = "YourApp::Example";
  
  create $class => {
    foo => Devel::Ladybug::Str->assert(),
  
    bar => Devel::Ladybug::Int->assert(),
  
    # ...
  };

  Meanwhile, in caller...

  #!/bin/env perl
  
  #
  # File: somecaller.pl
  #
  # Check for allowed attributes:
  #
  for ( qw| foo bar rebar | ) {
    next if !$class->isAttributeAllowed($_);
  
    # ...
  }
  
  #
  # Expected output is warning text to the effect of:
  #
  # BUG IN CALLER: "rebar" is not a member of class "YourApp::Example"
  #

• $class->assert()

  Abstract method, implemented by subclasses to return an assertion object.

  Returns a pre-made Devel::Ladybug::Type object with subtypes for the named datatype. See "Concrete Classes" in Devel::Ladybug for a list of types which may be asserted.

  create "YourApp::Example" => {
    someStr     => Devel::Ladybug::Str->assert(
      ::optional(),
      ::default("Foo Bar!")
    ),
  
    someInt     => Devel::Ladybug::Int->assert( ::optional() ),
    someFloat   => Devel::Ladybug::Float->assert( ::optional() ),
    someDouble  => Devel::Ladybug::Double->assert( ::optional() ),
    someBool    => Devel::Ladybug::Bool->assert( ::default(false) ),
  
    # ...
  };

  To enforce a range of allowed values, use the desired values as arguments:

  create "YourApp::Example" => {
    foo => Devel::Ladybug::Str->assert(qw| alpha bravo cthulhu |);
  
    ...
  };

  If the range of allowed values should be looked up from some external source at runtime (rather than load time), provide an anonymous function (Perl sub{} block or CODE ref).

  This lets the range of allowed values change through the lifetime of the application process, based on whatever the function returns (as opposed to using a static list, which is loaded at "use" time and doesn't adapt to changing data.)

  The function provided should return an array ref of allowed values.

  ...
  
   create "YourApp::Example" => {
     #
     # Always check against a live datasource:
     #
     someId => Devel::Ladybug::Str->assert( sub { YourApp::Example->allIds() } ),
  
     ...
   };

  Instance variables containing complex data structures, objects, or pointers to external objects follow the same basic form as simple assertions.

  The values for Devel::Ladybug::Array and Devel::Ladybug::Hash attributes are stored in linked tables, which Devel::Ladybug creates and manages.

  Devel::Ladybug::ExtID, which is a simple pointer to an external object, is generally a more maintainable approach than inline Devel::Ladybug::Array and Devel::Ladybug::Hash elements, and also provides the best performance.

PRIVATE CLASS METHODS

Class Callback Methods

• $class->import()

  Callback method invoked when callers use this package. Provides caller with Types and Bools.

PUBLIC INSTANCE METHODS

• $self->get($key)

  Get the received instance variable. Very strict about input enforcement.

  If using assertions, Devel::Ladybug *DIES* if the key is invalid!

• $self->set($key, $value)

  Set the received instance variable. Very strict about input enforcement.

  If using assertions, Devel::Ladybug *DIES* on purpose here if key or value are invalid.

• $self->clear()

  Removes all items, leaving self with zero elements.

  my $object = YourApp::Example->new(
    foo => "uno",
    bar => "dos"
  );
  
  print $object->count(); # 2
  print "\n";
  
  $object->clear();
  
  print $object->count(); # 0
  print "\n";

• $self->class()

  Object wrapper for Perl's built-in ref() function

• $self->value()

  Returns self's value as a native data type, ie dereferences it

AUTOLOADED

• $self->set<Attribute>($value)

  AUTOLOADed setter method. Set the attribute named in the message to the received value. Does lcfirst on the attribute name.

  Performs value checking and sanitizing (a good reason to use the setter!)

  $self->setFoo("bario")

• $self-><Attribute>()

  AUTOLOADed getter method. Returns the value for the received attribute.

  $self->setFoo("bario");
  
  my $value = $self->foo(); # returns "bario"

• $self->delete<Attribute>()

  AUTOLOADed key deletion method. Removes the named attribute from the working object. Performs lcfirst on the attribute named in the message.

  $self->setFoo("bario");
  $self->foo(); # returns "bario";
  
  $self->deleteFoo();
  $self->foo(); # returns undef

PRIVATE INSTANCE METHODS

• $self->_init();

  Abstract callback method invoked after object creation (called from new()).

  Override in subclass to handle additional logic if needed.

SEE ALSO

This file is part of Devel::Ladybug.