NAME

Fuse::PDF::FS - In-PDF implementation of a filesystem.

SYNOPSIS

    use Fuse::PDF::FS;
    my $fs = Fuse::PDF::FS->new({pdf => CAM::PDF->new('my_doc.pdf')});
    $fs->fs_mkdir('/foo');
    $fs->fs_write('/foo/bar', 'Hello world!', 0);
    $fs->save();

LICENSE

Copyright 2007-2008 Chris Dolan, cdolan@cpan.org

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DESCRIPTION

This is an implementation of a filesystem inside of a PDF file. Contrary to the package name, this module is actually independent of FUSE, but is meant to map cleanly onto the FUSE API. See Fuse::PDF and the mount_pdf front-end.

METHODS

$pkg->new($hash_of_options)

Create a new filesystem instance. This method creates a new root filesystem node in the PDF if one does not already exist. The only required option is the pdf key, like so:

   my $fs = Fuse::PDF::FS->new({pdf => $pdf});

Supported options:

pdf => $pdf

Specify a CAM::PDF instance. Fuse::PDF::FS is highly dependent on the architecture of CAM::PDF, so swapping in another PDF implementation is not likely to be feasible with substantial rewriting or bridging.

fs_name => $name

This specifies the key where the filesystem data is stored inside the PDF data structure. Defaults to 'FusePDF_FS', Note that it is possible to have multiple independent filesystems embedded in the same PDF at once by choosing another name. However, mounting more than one at a time will almost certainly cause data loss.

autosave_filename => undef | $filename

If this option is set to a filename, the PDF will be automatically saved when this instance is garbage collected. Otherwise, the client must explicitly call save(). Defaults to undef.

compact => $boolean

Specifies whether the PDF should be compacted upon save. Defaults to true. If this option is turned off, then previous revisions of the filesystem can be retrieved via standard PDF revert tools, like revertpdf.pl from the CAM::PDF distribution. But that can lead to rather large PDFs.

backup => $boolean

Specifies whether to save the previous version of the PDF as $filename.bak before saving a new version. Defaults to false.

$self->autosave_filename()

$self->autosave_filename($filename)

Accessor/mutator for the autosave_filename property described above.

$self->compact()

$self->compact($boolean)

Accessor/mutator for the compact property described above.

$self->backup()

$self->backup($boolean)

Accessor/mutator for the backup property described above.

$self->save($filename);

Explicitly trigger a save to the specified filename. If autosave_filename is defined, then this method is called via DESTROY().

$self->deletefs($filename)

Delete the filesystem from the in-memory PDF and save the result to the specified filename. If there is more than one filesystem in the PDF, only the one indicated by the fs_name above is affected. If no filesystem exists with that fs_name, the save succeeds anyway.

$self->all_revisions()

Return a list of one instance for each revision of the PDF. The first item on the list is this instance (the newest) and the last item on the list is the first revision of the PDF (the oldest).

$self->previous_revision()

If there is an older version of the PDF, extract that and return a new Fuse::PDF::FS instance which applies to that revision. Multiple versions is feature supported by the PDF specification, so this action is consistent with other PDF revision editing tools.

If this is a new filesystem or if the compact() option was used, then there will be no previous revisions and this will return undef.

$self->statistics()

Return a hashref with some global information about the filesystem. This is currently meant for humans and the exact list of statistics is not yet locked down. See the code for more details.

$self->to_string()

Return a human-readable representation of the statistics for each revision of the filesystem.

FUSE-COMPATIBLE METHODS

The following methods are independent of Fuse, but uses almost the exact same API expected by that package (except for fs_setxattr), so they can easily be converted to a FUSE implementation.

$self->fs_getattr($file)

$self->fs_readlink($file)

$self->fs_getdir($file)

$self->fs_mknod($file, $modes, $dev)

$self->fs_mkdir($file, $perms)

$self->fs_unlink($file)

$self->fs_rmdir($file)

$self->fs_symlink($link, $file)

$self->fs_rename($oldfile, $file)

$self->fs_link($srcfile, $file)

$self->fs_chmod($file, $perms)

$self->fs_chown($file, $uid, $gid)

$self->fs_truncate($file, $length)

$self->fs_utime($file, $atime, $mtime)

$self->fs_open($file, $mode)

$self->fs_read($file, $size, $offset)

$self->fs_write($file, $str, $offset)

$self->fs_statfs()

$self->fs_flush($file)

$self->fs_release($file, $mode)

$self->fs_fsync($file, $flags)

$self->fs_setxattr($file, $key, $value, \%flags)

$self->fs_getxattr($file, $key)

$self->fs_listxattr($file)

$self->fs_removexattr($file, $key)

HACKS

ENOATTR()

POSIX is missing a constant this error number (at least, not on Mac 10.4). If we detect that it is missing at runtime, we attempt to replace it by: 1) reading errno.h, 2) falling back to EIO.

See Fuse::PDF::ErrnoHacks.

SEE ALSO

Fuse::PDF

CAM::PDF

AUTHOR

Chris Dolan, cdolan@cpan.org