/ 
persist-0.3.1
/ Persist

NAME

Persist - This class contains constants and helpers for the Persist framework

SYNOPSIS

use Persist qw(:constants);

# ... use 'em ...

DESCRIPTION

If you are looking for usage information related to Persist the best starting place is Persist::Source.

This class contains constants and help functions for the Persist framework. There are two sets of constants: types and indexes. The helper functions are described below.

TYPES

The types are:

VARCHAR

Limited length variable length string. Use of this type should be following by a single numeric value which is the maximum number of characters that should be used in values stored in this type of column. The maximum limit of data that may be stored in a VARCHAR will depend greatly upon the implementation. It is suggested that the drivers try to use a type that will allow up to 5000 characters to be stored.

INTEGER

Integer value type. Takes no arguments and should store any 32-bit integer value.

AUTONUMBER

Integer sequence type. This column provides a unique default value upon insertion. It takes no arguments and should be type equivalent to INTEGER. Columns with this type should not be explicitly set during insertion or update. The driver may choose to make such attempts exceptional.

BOOLEAN

Boolean value that is true (1) or false (0) or NULL (undef). It takes no arguments. Some database backends will not support this directly, but it should always be simulated by the driver.

REAL

A real number value. This should be used for Perl's floating point values. It takes no arguments and database should try to support values up to double precision floating point values and be at least as accurate.

TIMESTAMP

A date/time value. This should store a date and time value accurate to the second (there's no need to note leap seconds). This should be able to store as wide of a date range as reasonble. Accuracy of dates is a very difficult prospect whenever moving more than a century in any direction, so very little standardization can realistically be expected. Values of this type are represented in Perl as a string in the format ECCYYMMDDhhmmssTTTTT where all fields are completely padded with zeros (0).

The fields are:

E is the epoch and is either '1' for AD or '0' for BC;
CC is the century minus one (21st century is 20, duh);
YY is the century year (note that 00 is an invalid year in the first century of either epoch);
MM is the month index based at 0 (0 is January, 11 is December);
DD is the day of month based at 1 (the last day of the month in January is 31);
hh is the hour of the day ranging from 0 to 23;
mm is the minute of the hour ranging from 0 to 59;
ss is the second of the minute ranging from 0 to 59; and
TTTTT is the timezone where the first character is either '+' or '-' to mark the direction of change from UTC and other four characters are a value between 0000 and 1200 to mark the number of whole minutes difference from UTC--UTC may be specified as either "-0000" or "+0000". A date with a time zone of UTC will be said to be "normalize".

It is probably safe to assume that dates for any modern time are according to the Gregorian calendar, but may belong to a related calendar when dates are listed from more than a few centuries past. (For information on the history of calendars and how they have been manipulated beyond all comprehension, I suggestion seeing http://astro.nmsu.edu/~lhuber/leaphist.html.)

INDEXES

The indexes are:

PRIMARY

This is the key that is used to uniquely identify the row. Duplicates should not be allowed and there should always be a value stored in this column (that is, it should never be NULL/undef). All tables must exactly one primary index.

This takes an array reference naming all the columns that are in the index. For example,

[ PRIMARY, [ 'someid', 'name' ] ]
UNIQUE

This notes that the column(s) may be used to unique identify the row, but is not the primary index.

This takes an array reference naming all the columns that are in the index. For example,

[ UNIQUE, [ 'someid', 'name' ] ]

This links two tables by one or more columns.

This index takes three arguments. The first is an array reference naming all the local columns that reference the other table. The second is the name of the referenced table. The third is the an array reference naming the foreign columns that are referenced. The number of columns specified locally and foreign should be the same.

For example,

[ LINK, [ 'someid', 'name' ], 'another_table', [ 'anoid', 'name' ] ]

HELPER FUNCTIONS

The helper functions include the following:

@date = Persist->parse_timestamp($date)

Given a timestamp string, this function will parse the date into it's parts. The output array will contain 9 fields. The fields, in order, are:

0 - Epoch (either '0' or '1')
1 - Century (a value from '00' to '40')
2 - Year (a value from '00' to '99')
3 - Month (a value from '00' to '11')
4 - Day (a value with varying range but always in '01' and '31')
5 - Hour (a value from '00' to '23')
6 - Minute (a value from '00' to '59')
7 - Second (a value from '00' to '59')
8 - Timezone (a value from '-1200' to '+1200')
$date = Persist->format_timestamp(@date)

Taking an array structured in the same way as the date returned by Persist-parse_timestamp>, returns a string formatted as described in the section about the TIMESTAMP data type.

$date = Persist->timestamp_from_time([ $time ])

Taking a time as returned from the perl function "time" in perlfunc, creates a date formatted for a Persist source. If the time argument is left out then the current time is used.

$ts_norm = Persist->normalize_timestamp($timestamp)

This method takes the given timestamp and transforms it such that the timestamp uses UTC as it's timezone (as "+0000"). If an absolute time comparison is needed, the timestamp may now be compared using the lexigraphic comparison operators (eq, ne, le, ge, lt, gt, cmp).

This method assumes that timezones aren't a relevent fact of dates in B.C. That is, it will not properly handle timezone normalization if trying to adjust them for a date in the previous epoch.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@users.sourceforge.net>

COPYRIGHT AND LICENSE

Copyright (c) 2003, Andrew Sterling Hanenkamp
All rights reserved.

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met:

  * Redistributions of source code must retain the above copyright 
    notice, this list of conditions and the following disclaimer.
  * Redistributions in binary form must reproduce the above copyright 
    notice, this list of conditions and the following disclaimer in 
    the documentation and/or other materials provided with the 
    distribution.
  * Neither the name of the Contentment nor the names of its 
    contributors may be used to endorse or promote products derived 
    from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.