Name

Object::Relation::DataType::State - Object::Relation object states

Synopsis

Use class methods:

  use Object::Relation::DataType::State;

  if ($obj_rel_obj->state->compare(Object::Relation::DataType::State->ACTIVE)) {
      $obj_rel->obj->set_state(Object::Relation::DataType::State->ACTIVE);
  }

Or use constants:

  use Object::Relation::DataType::State qw(:all);

  if ($obj_rel_obj->state->compare(ACTIVE)) {
      $obj_rel->obj->set_state(ACTIVE);
  }

Comparison, boolean, and numification operations are overloaded:

  unless ($obj_rel_obj->state == ACTIVE) {
      $obj_rel->obj->set_state(ACTIVE);
  }

  if ($state < ACTIVE) {
      print "This object is not active\n";
  }

  unless ($state) {
      print "This object is not active\n";
  }

  my $state_val = int $state;

Stringification works, too.

  print "The state is $state"; # Prints "The state is Active".

Description

This module creates the "state" data type for use in Object::Relation attributes. This class defines Object::Relation object states. There are five different states for objects:

PERMANENT

Objects in this state are permanent and always visible, and can never be deleted or purged. It will mainly be a few objects that ship with obj_rel that will be permanent.

ACTIVE

Active objects are visible in the UI, and uniqueness checks for them will be enforced.

INACTIVE

Inactive objects are visible in the UI, and uniqueness checks for them will be enforced, but they will cannot be used in any other context, including publishing or the creation of associations with other objects.

DELETED

Deleted objects are no longer visible in the UI, and can only be instantiated by looking them up via the API by calling lookup() with the appropriate arguments. Any uniqueness checks will not be affected by DELETED objects. Deleted objects cannot be undeleted; their deletion should be considered permanent.

PURGED

Purged objects are objects that are permanently purged from the data store. As such, they will only exist as objects until save() is called and any references to the object exist in memory. An object should only be purged in extreme circumstances, such as when some sort of legal motivation compels permanently eliminating data from the data store. Furthermore, a Object::Relation object should not be purged lightly, since an RDBMS data store will likely cascade delete all of its associations. For example, purging a type will delete all objects based on that type. More commonly, deleting a document will delete all data associated with the document, including all of its previous versions.

Object::Relation::DataType::State has constants with these names, which may be accessed as either class methods or as exportable functions. The constants return singleton Object::Relation::DataType::State objects that represent the various states. These same objects are returned by the state attribute accessors of Object::Relation.

Class Interface

Constructors

new

  my $state = Object::Relation::DataType::State->new($value);

Returns a Object::Relation::DataType::State object corresponding to the state value passed to it.

Instance Interface

Instance Methods

Object::Relation::DataType::State overloads a number of Perl operators in order to ease its use in various contexts. Each instance method overloads one or more operations.

value

  my $value = $state->value;

  # Or...
  my $value = int $state;

Returns the numeric value of the state. This is the value that is stored in the data store. This method overrides operations performed upon a state object in a numeric context. Such contexts include:

• Where used with a built-in operator that expects a number (e.g., int($state), substr($string, $state), or print "#" x $state).

• Where used as an operand for the range operator (e.g., for (1..$state)).

• Where used as an array entry index (e.g., $states[$state]).

is_active

  if ($state->is_active) {
      # ...
  }

  # Or...
  if ($state) {
      # ...
  }

  # From a Object::Relation object:
  if ($obj_rel->state) {
      # ...
  }

This method returns a true value if the state object is active or permanent. We expect that checking such a state will be a common occurence; therefore, this method overrides boolean operations (bool on the state object itself.

compare

  if ($state->compare($other_state) {
      print "States are not equal\n";
  }

  if ($state->compare($other_state) > 0) {
      print "$state is greater than $other_state\n";
  }

  if ($state->compare($other_state) < 0) {
      print "$state is less than $other_state\n";
  }

  # Or...
  if ($state == $other_state) {
      # ...
  }

  if ($state > $other_state) {
      # ...
  }

  if ($state < $other_state) {
      # ...
  }

Compares the state object to another state object and returns -1 if the state object is less than the other state object, returns 0 if they're equal, and returns 1 if the state object is greater than the other state object. This behavior allows the method to override the following operators:

<

>

<=

>=

==

!=

<=>

lt

gt

le

ge

eq

ne

cmp

name

  print "The state is ", $state->name;

  # Or...
  print "The state is $state";

Outputs a localized string representation the name of the state object. This method overloads the double-quoted string context ("" for Object::Relation::DataType::State objects.

Copyright and License

Copyright (c) 2004-2006 Kineticode, Inc. <info@obj_relode.com>

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Object::Relation

perl -MCPAN -e shell
install Object::Relation