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

NAME

Palm::Progect - Handler for Palm Progect databases.

SYNOPSIS

use Palm::Progect;
use Palm::Progect::Constants;

my $progect = Palm::Progect->new('options' => { 'quiet' => 1 });

$progect->load_db(
    file    => $some_file,
);

$progect->export_records(
    file    => $some_other_file,
    format  => 'text',
    options => {
        tabstop          => 4,
        fill_with_spaces => 1,
        date_format      => 'dd-mm-yyyy',
    },
);

DESCRIPTION

Palm::Progect is a class for handling Progect Database files.

Progect is a hierarchical organizer for the Palm OS. You can find it at:

http://sourceforge.net/projects/progect

Palm::Progect allows you to load and save Progect databases (and to convert between database versions), and to import and export records in various formats.

If all you are interested in doing is converting from one format to another, you should probably look at the progconv utility program which does just that.

These docs are for developers who want to manipulate Progect PDB files programatically.

OVERVIEW

You should be able to access all functions of the Palm::Progect system directly from the Palm::Progect module.

Although the various database drivers and record converters all live in their own Perl modules, Palm::Progect is the interface to their functionality. It will transparently delegate to the appropriate module behind the scenes necessary.

You can load a Palm::Progect database from a Progect PDB file (via the load_db method), or import records and/or preferences from another format (such as Text or CSV) (via the import_records and import_prefs methods).

After a Progect database has been loaded or imported, you will have a list of records (in $progect->records), and a preferences object (in $progect->preferences).

Each record in $progect->records is an object of type Palm::Progect::Record.

for my $rec (@{ $progect->records }) {
    my $description = $rec->description;
    my $priority    = $rec->priority;
    print "[$priority] $description\n";
}

See Palm::Progect::Record for the format of these records.

Once you have loaded the records and preferences, you can save them to a Progect PDB file (via the save_db method), or export them to another format (such as Text or CSV), via the export_records and export_prefs methods.

Currently the Preferences interface is not well defined and is mainly there to allow for future development. See "BUGS and CAVEATS".

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.

Constructor

new

Create a new Palm::Progect object:

my $progect = Palm::Progect->new(options => \%Options);

options takes an optional hashref containing arguments to the system. Currently this allows only a single option:

quiet

Suppress informational messages when loading and saving databases.

Methods

records

A reference to the list of records within the database. Each record is an object of type Palm::Progect::Record.

prefs

A reference to the preferences object within the database. It is an object of type Palm::Progect::Prefs. For now the prefs object doesn't do very much and is mostly a placeholder to allow for future development.

options

Reference to the hash of user options passed to the new constructor. See the new constructor for details.

version

The Progect database version currently in use. This can come directly from the source database (loaded with load_db) or from the user (as an argument to load_db or save_db).

load_db(file => $filename, version => $version)

Load the Progect database file specified by $filename.

The version parameter is optional. Normally you would leave it out and let Palm::Progect determine the version from the database file itself.

If you specify a particular version, then Palm::Progect will attempt to read the database as that version. This would be useful for instance in the case of a corrupt PDB that indicates an incorrect version, or a PDB of a version that Palm::Progect does not support (but you want to try and see if it can read it anyway).

Currently supported versions are 18 (for Progect database version 0.18) and 23 (for Progect database version 0.23).

Progect database version 0.18 was used all the way up until Progect version 0.22, so if you saved a database with Progect 0.22, the database will be a version 0.18 database.

save_db(file => $filename, version => $version)

Save the records and prefs as a Progect database of version $version to the filename $filename.

If you do not specify a version then the latest available version is assumed, unless you have set version before, by a previous call to load_db or save_db.

Currently supported versions are 18 (for Progect database version 0.18) and 23 (for Progect database version 0.23).

Progect database version 0.18 was used all the way up until Progect version 0.22, so if you saved a database with Progect 0.22, the database will be a version 0.18 database.

import_records(%args)

Import records from a file.

The options passed in %args are as follows:

file

The file to import the records from.

format

The conversion format to use when importing the records.

Internally, this determines which module will do the actual conversion.

For instance, specifying a format of Text will cause Palm::Progect::Converter::Text module to handle the import.

append

If true, then import_records will append the records imported from file to the internal records list. If false, import_records will replace the internal records list with the records imported from file.

You can pass other options to import_records, and these will be passed directly to the module that does the eventual conversion. For instance:

$progect->import_records(
    file        => 'somefile.csv',
    format      => 'CSV',
    date_format => 'dd-mm-yyyy',
);

In this example, the value of date_format will get passed directly to the Palm::Progect::Converter::CSV module.

export_records(%args)

Export records to a file.

The options passed in %args are as follows:

file

The file to export the records to. If blank, then the exported records will be written to STDOUT.

format

The conversion format to use when exporting the records.

Internally, this determines which module will do the actual conversion.

For instance, specifying a format of Text will cause Palm::Progect::Converter::Text module to handle the export.

append

If true, then export_records will append the exported records to file. If false, export_records will overwrite file (if it exists) before exporting the records.

You can pass other options to export_records, and these will be passed directly to the module that does the eventual conversion. For instance:

$progect->export_records(
    file        => 'somefile.csv',
    format      => 'CSV',
    date_format => 'dd-mm-yyyy',
);

In this example, the value of date_format will get passed directly to the Palm::Progect::Converter::CSV module.

import_prefs

Import preferences from a file. Currently this is not supported.

export_prefs

Export preferences to a file. Currently this is not supported.

repair_tree

Goes through the list of records and repairs the relationships between them:

$progect->repair_tree;

Palm::Progect calls this method internally just before it saves a Progect database file.

That means:

  • Insert the root record (no description, level 0) if necessary.

  • Fix the parent/child/sibling relationships (has_child, has_next, has_prev, etc.) if necessary.

BUGS and CAVEATS

Categories

Palm::Progect reads and writes categories properly from and to Progect PDB files. As of version 0.25, Progect itself can read these categories properly.

Versions of Progect earlier than 0.25 may have problems reading the categories as saved by Palm::Progect.

This is due to the fact that Palm::Progect does not write the preferences block correctly.

As a result, when you load into an older version of Progect a database that you created with Palm::Progect, You will get a warning that "Your preferences have been deleted".

Progect will then reset the category list.

However, all of the records will still keep their references to the deleted categories.

So, if you select "Edit Categories..." and recreate the categories in the exact same order as they were before, the records will magically return to their proper categories.

Again, these steps are only required when you are using a version of Progect that is older than version 0.25.

Preferences

Preferences are not handled properly yet. They cannot be imported or exported, and they are not read from the Progect database file.

Additionally, in Progect version 0.23 and earlier, when you load a database created by Palm::Progect into Progect, you will get a warning that "Your preferences have been deleted". The preferences for the database will be reset to sensible defaults.

In Progect version 0.25, you will not get this warning.

Two-digit Dates

Using a two digit date format will fail for dates before 1950 or after 2049 :).

AUTHOR

Michael Graham <mag-perl@occamstoothbrush.com>

Copyright (C) 2002-2005 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)

http://progect.sourceforge.net/