lpOD presently supports global metadata, i.e. metadata that describe a whole document. Some of them are defined in the ODF specification, others may be defined by the applications.
Prior to any access to the metadata, the application have to instantiate an odf_meta object through the get_meta() method of an existing odf_document:
meta = document.get_part(META)
All the methods related to global metadata belong to the odf_meta object.
For each pre-defined elementary piece of metadata, lpOD provides both a read accessor and a write accessor, whose name are respectively get_xxx() and set_xxx(), where xxx is the mnemonic name of the target. For example, the title of the document may be got, then changed, through the following sequence:
meta = document.get_part(META)
old_title = meta.get_title()
meta.set_title("The new title")
The get_xxx() and set_xxx() accessors are available for the following elements:
creation_date: the date of the initial version of the document;creator: the name of the user who created the current version of the document;description: the long description (or subtitle);editing_cycles: the number of edit sessions (may be regarded as a version number);editing_duration: the total editing time through interactive software, expressed as a time delta;generator: the signature of the application that created the document;initial_creator: the name of the user who created the first version of the document;language: the ISO code of the main language used in the document;modification_date: the date of the last modification (i.e. ot the current version);subject: the subject of the document;title: the title of the document.
When used without argument, some set accessors may automatically set default
values, according to the capabilities of the runtime environment.
For set_creation_date() and set_modification_date(), the default
is the current system date. For set_creator() and set_initial_creator(),
the default is the identifier of the current system user. For
set_generator() the default is the system name of the current program (as
it would appear in a command line) or, if not available, the current process
identifier. If the execution environment can't provide such informations, no
default value is provided. set_editing_cycles(), without argument,
increments the editing_cycles indicator by 1.
Some methods pre-defined pieces of metadata contain multiple items, so they can't be get or set through the simple accessors described above.
Knowing that a document may be "tagged" by one or more keywords, odf_meta provides a get_keywords() method that returns the list of the current keywords as a comma-separated string. Conversely, set_keywords() allows the user to set a full list of keywords, provided as a single comma-separated string; the provided list replaces any previously existing keyword; this method, used without argument or with an empty string, just removes all the keywords. Example:
meta.set_keywords("ODF, OpenDocument, Python, Perl, Ruby, XML")
The spaces after the commas are ignored, and it's not possible to set a keyword that contains comma(s) through set_keywords().
set_keyword() appends a new, given keyword to the list; it's neutral if the given keyword is already present; it allows commas in the given keyword (but we don't recommend such a practice).
check_keyword() returns true if its argument (which may be a regular expression) matches an existing keyword, or false if the keyword is not present.
remove_keyword() deletes any keyword that matches the argument (which may be a regular expression).
Document statistic metadata may be get or set using get_statistics() or set_statistics(). The first one returns a hash table whose keys are ODF attribute names of statistic data, as defined in §3.1.18 of the ODF 1.1 specification (for example, meta:page-count, meta-character-count, and so on). The second one must be provided with a similar data structure. The application is responsible for the accuracy of the values provides through set_statistics(); there is no consistency check in the lpOD API between these values and the statistical data of the real document content.
Each user-defined metadata element has a unique name (or key), a value and a datatype.
The odf_meta API provides a get_user_fields() method that returns a hash array whose each element is a key-value pair and whose value is associated with a datatype.
Possible datatypes are float, date, time, boolean and string.
When used from a language with typed values, the data type is just the type of the value in the host language, so the stored datatype may be safely ignored. For non-typed languages, the record structure of the returned array is: name, value and type.
The set_user_fields() method allows the applications to set or change all the user-defined items. Its argument is an array with the same structure as the result as get_user_fields().
In order to individually process user defined metadata, get_user_field() and set_user_field() are provided, too. get_user_field() requires the name as its argument; it returns the value and (optionnally and according to the host language) the datatype. Symmetrically, set_user_field(), which requires a name and a value (and optionnally a datatype), creates or replaces user-defined individal item. When used without value, or with a null value, set_user_field() just removes the field (if any) corresponding to the given key. If the optional style argument is not provided and if the host language is not typed, the string style applies by default. Example:
meta.set_user_field("Development status", "Working draft")
meta.set_user_field("Security status", "Classified")
meta.set_user_field("Ready for release", "false", "boolean")