/ 
OP-0.301
/ OP

NAME

OP - Compact Perl 5 class prototyping with object persistence

VERSION

This documentation is for version 0.301 of OP.

STATUS

The usual pre-1.0 warnings apply. Consider this alpha code. It does what we currently ask of it, and maybe a little more, but it is a work in progress.

SYNOPSIS

use OP;

A cheat sheet, cheat.html, is included with this distribution.

DESCRIPTION

OP is a Perl 5 framework for prototyping InnoDB-backed object classes.

This document covers the high-level concepts implemented in OP.

FRAMEWORK ASSUMPTIONS

When using OP, as with any framework, a number of things "just happen" by design. Trying to go against the flow of any of these base assumptions is not recommended.

Default Base Attributes

Unless overridden in __baseAsserts, OP classes always have the following baseline attributes:

  • id => OP::ID

    id is the primary key at the database table level.

    Objects will use a GUID (globally unique identifier) for their id, unless this behavior is overridden in the instance method _newId(), and __baseAsserts() overridden to use a non-GUID data type such as OP::Int.

    id is automatically set when saving an object to its backing store for the time. Modifying id manually is not recommended.

  • name => OP::Name

    OP uses "named objects". By default, name is a human-readable unique secondary key. It's the name of the object being saved. Like all attributes, name must be defined when saved, unless asserted as ::optional (see "undef Requires Assertion").

    The value for name may be changed (as opposed to id, which should not be tinkered with), as long as the new name does not conflict with any objects in the same class when saved.

    name may be may be keyed in combination with multiple attributes via the ::unique OP::Subtype argument, which adds InnoDB reference options to the schema.

    create "YourApp::Class" => {
  #
  # Don't require named objects:
  #
  name => OP::Name->assert(::optional),

  # ...
};

  • ctime => OP::DateTime

    ctime is the Unix timestamp representing the object's creation time. OP sets this when saving an object for the first time.

  • mtime => OP::DateTime

    mtime is the Unix timestamp representing the object's last modified time. OP updates this each time an object is saved.

undef Requires Assertion

Instance variables may not be undef, unless asserted as ::optional.

Object instances in OP may not normally be undef. Generally, if a value is not defined, OP currently returns undef rather than an undefined object instance. This may change at some point.

Namespace Matters

OP's core packages live under the OP:: namespace. Your classes should live in their own top-level namespace, e.g. "YourApp::". This will translate to the name of the app's database, unless overridden.

OBJECT TYPES

OP object types are used when asserting attributes within a class, and are also suitable for instantiation or subclassing in a self-standing manner.

The usage of these types is not mandatory outside the context of creating a new class-- OP always returns data in object form, but these object types are not a replacement for Perl's native data types in general usage, unless the developer wishes them to be.

These modes of usage are shown below, and covered in greater detail in specific object class docs.

DECLARING AS SUBCLASS

By default, a superclass of OP::Node is used for new classes. This may be overridden using __BASE__:

use OP;

create "YourApp::Example" => {
  __BASE__ => "OP::Hash",

};

or

package YourApp::Example;

use strict;
use warnings;

use base qw| OP::Hash |;

1;

ASSERTING AS ATTRIBUTES

When defining the allowed instance variables for a class, the assert() method is used:

#
# File: Example.pm
#
use OP;

create "YourApp::Example" => {
  someString => OP::Str->assert,
  someInt    => OP::Int->assert,

};

INSTANTIATING AS OBJECTS

When instantiating, the class method new() is used, typically with a prototype object for its argument.

#
# File: somecaller.pl
#
use strict;
use warnings;

use YourApp::Example;

my $example = YourApp::Example->new(
  name       => "Hello",
  someString => "foo",
  someInt    => 12345,
);

$example->save("Saving my first object");

$example->print;

IN METHODS

Constructors and setter methods accept both native Perl 5 data types and their OP object class equivalents. The setters will automatically handle any necessary conversion, or throw an exception if the received arg doesn't quack like a duck.

To wit, native types are OK for constructors:

my $example = YourApp::Example->new(
  someString => "foo",
  someInt    => 123,
);

#
# someStr became a string object:
#
say $example->someString->class;
# "OP::Str"

say $example->someString->size;
# "3"

say $example->someString;
# "foo"

#
# someInt became an integer object:
#
say $example->someInt->class;
# "OP::Int"

say $example->someInt->sqrt;
# 11.0905365064094

say $example->someInt;
# 123

Native types are OK for setters:

$example->setSomeInt(456);

say $example->someInt->class;
# "OP::Int"

ABSTRACT CLASSES & MIX-INS

OBJECT TYPES

The basic types listed here may be instantiated as objects, or asserted as inline attributes.

CONSTANTS & ENUMERATIONS

HELPER MODULES

EXPERIMENTAL*: INFOMATICS

Experimental classes are subject to radical upheaval, questionable documentation, and unexplained disappearances. They represent proof of concept in their respective areas, and may move out of experimental status at some point.

EXPERIMENTAL: SCHEDULING

EXPERIMENTAL: FOREIGN DB ACCESS

EXPERIMENTAL: INTERACTIVE SHELL

EXPERIMENTAL: BULK TABLE WRITER

SEE ALSO

OP::Class, OP::Type

AUTHOR

Alex Ayars <pause@nodekit.org>

COPYRIGHT

 File: OP.pm

 Copyright (c) 2009 TiVo Inc.

 All rights reserved. This program and the accompanying materials
 are made available under the terms of the Common Public License v1.0
 which accompanies this distribution, and is available at
 http://opensource.org/licenses/cpl1.0.txt