NAME

OP::Hash - Hashtable object

DESCRIPTION

Extends OP::Object to handle Perl HASH refs as OP Objects. Provides constructor, getters, setters, "Ruby-esque" collection, and other methods which one might expect a Hash table object to respond to.

INHERITANCE

This class inherits additional class and object methods from the following packages:

OP::Class > OP::Object > OP::Hash

SYNOPSIS

  use OP::Hash;

  my $hash = OP::Hash->new();

  my $hashFromNonRef = OP::Hash->new(%hash); # Makes new ref

  my $hashFromRef = OP::Hash->new($hashref); # Keeps orig ref

PUBLIC CLASS METHODS

• $class->assert(*@rules)

  Returns an OP::Type::Hash instance encapsulating the received subtyping rules.

  Really, don't do this. If you think you need to assert a Hash, please see "AVOIDING HASH ASSERTIONS" at the end of this document for an alternative approach.

PUBLIC INSTANCE METHODS

• $hash->collect($sub), yield(item, [item, ...]), emit(item, [item...])

  Ruby-esque key iterator method. Returns a new OP::Array, containing the yielded results of calling the received sub for each key in $hash.

  $hash->collect is shorthand for $hash->keys->collect, so you're really calling collect in OP::Array. yield and emit are exported by OP::Array. Please see the documentation for OP::Array regarding usage of collect, yield, and emit.

    #
    # For example, quickly wrap <a> tags around array elements:
    #
    my $tagged = $object->collect( sub {
      my $key = shift;
  
      print "Key $key is $object->{$key}\n";
  
      emit "<a name=\"$key\">$object->{$key}</a>";
    } );

• $self->each($sub)

  List iterator method. Runs $sub for each element in self; returns true on success.

    my $hash = OP::Hash->new(
      foo => "uno",
      bar => "dos",
      rebar => "tres"
    );
  
    $hash->each( sub {
      my $key = shift;
  
      print "Have key: $key, value: $hash->{$key}\n";
    } );
  
    #
    # Expected output:
    #
    # Have key: foo, value: uno
    # Have key: bar, value: dos
    # Have key: rebar, value: tres
    #

• $self->keys()

  Returns an OP::Array object containing self's alpha sorted keys.

    my $hash = OP::Hash->new(foo=>'alpha', bar=>'bravo');
  
    my $keys = $hash->keys();
  
    print $keys->join(','); # Prints out "bar,foo"

• $self->values()

  Returns an OP::Array object containing self's values, alpha sorted by key.

    my $hash = OP::Hash->new(foo=>'alpha', bar=>'bravo');
  
    my $values = $hash->values();
  
    print $values->join(','); # Prints out "bravo,alpha"

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

  Set the received instance variable. Extends OP::Object::set to always use OP::Hash and OP::Array when it can.

    my $hash = OP::Hash->new(foo=>'alpha', bar=>'bravo');
  
    $hash->set('bar', 'foxtrot'); # bar was "bravo", is now "foxtrot"

• $self->size()

  Returns the number of key/value pairs in self

• $self->isEmpty()

  Returns true if self's size is 0, otherwise false.

AVOIDING HASH ASSERTIONS

One might think to assert the Hash type in order to store hashtables inside of objects in a free-form manner.

OP could technically do this, but this documentation is here to tell you not to. A recommended approach to associating arbitrary key/value pairs with database-backed OP objects is provided below.

Do not do this:

  #
  # File: Example.pm
  #
  use OP qw| :all |;

  create "YourApp::Example" => {
    someInlineHash => OP::Hash->assert()
  };

Rather, explicitly create a main class, and also an extrinsics class which handles the association of linked values. Manually creating linked classes in this manner is not as quick to code for or represent in object form, but it mitigates the creation of deeply nested, complex objects and "sprawling" sets of possible values which may arise from systems with lots of users populating data. Something akin to the following is the recommended approach:

  #
  # File: Example.pm
  #
  # This is the main class:
  #
  create "YourApp::Example" => {
    #
    # Assertions and methods here...
    #
  };

  #
  # File: Example/Attrib.pm
  #
  # This is where we tuck extrinsic attributes:
  #
  use OP qw| :all |;
  use YourApp::Example;

  create "YourApp::Example::Attrib" => {
    exampleId => OP::ExtID->assert( "YourApp::Example" ),

    elementKey => OP::Str->assert(
      #
      # ...
      #
    ),

    elementValue => OP::Str->assert(
      # Assert any vector or scalar OP object class, as needed.
      #
      # OP::Str can act as a catch-all for scalar values.
      #
      # ...
    ),
  }

An extension of this approach is to create multiple extrinsincs classes, providing specific subtyping rules for different kinds of key/value pairs. For example, one might create a table of linked values which are always either true or false:

  #
  # File: Example: BoolAttrib.pm
  #

  use OP qw| :all |;
  use YourApp::Example;

  create "YourApp::Example::BoolAttrib" => {
    exampleId => OP::ExtId->assert( "YourApp::Example" ),

    elementKey => OP::Str->assert( ),

    elementValue => OP::Bool->assert( ),
  };
  

SEE ALSO

This file is part of OP.