Palm::Progect - Handler for Palm Progect databases.
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', }, );
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.
progconv
These docs are for developers who want to manipulate Progect PDB files programatically.
PDB
You should be able to access all functions of the Palm::Progect system directly from the Palm::Progect module.
Palm::Progect
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).
load_db
import_records
import_prefs
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).
$progect->records
$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.
save_db
export_records
export_prefs
Currently the Preferences interface is not well defined and is mainly there to allow for future development. See "BUGS and CAVEATS".
Preferences
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.
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:
Suppress informational messages when loading and saving databases.
A reference to the list of records within the database. Each record is an object of type Palm::Progect::Record.
Palm::Progect::Record
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.
Palm::Progect::Prefs
Reference to the hash of user options passed to the new constructor. See the new constructor for details.
new
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 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.
version
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).
18
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 the records and prefs as a Progect database of version $version to the filename $filename.
$version
$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.
Import records from a file.
The options passed in %args are as follows:
%args
The file to import the records from.
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.
Text
Palm::Progect::Converter::Text
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.
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.
date_format
Palm::Progect::Converter::CSV
Export records to a file.
The file to export the records to. If blank, then the exported records will be written to STDOUT.
The conversion format to use when exporting the records.
For instance, specifying a format of Text will cause Palm::Progect::Converter::Text module to handle the export.
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', );
Import preferences from a file. Currently this is not supported.
Export preferences to a file. Currently this is not supported.
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.
has_child
has_next
has_prev
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 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.
Using a two digit date format will fail for dates before 1950 or after 2049 :).
Michael Graham <mag-perl@occamstoothbrush.com>
Copyright (C) 2002 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/
Palm::PDB(3)
http://progect.sourceforge.net/
To install Palm::Progect, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Palm::Progect
CPAN shell
perl -MCPAN -e shell install Palm::Progect
For more information on module installation, please visit the detailed CPAN module installation guide.