NAME

OP - Compact prototyping of InnoDB-backed object classes

VERSION

This documentation is for version 0.304 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, ex/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

  name is a unique, secondary, human-readable key.

  For more information on named objects, see OP::Name.

• 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 attributes from the database 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",

    # ...
  };

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

• OP::Class - Abstract "Class" class

• OP::Class::Dumper - Introspection mix-in

• OP::Object - Abstract object class

• OP::Persistence - Storage and retrieval mix-in

• OP::Node - Abstract stored object class

• OP::Type - Instance variable typing

• OP::Subtype - Instance variable subtyping

OBJECT TYPES

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

• OP::Any - Wrapper for any type of variable

• OP::Array - List

• OP::Bool - Overloaded boolean

• OP::Code - Any CODE reference

• OP::DateTime - Overloaded time object

• OP::Domain - Overloaded domain name

• OP::Double - Overloaded double-precision number

• OP::EmailAddr - Overloaded email address

• OP::ExtID - Overloaded foreign GUID

• OP::Float - Overloaded floating point number

• OP::Hash - Hashtable

• OP::ID - Overloaded GUID

• OP::Int - Overloaded integer

• OP::IPv4Addr - Overloaded IPv4 address

• OP::Name - Unique secondary key

• OP::Num - Overloaded number

• OP::Ref - Any reference value

• OP::Rule - Regex reference (qr/ /)

• OP::Scalar - Any Perl 5 scalar

• OP::Str - Overloaded unicode string

• OP::TimeSpan - Overloaded time range object

• OP::URI - Overloaded URI

CONSTANTS & ENUMERATIONS

• OP::Constants - "dot rc" values as constants

• OP::Enum - C-style enumerated types as constants

HELPER MODULES

• OP::Utility - System functions required globally by OP

• OP::Exceptions - Errors thrown by OP

TOYS & TOOLS

• bin/oped - Edit OP objects using VIM and YAML

• bin/opid - Dump OP objects to STDOUT in various formats

• bin/opsh - Interactive and persistent Perl 5 shell

EXPERIMENTAL

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.

INFOMATICS

The infomatics classes are an attempt to replicate certain functionality of RRD using SQL and Perl.

• OP::Log - OP::RRNode class factory

• OP::RRNode - Round Robin Database Table

• OP::Series - Cooked OP::RRNode Series Data

• OP::SeriesChart - Image-based Series Visualizer

FOREIGN DB ACCESS

Foreign DB access classes are similar in function to Class::DBI, in that they are used to derive object classes from existing schemas. This is an inversion of how OP normally functions, since OP was designed to derive schemas from classes.

• OP::ForeignRow - Non-OP Database Access

• OP::ForeignTable - ForeignRow class factory

BULK TABLE WRITER

The Bulk writer provides an alternate method for saving objects, utilizing MySQL's LOAD FILE syntax.

• OP::Persistence::Bulk - Deferred fast bulk table writes

SEE ALSO

OP::Class, ex/cheat.html

OP is on GitHub: http://github.com/aayars/op

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

cpanm OP

perl -MCPAN -e shell
install OP