/ 
Palm-Progect-1.0.2
River stage zero No dependents
/ Palm::Progect

NAME

Palm::Progect - Handler for Palm Progect databases.

SYNOPSIS

use Palm::PDB;
use Palm::Progect;

my $pdb = new Palm::PDB;

$pdb->Load('myprogect.pdb');

# Read in the categories into a simple array
my @categories = map { $_->{name} } @{$pdb->{'appinfo'}{'categories'}};

# For any given record, the category will be a number
# that indexes to the category array.
my @records    = @{$pdb->{'records'};

# ...
# manipulate categories and records somehow
# ...

# Save a new pdb
my $pdb = Palm::Progect->new();

my $appinfo = {};
Palm::StdAppInfo::seed_StdAppInfo($appinfo);
my $start_category_id = $appinfo->{lastUniqueID};

# Insert the "root record" if necessary
unless ($records[0]{'level'} == 0) {
    unshift @records, $pdb->new_Root_Record();
}

# Write the categories, in order,
# giving them sensible PDB numbers

my $i;
for ($i = 0; $i < @categories; $i++) {
    $appinfo->{'categories'}[$i] = {
        name    => $categories[$i],
        id      => $i ? $start_category_id + $i : 0,
        renamed => 0,
    };
}

$appinfo->{lastUniqueID} = $start_category_id + $i;

# Rebuild the parent/child relationships
@records = Palm::Progect->Repair_Tree(\@records);

$pdb->{'name'}    = 'my new progect';
$pdb->{'records'} = \@records;
$pdb->{'appinfo'} = $appinfo;

$pdb->Write('mynewprogect.pdb');

DESCRIPTION

The Progect PDB handler is a helper class for the Palm::PDB package. It allows you to load and save Progect databases.

Generally, you load a Progect PDB file into memory, manipulate its records, and then save a new PDB file to disk.

Modifying a Progect database "in place" is not well supported or tested.

This module was largely written in support of the progconv utility, which is a conversion utility which imports and exports between Progect PDB files and other formats.

AppInfo block

The AppInfo block begins with standard category support. See Palm::StdAppInfo for details.

Records

The records of the Progect DB. A record is a node in the Progect tree. It has a description, type and date information, and can have a note.

Unlike nodes in a real tree, records in the Progect don't maintain parent/child relationships with other records. Instead, records have a level, which is an indication of how many steps they are indented.

A record's child will have a higher level than it's parent:

first record                                  (level 1)
    child of first record                     (level 2)
    second child of first record              (level 2)
        grandchild of first record            (level 3)
another record                                (level 1)

With the Palm::Progect module you can access the list of records via:

$record = $pdb->{records}[N]

Each record in the list is a hashref, containing keys for the various fields that a Progect record can have:

$record->{description}

A string, the text of the progect node.

$record->{level}

The indent level of the record. See above under Records.

$record->{note}

A string, the note (if any) attached to the progect node.

$record->{hasNote}

True if the record has a note, false otherwise

$record->{priority}

The priority of the record from 1 to 5, or 0 for no priority.

isAction
isProgress
isNumeric
isInfo

Any record can have one (and only one) of the above types.

If you are going to change the type of a record, remember to set all the other types to false:

undef $record->{isAction};
undef $record->{isProgress};
undef $record->{isNumeric};
$record->{isInfo} = 1;
numericActual

The numerator of a numeric record. If the numeric value of a record is 4/5, then the numericActual value is 4.

numericLimit

The denominator of a numeric record. If the numeric value of a record is 4/5, then the numericLimit value is 5.

$record->{completed}

Completed has different values depending upon the type of record. For action items, it is either 1 or 0, for complete or not complete.

For Progress items, it is a number between 1 and 100, indicating a percentage.

For Numeric items it is a number between 1 and 100 indicating the the integer percentage of the numericActual value divided by the numericLimit value.

$record->{DateDue}

The due date of record, in standard unix time (i.e. number of seconds since Jan 1, 1969).

To read this time value, use the localtime function:

my ($year, $month, $day);
if ($record->{hasDueDate}) {
    my ($day, $month, $year) = (localtime $record->{dateDue})[3,4,5];
    $year += 1900;
    $month += 1;

    print "The date of this record is $year/$month/$day\n";
}

To convert to this value when you are prepared to save the record, use the Time::Local module:

use Time::Local;
eval {
    $record{dateDue}      = timelocal(0,0,0,$day,$month-1,$year)
    $record{hasDueDate}   = 1;
};
$record->{hasDueDate}

True if the record has a due date, false otherwise.

$record->{hasToDo}

True if the record has a ToDo link, false otherwise.

$record->{opened}
$record->{hasNext}
$record->{hasPrev}
$record->{hasChild}

These properties are used by Progect to remember what the parent/child relationship between records is.

You shouldn't mess with these directly. Rather, call the Repair_Tree function before you save your PDB file.

CLASS METHODS

new

$pdb = new Palm::Progect;

Create a new PDB, initialized with the various Palm::Progect fields and an empty record list.

Use this method if you're creating a Progect PDB from scratch.

Repair_Tree

This utility routine takes a list of categories, and based upon their order and their level, determines their ancestral relationships, filling in the following properties as appropriate for each record:

hasNext
hasPrev
hasChild

Arguments: A List of records or a reference to one.

Returns: The list of records with relationships intact or a reference, if called in a scalar context.

Example:

my @records     = Palm::Progect->Rebuild_Relationships(@records);
my $records_ref = Palm::Progect->Rebuild_Relationships(\@records);

OBJECT METHODS

new_Record

$record = $pdb->new_Record;

Creates a new Progect record, with blank values for all of the fields. Returns the record.

new_Root_Record

$record = $pdb->new_Root_Record;

Creates and returns a new Root Progect record.

This is the invisible, unnamed record at level 0 at the head of the record list which 'contains' all other records. You never see this record in Progect, but it's necessary.

For Example:

unless ($records[0]{level} == 0) {
    unshift @records, $pdb->new_Root_Record;
}

ParseRecord

This is the method that reads the raw binary data of the Progect record and parses it into fields of the %record hash.

You should not need to call this method manually - it is called automatically for every record when you load a Progect database.

my $parsed_record = $pdb->ParseRecord(%raw_record);

PackRecord

This is the method that packs %records hash into the raw binary data of the Progect record.

You should not need to call this method manually - it is called automatically for every record when you save a Progect database.

my $raw_record = $pdb->ParseRecord(\%record);

AUTHOR

Michael Graham <mag-perl@occamstoothbrush.com>

Copyright (C) 2001 Michael Graham. All rights reserved. This program is free software. You can use, modify, and distribute it under the same terms as Perl itself.

The latest version of this module can be found on http://www.occamstoothbrush.com/perl/

SEE ALSO

progconv

Palm::PDB(3)

Palm::StdAppInfo(3)

http:://progect.sourceforge.net/