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 datatype), 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 developement 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.
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 of 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 informations about the current lpOD installation, as a string in scalar context, or as a hash in array context.
Example:
say scalar lpod->info;The installation_path method returns the path of the ODF::lpOD module installation in the user's filesystem.
Local encoding
All the text/attribute oriented methods of the odf_element may automatically convert the processed content from or to the local encoding of the user. The local encoding is utf8 by default. It may be get or set using the common get_local_encoding or set_local_encoding. The latter must be called with an encoding name that is supported by the Perl Encode module (an alert is issued and nothing is changed if the given encoding is not supported).
Example:
my $old_encoding = $lpod->get_local_encoding;
lpod->set_local_encoding('iso8859-1');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.
COPYRIGHT & LICENSE
Copyright (c) 2010 Ars Aperta, Itaapy, Pierlis, Talend.
This work was sponsored by the Agence Nationale de la Recherche (http://www.agence-nationale-recherche.fr).
lpOD is free software; you can redistribute it and/or modify it under the terms of either:
a) the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. lpOD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with lpOD. If not, see http://www.gnu.org/licenses/.
b) the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0