OODoc(3pm)

📦

version 2.125 · 3 versions

2.125 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing (latest)
2.125 · ubuntu jammy
2.125 · ubuntu resolute, ubuntu stonking

, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing

🌸 OODoc 💅

okay bestie, welcome to the OODoc(3pm) page — it's filed under User Contributed Perl Documentation, and it's the main character of the whole OpenOffice::OODoc universe. Sit down, grab a strawberry 🍓, we're doing this.

✨ NAME ✨

OpenOffice::OODoc — The Perl Open OpenDocument Connector. yes, that's really the name, "Open OpenDocument", it's giving recursive, we love her 💖

🦋 SYNOPSIS 🦋

        use OpenOffice::OODoc;

                        # get global access to the content of an ODF file
        my $document = odfDocument(file => "MyFile.odt");
                        # select a text element containing a given string
        my $place = $document->selectElementByContent("my search string");
                        # insert a new text element before the selected one
        my $newparagraph = $document->insertParagraph
                        (
                        $place,
                        position        => 'before',
                        text            => 'A new paragraph to be inserted',
                        style           => 'Text body'
                        );
                        # define a new graphic style, to display images
                        # with 20% extra luminance and color inversion
        $document->createImageStyle
                        (
                        "NewImageStyle",
                        properties      =>
                                {
                                'draw:luminance'        => '20%',
                                'draw:color-inversion'  => 'true'
                                }
                        );
                        # import an image from an external file, attach it
                        # to the newly inserted paragraph, to be displayed
                        # using the newly created style
        $document->createImageElement
                        (
                        "Image1",
                        style           => "NewImageStyle",
                        attachment      => $newparagraph,
                        import          => "D:\Images\Landscape.jpg"
                        );
                        # save the modified document
        $document->save;

like, look at her go 😭 she reads a doc, drops a paragraph in it, invents a whole image style, yeets in a jpg from your Windows drive, and saves. no cap. 🔥

🌈 DESCRIPTION 🌈

This toolbox is an extensible Perl interface that lets you do direct read/write operations on files complying with the OASIS Open Document Format for Office Applications (ODF) — aka the ISO/IEC 26300:2006 standard. periodt, it's a real standard.

It hands you a high-level, document-oriented language, and it shields you, the programmer, from all the crunchy little details of the file format. She can process different document classes: texts, spreadsheets, presentations, and drawings. She can retrieve or update styles and images, document metadata, and text content. 💅

OpenOffice::OODoc is designed for data retrieval and update in existing documents, and for full document generation. so like, both vibes. 🫶

💜 HOW TO USE THE DOCUMENTATION 💜

Read this chapter, and then the OpenOffice::OODoc::Intro one, before you even think about digging into the detailed documentation. trust, bestie, it's the move.

The reference manual is split into several separate chapters, described below. 👇

The OpenOffice::OODoc documentation, just like the API itself, is distributed amongst several manual pages on a thematic and technical basis. This section right here is a general foreword.

Each manual page corresponds to a Perl module — the one exception being OpenOffice::OODoc::Intro. It's strongly recommended you peek at the Intro before any other manual chapter, so you can get quick, practical knowledge of the big picture. 🌍 Another possible introductory read was published in The Perl Review (issue #3.1, dec. 2006) http://www.theperlreview.com, and there's an alternative presentation article, intended for French-reading users, downloadable at http://jean.marie.gouarne.online.fr/doc/perl_odf_connector.pdf 📚

The API is object-oriented and, with the exception of the main module (OpenOffice::OODoc itself), every module defines a class. Each module's features are documented in a manual page with the same name. BUT — and this is the plot twist — while some classes inherit from other ones, they bring a lot of features that aren't documented in their own manual page. The best example is OpenOffice::OODoc::Document: she contains a few method definitions by herself, but she's the most powerful class, because she inherits from four other classes, so her features are documented across five manual pages. iconic behavior, honestly 👑

Fortunately, the classes are defined on a functional basis. So, for example, to learn the text-related capabilities of a Document object, the user should hit the Text manual page before the Document one. iykyk.

The detailed documentation of the API is distributed according to the following list:

👑 OpenOffice::OODoc

This manual page — the one you're reading rn — contains (in the GENERAL FUNCTIONS section below) the description of a small number of miscellaneous functions, dedicated to controlling some general parameters, creating the main objects of the applications, or giving the user some basic utilities. It introduces the main object constructors, namely odfContainer(), odfDocument() and odfMeta(). ✨

👑 OpenOffice::OODoc::File

This manual page has the detailed info about the physical access to the ODF containers, i.e. the multipart, compressed files that contain the documents.

In some simple applications, this page can be ignored without risk. 🙈

👑 OpenOffice::OODoc::XPath

She describes all the common features provided by the corresponding class, available in every other class with the exception of OODoc::File. This page is so called because it essentially relies on XPath expressions to select the various document elements. However, beyond the XPath-based retrieval features, it lets the user update, create, or delete any element.

This manual page describes the common XML toolbox of OpenOffice::OODoc. It allows almost everything, and it may be appropriate for XML- and XPath-aware users who have some knowledge of the Open Document Format. On the other hand, it covers only the low level part of the API.

The high level part of OpenOffice::OODoc is covered by the ::Text, ::Image, ::Styles, ::Document and ::Meta manual chapters. However, the user should remember that ::XPath describes some common features which are not redundantly documented in the high level chapters, so this manual page can be useful even if the user don't need to work with explicit XPath expressions. (grammar said no, the docs said yes, we move 💀)

Note: by "high level", I don't suggest that OpenOffice::OODoc provides any stratospheric functionality. The "high level" API is a set of frequently needed features that are implemented in order to be used without knowledge of the ODF storage structure and without XML familiarity. The following example, which retrieves a section in a text document according to its name, illustrates the difference: while both return the same result, the second instruction, which is mnemonic and largely self-documented, belongs to a higher level than the first one:

        $section = $doc->getElement('//text:section[@text:name="Foo"]');
        $section = $doc->getSection("Foo");

👑 OpenOffice::OODoc::Text

This manual page describes all the high level text processing methods and lets the user's program deal with all the text containers (headers, paragraphs, item lists, tables, and footnotes). OpenOffice::OODoc::Text is dedicated to the text content and structure of any kind of document, and *NOT* to the so-called "text documents". As a consequence, this chapter describes all the methods which process ODF text containers in spreadsheets and presentations as well as in text documents. 🗂️

The set of covered text objects includes all the markup elements that may be inserted within paragraphs, such as variable text fields, notes, bibliography entries, bookmarks, index entries, text runs with special styles, hyperlinks, etc. 🦋

Whatever the document class, the ::Text part of OpenOffice::OODoc may apply to some style definitions, too. For example, a page style may specify a header and/or a footer that may contain paragraphs and other text elements.

👑 OpenOffice::OODoc::Image

This manual page describes all the graphics manipulation API — all the available syntax dedicated to inserting or removing images in the documents, and to controlling the presentation of these images. 🎀

Note that OpenOffice::OODoc does *NOT* include any graphical processing API; it just deals with the Open Document way to include and display images. It allows, for example, control over the color correction and the display size of an image in the context of a particular document — but not changing the image itself. she styles the pic, she does not edit the pic, bestie.

👑 OpenOffice::OODoc::Styles

This manual page describes the methods to use to control the styles of a document, knowing that each page layout, each text element, and each image is displayed or printed according to a style. This part of the documentation can be ignored if the user's programs are strictly content-focused and don't care about the presentation.

Note that some style definitions, such as master pages, can include text containers or images, which can be processed through methods provided by OpenOffice::OODoc::Text or OpenOffice::OODoc::Image.

👑 OpenOffice::OODoc::Document

This manual page describes some miscellaneous methods that deal simultaneously with text, presentation and/or images. So, in order to discover the capabilities of a "Document" object (created with ooDocument), the user should use the Text, Image, Styles AND Document manual pages. The OpenOffice::OODoc::Document class inherits all the features provided by the other classes, with the exceptions of OpenOffice::OODoc::File and OpenOffice::OODoc::Meta.

👑 OpenOffice::OODoc::Meta

This manual page describes all the available methods to use in order to control the global properties (or "metadata") of a document. Most of these properties are those an end-user can get or set through the File/Properties command with the OpenOffice.org desktop software. 💅

👑 OpenOffice::OODoc::Manifest

This manual page describes the manifest management API, knowing that the manifest, in an ODF file, contains the list of the file components (or "members") and the media type (or MIME) of each one. The text content, the style definitions, the embedded images, etc. are each one stored as a separate "member". so she's basically the packing list for the whole file 📦✨

🌟 GENERAL FUNCTIONS (EXPORTED) 🌟

`odfConnector()`

        Synonym: odfDocument()

`odfContainer($filename)`

Shortcut for OpenOffice::OODoc::File->new(). 🫶
This function returns a File object, that is the object representation of the physical package containing the text, the images and the style definitions of an ODF document.
See the OpenOffice::OODoc::File manual page for detailed syntax. 👀
See the OpenOffice::OODoc::Intro manual page to know why, in some situations, the using applications need or don't need to deal with explicit File objects.
Synonyms: odfFile(), odfPackage().

`odfDecodeText($ootext)`

odfDecodeText($odftext) — gimme a raw ODF (UTF-8) string and I hand you back the same thing translated into your local character set. Lowkey you never need this tho, because the normal text read/write methods of OpenOffice::OODoc already do the translation for you automatically — it's only here for when your app is out here bypassing the API entirely. 💅

🌸 odfDocument() 🌸

Shortcut for OpenOffice::OODoc::Document->new().

Okay bestie, this one is THE one. It's the most general document constructor, periodt. It creates and returns a brand new Document object. You can build it on top of an existing ODF file, or from XML / OpenDocument-compliant data you already loaded into memory. And with the right create parameter, it'll even make you a whole document from scratch. ✨

The Document class is stacked — it gives you methods for a lot of read/update operations across the text content, the graphics, and the presentation. So ooDocument() is the recommended first call when you want to get at a document for further processing.

See the OpenOffice::OODoc::Document manual page for the detailed syntax. iykyk 👑

odfEncodeText($ootext) — the reverse glow-up: give me a string made of local characters and I return it translated into an ODF-compliant (UTF-8) string. The string you pass has to match the active local encoding (peep odfLocalEncoding()). Again, the regular text read/write methods of OpenOffice::OODoc do this automatically, so this function is only for when your application needs to bypass the API. 🦋
odfFile($filename) — Synonyms: odfContainer(), odfPackage().
odfImage() — Shortcut for OpenOffice::OODoc::Image->new().

Generally not used explicitly by the applications.

This function returns a document object whose features are related to image element processing, which is a subset of the Document object.

See the OpenOffice::OODoc::Image manual page for detailed syntax. 🎀

odfLocalEncoding([character_set]) — Accessor to get/set the user's local character set (see $OpenOffice::OODoc::XPath::LOCAL_CHARSET in the OpenOffice::OODoc::XPath man page).

Example:

$old_charset = odfLocalEncoding();
odfLocalEncoding('iso-8859-15');

If the argument you give is an unsupported encoding, you get an error message and the old encoding is preserved. So this accessor is safer than just directly updating the $OpenOffice::OODoc::XPath::LOCAL_CHARSET variable. no cap 🫶

The default local character set is fixed according to the OODoc/config.xml file of your local OpenOffice::OODoc installation (see readConfig() below), or to iso-8859-1 if that file is missing or doesn't say anything about the local character set. By calling ooLocalEncoding() with an argument, your programs can override this default.

Note: the user can override this setting for a particular document, using the 'local_encoding' property of the document object (see the OpenOffice::OODoc::XPath manual page).

See the Encode::Supported (Perl) documentation for the list of supported encodings. 🌈

odfLocaltime() — Converts the numeric time given in argument to an ISO-8601 date (aaaa-mm-jjThh:mm:ss), knowing that this format is required for the stored content of any ODF-compliant date element or attribute.

The argument type is the same as for the standard Perl localtime() function, i.e. a number of seconds since the "epoch". It can be, for example, a value previously returned by a time() call.

Without argument, returns the current local time in ISO-8601 format.

Beware: The resolution of this function is limited to the second, unlike the ISO-8601 standard which supports an optional subsecond field. 💀

odfManifest() — Short cut for OpenOffice::OODoc::Manifest->new().

This function returns a Manifest object, giving access to the meta-information of the physical archive containing the document. 🔥

odfMeta() — Shortcut for OpenOffice::OODoc::Meta->new().

This function returns a Meta object. Such an object represents the global properties, or "metadata", of a document. It brings a set of accessors allowing the user to get or set some properties such as the title, the keyword, the description, the creator, etc.

See the OpenOffice::OODoc::Meta manual page for details. 💖

odfPackage($filename) — Synonyms: odfContainer(), odfFile().
odfReadConfig([filename]) — Creates or resets some variables of the API according to the content of an XML configuration file. Without argument, this function looks for 'OODoc/config.xml' under the installation directory of OpenOffice::OODoc. In any case, the provided file must have the same XML structure as the config.xml file included in the distribution, so:

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <OpenOffice-OODoc>
        <XPath-LOCAL_CHARSET>my_charset</XPath-LOCAL_CHARSET>
        <Styles-COLORMAP>my_colormap_file</Styles-COLORMAP>
        <File-WORKING_DIRECTORY>my_path</File-WORKING_DIRECTORY>
        <File-DEFAULT_OFFICE_FORMAT>2</File-DEFAULT_OFFICE_FORMAT>
        <BUILD_DATE>cpan_package_build_date</BUILD_DATE>
        <INSTALLATION_DATE>my_installation_date</INSTALLATION_DATE>
    </OpenOffice-OODoc>
</config>

In the example above, "my_oo_date" should be replaced by a regular ISO-8601 date (YYYY-MM-DDThh:mm:ss).

Elements out of the <OpenOffice-OODoc> element are ignored. Any element included in <OpenOffice-OODoc> sets or update a variable with the same name and the given value in the space of the OpenOffice::OODoc package. So, for example an element like

<strange_thing>a strange value</strange_thing>

will make a new $OpenOffice::OODoc::strange_thing variable, initialized with the string "a strange value", available for any program using OpenOffice::OODoc.

Attributes and sub-elements are ignored.

Strings with characters larger than 7 bits must be encoded in UTF-8.

Any '-' character appearing in the name of an element is replaced by '::' in the name of the corresponding variable, so, for example, the <XPath-LOCAL_CHARSET> element controls the initial value of $OpenOffice::OODoc::XPath::LOCAL_CHARSET.

All the variables defined in this file, are the file itself, are optional.

The <INSTALLATION_DATE> element is not used by the API; it's provided for information only. It allows the user to get (in OpenOffice format) the date of the last installation of OpenOffice::OODoc, through the variable $OpenOffice::OODoc::INSTALLATION_DATE. In the default config.xml provided with the distribution, this element contains the package generation date.

The <BUILD_DATE> element is the date of the CPAN package.

This function is automatically executed as soon as OpenOffice::OODoc is used, if the OODoc/config.xml configuration file exists. ⭐

odfStyles() — Shortcut for OpenOffice::OODoc::Styles->new().

Generally not used explicitly by the applications.

This function returns a Styles object, that brings a subset of the Document object. In can be used in place of odfDocument() if the calling application needs some style/presentation manipulation methods only. Note the 's' at the end of 'Styles': this object doesn't represent a particular style; it represents a set of styles related to a document.

See the OpenOffice:OODoc::Styles manual page for detailed syntax. 🧚

odfTemplatePath([path]) — Shortcut for OpenOffice::OODoc::File::templatePath().

Accessor to get/set an alternative path for the ODF template files used to create new documents.

The template path must designate a directory containing 4 regular ODF files, each one corresponding to an supported ODF document class, i.e. template.odt, template.ods, template.odp, template.odg. 🌸

odfText() — Shortcut for OpenOffice::OODoc::Text->new().

Generally not used explicitly by the applications.

This function returns a Text object, that brings a subset ot the Document object. It can be used in place of ooDocument() if the calling application is only text-focused (i.e. if it doesn't need to deal with graphics and styles). The processed document can contain (and probably contains) graphics and styles, but the methods to process them are simply not loaded.

See the OpenOffice::OODoc::Text manual page for detailed syntax. 💜

odfTimelocal() — Translates an ODF-formatted date (ISO-8601) into a regular Perl numeric time format, i.e. a number of seconds since the "epoch". So, the returned value can be processed with any Perl date formatting or calculation function.

Example:

my $date_created = odfTimelocal($meta->creation_date());
$lt = localtime($date_created);
$elapsed = time() - $date_created;
print "This document has been created $date_created\n";
print "$elapsed seconds ago";

This sequence prints the creation date of a document in local time string format, then prints the number of seconds between the creation date and now. Note that the creation_date() method used here works with the meta-data document part only (see OpenOffice::OODoc::Meta for details about this method).

Note: This function requires the Time::Local Perl module. 🍓

odfWorkingDirectory([path]) — Accessor to get/set the working directory to use for temporary files. Short-lived temporary files are generated each time the save() function (see OpenOffice::OOdoc::File) is called. If case of success, these files are automatically removed when the call returns, so the user can't view them. If something goes wrong during the I/O processing, the temporary files remain available for debugging. In any case, a working directory is necessary to create or update documents. However, OpenOffice::OODoc can be used without available working directory in a read-only application. 🙈

…anyway bestie, where were we? oh right, the working-directory tea ☕

The default working directory lowkey depends on the OODoc/config.xml file of your local OpenOffice::OODoc installation. If that file is missing, or if it doesn't contain a <File-WORKING_DIRECTORY> element, then the working directory is just "." — aka the current working directory of the user's application. very "we'll figure it out" of it 💅

If an argument is given, it replaces the current working directory. simple as that.

Heads up 💀 a warning gets issued if the (existing or newly set) path is not a directory with write permission. After that warning, your application can still run, but any attempted file update or creation fails. like, every single one. no cap.

This accessor sets only the default working directory for the application. A special, separate working directory can be set for each OOo document — see the manual page for OpenOffice::OODoc::File for details, if needed. 👑

CAUTION: a odfWorkingDirectory() call can't change the working directory of a previously created File object. So consider this code sequence, bestie, look at it carefully:

        my $doc0 = ooDocument(file => 'doc0.odt');
        odfWorkingDirectory('C:\TMP');
        my $doc1 = ooDocument(file => 'doc1.odt');

In this example, all the write operations related to the $doc0 document will use the default working directory, while the ones related to $doc1 will use C:\TMP. it's giving "order of operations matters" ✨

`odfXPath()`

Shortcut for OpenOffice::OODoc::XPath->new(). ✨

Generally not used explicitly by the applications. (iykyk)

This function returns an XPath object, that brings all the low level XML navigation, retrieve, read and write methods of the API. The XPath class (in the OpenOffice::OODoc context) is an OpenOffice-aware wrapper for the general XML::Twig API. Unless you are a very advanced user and you have a particular hack in mind, you should never need to explicitly create an XPath object. But you must know that every method or property of this class is inherited by the Text, Image, Styles, Document and Meta objects. So the knowledge of the corresponding manual page could be useful. 🫶

See the OpenOffice::OODoc::XPath manual page for detailed syntax.

`ooDocument()`

Synonyms: odfDocument(), odfConnector(). 💖

`ooDecodeText()`

See odfDecodeText().

`ooEncodeText()`

See odfEncodeText().

`ooFile($filename)`

Synonyms: odfContainer(), odfPackage(), odfFile(). 🎀

`ooImage()`

Synonym: odfImage().

`ooLocalEncoding()`

See odfLocalEncoding().

`ooLocaltime([$time_value])`

See odfLocaltime()

`ooManifest()`

Synonym: odfManifest().

`ooMeta()`

Synonym: odfMeta().

`ooReadConfig()`

See odfReadConfig().

`ooStyles()`

Synonym: odfStyles().

`ooTemplatePath()`

See odfTemplatePath().

`ooText()`

Synonym: odfText().

`ooTimelocal($oodate)`

See odfTimelocal()

`ooWorkingDirectory()`

See odfWorkingDirectory().

`ooXPath()`

Synonym: odfXPath(). ⭐

🌸 AUTHOR/COPYRIGHT 🌸

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

Contact: jmgdoc@cpan.org

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 a wrap, bestie 🎀🦋 this whole thing shipped as perl v5.34.0, dated 2022-06-16, and it's literally called OODoc(3pm) — go forth and document your spreadsheets, mwah 💅💖

📦 where this page comes from

debian bookworm: libopenoffice-oodoc-perl 2.125-4 · LGPL-2.1-only
debian trixie: libopenoffice-oodoc-perl 2.125-4 · LGPL-2.1-only
ubuntu noble: libopenoffice-oodoc-perl 2.125-4 · LGPL-2.1-only
ubuntu questing: libopenoffice-oodoc-perl 2.125-4
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms