NAME

ODF::lpOD::Common - Common utilities provided by the Perl lpOD library

DESCRIPTION

This manual page describes miscellaneous functions and auxiliary features of the lpOD Perl implementation that are not directly linked to the lpOD functional specification.

Data conversion and type checking utilities

The utilities introduced in this section are implemented as exported functions. They may be used without package or object reference.

is_true(value),

Returns TRUE if the given value may be regarded as true (in the Perl lpOD implementation). The usual Perl true values are interpreted as TRUE, with the a few exceptions. The strings 'false', 'no', and 'off', like 0, undef, and the empty string, are regarded as FALSE.

The common constants TRUE and FALSE (corresponding to 1 and 0) may be used by the applications.

is_false(value)

Returns TRUE if the given value is undef, zero, an empty string, 'false', 'no', 'off'. Returns FALSE otherwise.

odf_boolean(value)

Translates in an ODF-compliant boolean value (i.e. 'true' or 'false') a Perl/lpOD boolean value. The result may be used as the value of any ODF boolean attribute.

is_odf_datatype(type)

Returns TRUE if the given argument is the name of a valid ODF data type for table cells or variable fields, FALSE otherwise. For example, the first instruction below returns TRUE and the second one returns FALSE:

        $check1 = is_odf_datatype('float');
        $check2 = is_odf_datatype('complexType');

odf_value(value, type)

Converts the given value according to the given type (which must be a regular ODF data type), and checks it if the value is already in ODF format.

The following example formats the current system date so the result may be used as the value of a date field in a document:

        $odf_date = odf_value(time(), 'date');

This function returns undef if the given value is not compatible with the given type.

Note: this function doesn't work for any type in the present development version.

iso_date(time)

Translates a numeric time into an ISO-8601, ODF-compliant date.

Without argument, returns the current date in ODF-compliant format.

numeric_date(odf_date)

Translates an ISO-8601 date, coming from an ODF document, into a Perl computable time value.

translate_coordinates(alpha_spreadsheet_coordinates)

Returns the zero-based row number and column number according to a string representing spreadsheet-like coordinated. For example "A1" gives (0, 0), "Z10" gives (9, 25), and so on. Note that the row number comes first in the result, while the column letter comes first in the argument.

translate_range(alpha_spreadsheet_range)

Returns the zero-based numeric coordinates of the two positions that define a range in a spreadsheet, according to an alphanumeric range expression. As an example, "B4:F12" gives (3, 1, 11, 5). Note that the given string must be separated in two part by a colon; each part is translated according to the same logic as translate_coordinates(), producing a list of 4 values.

External file control

file_parse(file_path)

Returns the base name and the directory path extracted from the given file path. The following example will return ("logo.png", "/usr/share/images/"):

        ($dir, $base) = file_parse("/usr/share/images/logo.png");

file_type(file_path)

Returns the MIME type of the resource corresponding to the given file path, or undef (without error) if the resource is not available, if the File::Type module is not installed, or if the resource is not supported by File::Type.

Beware: This function uses the File::Type logic and don't determine the type according to the file name suffix.

image_size(file_path)

Returns the size, expressed in points (pt), of the image corresponding to the given file path (if any), or undef (without error) if the Image::Size module is not installed, if the given file is not available, or if the image type is not supported by Image::Size.

The return value (if defined) is an array ref of 2 strings (the width and the height), each one containing a numeric value and terminated by "pt". This array ref may be directly used as the value of any size-related parameter or argument in the lpOD API.

General configuration

Some methods are provided by the lpod pseudo-object in order to get or set some configuration parameters.

Installation information

The info method returns some information about the current lpOD installation, as a string in scalar context, or as a hash in array context.

For example, the instruction 'say scalar lpod->info' produces an information string containing "ODF::lpOD", the CPAN package build date, and the current installation path, like in the example below:

 ODF::lpOD 1.106 2011-02-15T15:07:39 /usr/lib/perl5/site_perl/5.10.0/ODF/lpOD

The installation_path method returns the path of the ODF::lpOD module installation in the user's file system.

Color name translation

Knowing that lpOD allows the user to specify color codes for various objects, some codes may be replaced by symbolic names. A few hundreds of symbolic names and the corresponding values are defined by default, according to a standard Xorg/RGB vocabulary. The user may add custom color names thanks to load_color_map(), whose argument is the full path of a RGB text file whose format complies with the typical Xorg "rgb.txt".

The unload_color_map() removes every color name for the current process, while load_color_map() without argument restores the default name/code mapping. load_color_map() may be used repeatedly in order to cumulate several RGB files.

Two explicit color translation functions are provided:

• color_code(name) : returns the color code corresponding to the given color name, if known; ex: color_code('antique white') produces '#faebd7'; returns undef if the name is unknown;

• color_name(code) : returns a symbolic name, if any, corresponding to the given color code; ex: color_name('#faebd7') returns 'antique white'; returns undef if no name is known for this code.

Beware that different names may correspond to the same code, so at the end of the sequence below, $a may differ from $b:

        $c = color_code($a);
        $b = color_name($c);

Character sets handling

lpOD is (as soon as possible) locale- and platform- neutral, so its default input and output character set is always utf8 unless the user makes an explicit alternative selection.

All the text/attribute oriented methods of the odf_element may automatically convert the processed content from or to the local character set of the user. The default character set is utf8. If the user provides non-utf8 content, the input character set must be declared using the set_input_charset(), that is a lpOD installation method (not a document method). Example:

        lpod->set_input_charset('iso-8859-1');

If the user wants to get non-utf8 outputs from any content-extraction method, the output character set must be declared in a similar way through set_output_charset():

        lpod->set_output_charset('iso-8859-1');

Input and output charsets may be changed at any time, so the user may, for example, successively insert texts using various encodings (that could prove useful for document generation from heterogeneous web sources).

Beware that the input and output charsets are not always the same. The user could want, for example, populate a document from non-utf8 web pages, and in the same session export some content from the same to document to local log files or the console, that may require utf8 or a another character set (depending of the user's locale).

The currently active character sets may be checked using get_input_charset() and get_output_charset() (as methods of the lpod pseudo-object).

For the list of supported character sets, see the documentation of the Perl Encode module.

Warning information

The "lpod->debug()" method, when called with TRUE of FALSE as argument, switches on or off the debug flag. If this flag is on, the call stack is displayed with every error message of the lpOD API.

AUTHOR/COPYRIGHT

Developer/Maintainer: Jean-Marie Gouarne http://jean.marie.gouarne.online.fr Contact: jmgdoc@cpan.org

Copyright (c) 2010 Ars Aperta, Itaapy, Pierlis, Talend. Copyright (c) 2011 Jean-Marie Gouarné.

This work was sponsored by the Agence Nationale de la Recherche (http://www.agence-nationale-recherche.fr).

License: GPL v3, Apache v2.0 (see LICENSE).

cpanm ODF::lpOD

perl -MCPAN -e shell
install ODF::lpOD