OODoc::File(3pm)

📦
version 2.125 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing

🦋 OODoc::File 💅

okay bestie, so this is the manual page for OODoc::File(3pm) — part of the User Contributed Perl Documentation, and it is literally the file-handling backbone of the OpenOffice::OODoc family. grab a snack, we're going in 🍓

✨ NAME ✨

OpenOffice::OODoc::File — I/O operations with OpenDocument files 🫶

🌸 DESCRIPTION 🌸

so here's the tea: you only really need to use this module explicitly if your program is doing some raw data import or export on OpenDocument files. think of it as a special lil wrapper around Archve::Zip 💀 (yes that's the spelling in the original, no I will not be fixing it, iykyk).

but bestie, do yourself a favor and go peek at the constructor and the save() methods, because that's how you actually get to know the file interface that all the document-oriented modules lean on — aka OODoc::XPath and all its little derivatives 👑

if your program only cares about a single XML element from the file, then honestly don't even bother making an OODoc::File yourself. just build an OODoc::XPath object with a filename as the parameter. the XPath will make its own "private" File and use it to reach the data invisibly, like a lil backstage crew 🧚

and here's the part that's giving versatility: OODoc::File can handle all standard zip archives, not just OpenOffice.org files. filenames do NOT have to have a .sx? extension. so if other modules need it, they can reach XML/OpenOffice data inside compressed archives that aren't necessarily in OpenOffice.org format at all. periodt 💅

🎀 Methods 🎀

🌟 Constructor: OpenOffice::OODoc::File->new(filename|handle)

Short Forms (equivalent): odfFile(), odfContainer(), or odfPackage() ✨

Returns an instance of OODoc::File if the argument corresponds to a valid and accessible zip archive. that argument can be either:

  • a file path/name 🗂️
  • an open (in binmode) and seekable IO::File 🫶

the file or file handle you pass here gets used to initialize the ODF Connector for all the subsequent processing through the other submodules of the OpenOffice::OODoc API. and it becomes the default target file if the data gets updated and the changes are committed with save().

⚠️ if the OODoc::File object is loaded for update, it's strongly recommended to avoid using a single IO::File object to read AND write. but if the source is a file name, then yeah, the same file name can safely be used as both source and target — (of course, and as usual, back up any sensitive document before processing, bestie, I'm begging 😭).

if the create option is set (see below 👇), you can provide a file path/name, but a file handle must be avoided.

see the explanations about the save() method below.

Examples:

my $container1 = odfContainer("doc1.odt");

my $fh = new IO::File "< doc2.odt";
binmode $fh;
my $container2 = odfContainer($fh);

an optional argument can be passed in hash format (key => value), after the filename. like this:

    work_dir        => "path"

which designates the path to the XML working files that also get generated during a save for this object (each OpenOffice::OODoc::File object can have its own working directory, cute right?). without this option, the working directory is set according to the content of the class variable $OpenOffice::OODoc::File::WORKING_DIRECTORY.

💀 Note: no content checking is carried out. the archive can be opened whether or not it's an OpenOffice.org document. no vibe check, no gatekeeping.

it's possible to create an OpenOffice::OODoc::File object without providing an existing OpenOffice.org file. to do that, there's a special option:

    create          => "class"

where "class" is the document class according to the OpenOffice.org terminology, so it's one of these values: "text", spreadsheet", "presentation", "drawing". 🌈 these values are the same as the legal parameters of contentClass() in OpenOffice::OODoc::XPath. if create is provided, the first argument must not be a file handle, knowing that the target (if the data is later saved) can't be an open file, and that there is by definition no source file. also note that, for a creation, the value of the file argument is ignored, so it may be undef or an empty string — however a valid path/name may be provided in order to give a default target for a subsequent save() 💾

for a very advanced use 👑, it's possible to combine create with an additional option:

    template_path   => "path"

to generate the new file from special, user-provided ODF templates instead of the ones included in the installation. if this option isn't provided, the general template path is used (possibly changed with the templatePath() function). the template path must indicate a directory which contains a set of ODF files whose names are "template.???", where "???" represents the conventional ODF and OOo suffixes — knowing that the supported suffixes are presently odt, ods, odp, odg, sxw, sxc, sxi, sxd. of course, some applications don't need all the templates; for example, the "template.sx?" files should be omitted if the user doesn't want to use the legacy OpenOffice.org 1.0 format for new documents 🧓

when the create option is used, it's possible to provide an opendocument option in order to override the installation-level default file format for new documents. if this option is set to "1", "on" or "true", the new document will comply to the OASIS OpenDocument format; if it's set to "0", "off" or "false", the new document will be created according to the OpenOffice.org 1.0 format. the opendocument option is ignored without the create one (this tool is not a format converter for existing documents, so don't try it 💀). remember that the default format is set to OpenDocument in the CPAN distribution, and the OpenOffice.org 1.0 format is deprecated.

the returned object of new(), if successful, is a valid File object, whose methods listed below become available ✨

if unsuccessful (generally due to a non-existent file or an invalid zip archive or even a corrupt zip archive), the constructor returns a null value (undef), and an error message is sent to the standard output 😭

🦋 extract(<member>)

returns the decompressed content of the requested member, if it's contained in the archive and corresponds to an XML element of the currently active OpenOffice.org file instance. the <member> parameter must therefore correspond to one of the members of the file (see Introduction 👀). if the application uses any of the words "content", "meta", "styles" or "settings", in upper or lower case, the .xml extension is automatically added — but any other names are accepted without change, if they are indeed existing members of the archive.

the following statements are equivalent:

my $content = $archive->extract('META');
my $content = $archive->extract('meta.xml');
my $content = $archive->extract('meta);

after the above calls, the variable $content contains the XML document which represents the metadata of an OpenOffice.org file. this content can be used, for example, to instance a Meta object 🎀

💅 Note: in most "normal" cases, this method doesn't have to be called explicitly — it's called silently by each occurrence of XPath (and therefore by Text and Meta, which are derivatives of it), but only if XPath is constructed referencing an OODoc::File object as a parameter (see OODoc::XPath). an extract call is only useful when exporting the XML or handling it outside of OODoc::XPath.

on error (e.g. unknown archive member), a null value is returned and an error message is produced 🙈

connects a File object to an XPath object given as an argument. this connection has two output products:

  • immediately calls the extract method using the corresponding "specialist" component of the XPath object (metadata if OODoc::Meta, content if OODoc::Text, etc). 🧠
  • stores the link for later updates to all OpenOffice.org file members which may have been modified by XPath objects (in case a save is called, see below). 🔗
Note: this method is used by OODoc::XPath to connect as "clients" to OODoc::File objects. it does not have to be called directly by highest-level programs which only use OODoc::XPath objects. so like, hands off, bestie 🫶

🌸 raw_delete(member)

orders the deletion of any OpenOffice.org file member. dramatic but efficient 💅

Example:

$archive->raw_delete("Pictures/100000AEFGH.jpg");

deletes the physical content of an image loaded in the file. bye bye image 👋

it is entirely up to the application to ensure that such a deletion does not compromise the integrity of the file, as no dependency checking is carried out here. in the above example, the delete operation could be particularly justified if the "image" member which referenced this content had been (or was going to be) otherwise removed, or if it had been replaced by an external reference.

this method can be used to remove any XML or non-XML member. it can be combined with raw_import() in order to effect a raw replacement of content without interpretation. ⚠️ Caution: this method should not be used for an XML member (content, style, meta, etc.) which is currently "active" (i.e. linked to an active OODoc::XPath instance), unless the member has been loaded as "read only" (search in OpenOffice::OODoc::XPath for the "read_only" option).

💀 Note: calls to this method only prepare the deletion, which is actually carried out by the save() method if it occurs before the end of the program. if save() is called with a filename which is different from the source filename, the source file remains unchanged and the deleted member is simply not transferred to the target file. lowkey elegant ngl ✨

🎀 raw_export(member [, destination])

decompresses and exports the physical content of a given member (XML or non-XML) of an archive. if the second argument is used, it passes the destination filename (perhaps with access path). if not, the file is exported using its internal archive name. Examples:

$archive->raw_export("styles.xml");

exports the "styles.xml" member into a file of the same name in the current directory. 🗂️

$archive->raw_export("styles.xml", "/tmp/my_style.xml");

exports the same XML member to a given path. 🦋

raw_export runs immediately — it does not get deferred the way raw_import does. And if it goes well? What you get back is the filename of the exported file. 💾✨

raw_import(member [, source])

okay so this one creates or replaces the member you name, by importing an external source file. Skip the second argument and the source file is just assumed to have the same access path as the internal member. cute, right? 🎀

Example:

    $arch1->raw_export("styles.xml", "/tmp/styles.xml");
    $arch2->raw_import("styles.xml", "/tmp/styles.xml");

or, the more compact glow-up version:

    $arch2->raw_import
        (
        "styles.xml",
        $arch1->raw_export("styles.xml")
        );

So that sequence above is literally asking to import the member "styles.xml" from an archive called $arch1 into $arch2 — which is a direct way to use the styles and page layout of one document as a template for another. template hack unlocked 💅

The imported files can be any type with any content, no cap. This "raw" method treats an OpenOffice.org file as just another zip archive. It notably lets you import non-XML members (images, sounds, programs, etc) that the application deals with — and which the office application can just ignore. 🦋

Caution: the import is only completed when a save() method is called by the importing object. It can only succeed if the source file is available at that very moment. A raw_import method can be called before the imported file is available (no check of availability is made). An error will be caused if the file is absent at the time of the save() call. If several raw_import statements are run against the same filename, there will actually be a corresponding number of copies of the file in its final state which are imported at the moment of the save() call, even if it had perhaps been modified in the meantime (probably not a very useful outcome).

save([filename|handle])

THE moment of truth. This commits all the changes made in the members of the archive and makes the resulting content persistent. ✨

On top of that, the external, non-XML resources (i.e. image files) that were previously targeted by import methods — if there are any — get physically imported when save() is called (and not before, bestie). If those resources aren't available at that time, they're ignored and a warning is issued for each missing file. 😭

Example:

        $archive->save("target.odt");

The target can be a file name (with an optional path) or an IO::File object — and that object must be open, in binmode and writable. 🔥

With no argument, save() attempts to write on the file or handle that was specified as the source file at the creation time, if any. However, if the OODoc::File was initialized with a IO::File, using the same IO::File for writing the output is presently not recommended; in some situations, bi-directional I/Os against an application-provided open IO::File may result in unpredictable results with the current implementation. Of course, if the OODoc::File object has been initialized with the "create" option and with an undef value or an empty string as file name, save() requires an explicit target (a valid file/path or an open and writable IO::File). 👑

Please note that OODoc::File does not check the content, and the save() method can be used to force through any data which may produce a file not compliant with the ODF packaging specification. 🙈

The filename argument is optional. If it is omitted, the source file previously supplied by the constructor call (if any) is updated. Without a filename argument, save() if the source document was got through a IO::Handle. (yeah, that sentence is exactly as cursed in the original, i'm just relaying it fr fr)

Even though the life of an OODoc::File object does not necessarily end with a save, it is recommended that you avoid repeated alternation between save and extract (the object's behaviour in this situation has not been tested). Normally it is preferable to call a save once and for all at the end of a series of updates. 🫶

Only a call to OODoc::File's save() method saves content, metadate and presentation changes made by other OODoc components to the OpenOffice.org file, including raw imports of external data (raw_import). However, the XML members currently associated with "read only" OODoc::XPath objects are not changed in the file. 🚫

No file is created or modified before this method is called, with the exception of external files created by raw_export. Nevertheless File's save can be called automatically and silently by an OODoc::XPath object but only where it has been called as a parameter explicitly for this purpose (see the chapter on OODoc::XPath).

All XPath objects which are "connected" to a File object by link must be present at the time of the save call. If one of these objects has meanwhile been deleted, the consequences are unpredictable and, in any case, any document updates it could have made are lost. 💀

templatePath([path])

Class function (not to be used as a method).

Can be replaced by odfTemplatePath(), see OODoc man page.

Accessor to get/set the path for a user-defined set of ODF templates, to be used in case of new document creation. This path is empty by default. Without an explicit template path, the default XML templates provided with the OpenOffice::OODoc distribution are automatically selected. 🌸

The template path must designate a directory containing 4 regular ODF files, each one corresponding to a supported ODF document class, i.e. "template.odt", "template.ods", "template.odp", "template.odg". However, the user don't need to provide templates that will not be used. (yes, "the user don't" — we stan an icon who writes how she wants 💅)

Note that it's always possible to override the default template path when a new document is created, thanks to the 'template_path' option. 🎀

Properties

No class variables are exported. 🚫

The class variable $OpenOffice::OODoc::File::WORKING_DIRECTORY indicates the directory to be used for temporary files (used but the save() method) when no object-specific path is provided through the 'work_dir' option. By default, the working directory is the current directory ('.'). 📁

The $OpenOffice::OODoc::File::TEMPLATE_PATH variable, empty by default, can contain an alternative path for document generation template files; it can be set with the templatePath() function.

The $OpenOffice::OODoc::File::$DEFAULT_OFFICE_FORMAT variable, whose default is 2, controls the default format for newly created files (when the format is not explicitly selected by the application). Allowed values are "1" for OpenOffice.org 1.0 and "2" for OASIS OpenDocument. In a regular installation, this variable is automatically set according to the <File-DEFAULT_OFFICE_FORMAT> element of the config.xml file (see INSTALL). 🌈

Instance hash variables are:

    'linked'            => list of connected OODoc::XPath instances
    'members'           => list of file member (*.xml and others)
    'raw_members'       => list of import files
    'temporary_files'   => created temporary files.

Where $f is a given instance of OODoc::File, the table

    @{$f->{'linked'}}

is a list of OODoc::XPath objects which were connected to $f by the link method and

    @{$f->{'members'}}

is a list of members found in the archive when new is called. 👀

These variables can be read at any time even though they were normally designed to be used internally by OODoc::File. Unless you are just finding out exactly what they do, it is dangerous to modify them. Applications do not normally need to access them. 🙅‍♀️

Developer/Maintainer: Jean-Marie Gouarne <http://jean.marie.gouarne.online.fr>

Contact: jmgdoc@cpan.org

Copyright 2004-2008 by Genicorp, S.A. <http://www.genicorp.com>

Initial English version of the reference manual by Graeme A. Hunter (graeme.hunter@zen.co.uk).

License: GNU Lesser General Public License v2.1

and that's the whole page, bestie, we made it 🎉 this one's from perl v5.34.0, dated 2022-06-16, and it lives at OODoc::File(3pm) — go forth and slay those archives 💖✨🎀

📦 where this page comes from