README for Palm::PalmDoc

This module can format ASCII text into a PalmDoc PDB file.

Palm::PalmDoc can be used as follows.

# Example 1
use Palm::PalmDoc;
my $doc = PalmDoc->new({INFILE=>"foo.txt",OUTFILE=>"foo.pdb",TITLE=>"foo bar",COMPRESS=>1});
$doc->read_text();
$doc->write_text();

-or-

# Example 2
use Palm::PalmDoc;
my $doc = PalmDoc->new({OUTFILE=>"foo.pdb",TITLE=>"foo bar"});
$doc->compression(1);
$doc->body("Foo Bar"x100);
$doc->write_text();

-or-

#Example 3
use Palm::PalmDoc;
my $doc = PalmDoc->new();
$doc->body("Foo Bar"x1000);
$doc->title("Foo Bar Baz");
open(FOO,">foo.pdb") || die $!;
print FOO $doc->pdb_header(),$doc->body();
close(FOO);


Palm::PalmDoc provides the following functions :

* new(@params)

The constructor of Palm::PalmDoc. This function can accept parameters used to 
generate the PalmDoc file. Parameters accepted are INFILE, OUTFILE, TITLE 
and BODY. They need to be passed in hash context (or a list/array mimicking 
a hash). A reference to a hash is also accepted, as well as a reference to 
an array.

  my $doc = PalmDoc->new({INFILE=>"foo.txt",OUTFILE=>"foo.pdb"});

is same as 

  my $doc = PalmDoc->new(INFILE=>"foo.txt",OUTFILE=>"foo.pdb");

or as 

  my $doc = PalmDoc->new("INFILE","foo.txt","OUTFILE","foo.pdb");

Keys are always uppercased (even though they may not be passed as such). 
Possible keys are:

- INFILE
  The input filename

- OUTFILE
  The output filename

- TITLE
  The document title

- BODY
  The document body

- COMPRESS
  Boolean to indicate compression


* body($body)

This is a plain getter/setter function except that it also sets the required 
length. The same action can be performed by setting the appropriate hash 
key/value pair in the constructor or by using the read_text function.

  $doc->body("Foo Bar"x100);


* title($title)

This is a plain getter/setter function for the title. The same action can be 
performed by setting the appropriate hash key/value pair in the constructor.

  $doc->title("Foo Bar Baz");


* infile($filename)

This is a plain getter/setter function for the Input filename. The same 
action can be performed by setting the appropriate hash key/value pair in 
the constructor.

  $doc->infile("foo.txt");


* outfile($filename)

This is a plain getter/setter function for the Output filename.	The same 
action can be performed by setting the appropriate hash key/value pair in 
the constructor.

  $doc->outfile("foo.pdb");


* read_text()

This function uses the inputfile property to read the body from a file. It 
also sets the required length. This function returns the text read if 
successfull or a false if not successfull.	

  $doc->read_text();


* write_text()

This function uses the outputfile property to write the header and body to a 
file. The headers are generated by the pdb_header function. This function 
returns true if successfull or false if not successfull.

  $doc->write_text();


* pdb_header()

This function generates the correct PDB headers for the body and length. 
You only need to use this function if you're writing the body to a file 
manually since write_text() already used pdb_header. This function returns 
the generated header which should precede the converted body.

* compression($boolean)

This function toggles the compression. By default compression is off.
The same action can be performed by setting the appropriate hash 
key/value pair in the constructor.

  $doc->compression(1); #Turn PalmDoc Compression on


TODO

Since my primary goal was to port the core, most of the features present in
Bibelot are not included. 

DISCLAIMER

MOST of this code is borrowed from Bibelot (http://www.sourceforge.net/projects/bibelot/).
This code is released under GPL (GNU Public License). More information can be 
found on http://www.gnu.org/copyleft/gpl.html

VERSION

This is Palm::PalmDoc 0.0.6.


This Module was written by Hendrik Van Belleghem (beatnik@quickndirty.org)

SEE ALSO

Bibelot - http://www.sourceforge.net/projects/bibelot/

GNU & GPL - http://www.gnu.org/copyleft/gpl.html