OpenOffice::OODoc::Text - The text processing submodule of OpenOffice::OODoc
This man chapter describes the text-oriented methods of OpenOffice::OODoc, implemented by the OpenOffice::OODoc::Text class, and inherited by the OpenOffice::OODoc::Document class.
This class should not be explictly used in an ordinary application, because all its features are available in the OpenOffice::OODoc::Document class, in combination with other features. Practically, the present manual is provided to describe the text-oriented features of OpenOffice::OODoc::Document (knowing that these features are technically supported by the OpenOffice::OODoc::Text component of the API).
These features are text-oriented, but can be used against any class document, such as spreadsheets or presentations as well as text documents.
The OpenOffice::OODoc::Text class is a specialist derivative of OpenOffice::OODoc::XPath for XML elements which describe the text content of OOo/ODF documents. Here, "text content" means containers that can host text content (i.e. tables, lists...) as well as flat text.
Knowing that the "styles.xml" member of an OpenOffice.org file can contain text (because some style definitions, such as page headers or footers, can contain text), the presently described features can be used against this member as well as the "content.xml" member.
This module Should be used in combination with OpenOffice::OODoc::Styles, via the OpenOffice::OODoc::Document class, if the application has to handle detailed presentation parameters of text elements. This is because such parameters are held in styles elements and not in the text elements themselves, according to the principle of separation of content and presentation which is one of the foundations of the OpenDocument format.
Short Form: ooText(<parameters>) See OpenOffice::OODoc::XPath->new The XML member loaded by default is 'content.xml'. The most common creation method is like this: my $doc = ooText(file => 'my_file.odt'); This constructor should generally not be called directly, because it's inherited by ooDocument(). Other parameters can be supplied as options (see the properties list at the end of the chapter). Example: my %delim = ( 'text:h' => { begin => '\sect{', end => '}' }, 'text:list-item' => { begin => '\item' } 'text:footnote-body' => { begin => '\footnote{', end => '}' } ); my $doc = ooText ( file => 'filename.odt', paragraph_style => 'My Paragraphs', header_style => 'My Headers', delimiters => { %delim } ); This technique gives the default styles to be used when creating new text elements. It also gives the particular delimiters (in this case LaTeX style markers) to be used at the beginning or end of some elements (in this case headers, list elements, footers) where the text is to be exported "as is". See the getText method of OODoc::Text for information about exporting text.
Copies an existing element of any type and appends it to the end of the document body. No new element is created.
In a presentation or drawing document, appends a new page at the en of the document. Possible options are: name => page name (unique) id => page numeric ID (unique) style => page style name master => master page name Returns the new draw page element if successful, undef if not.
Creates a new header of any level and appends it to the end of the document. Options are given as a hash [key => value]: 'text' => <header text> 'level' => header level, default is 1 'style' => header style, default is 'Heading 1' Examples: $doc->appendHeader(text => 'Next section'); adds the text 'Next section' as 'Header 1'. $doc->appendHeader ( text => 'Chapter Conclusion', level => '2', style => 'Heading 2' ); adds a level 2 header to the end of the text body. You can give any XML attribute to the new header except for style or header level. In this case, the program must construct a hash containing pairs of key-values for the attributes you want to create and pass it using the 'attribute' option. Example: my %attr = ( 'att1' => 'value1', 'att2' => 'value2' ); $doc->appendHeader ( text => 'Attributes are important', level => '1', style => 'Chapter header', attribute => %attr ); If the 'text' option is empty, the header is created with an empty content. Note: this method can only be used with a new header i.e. it adds while it creates. To add an already available element using getHeader from the same document or from another document, use the appendElement method instead which is inherited from OODoc::XPath.
Adds a new item to a list (ordered or unordered). The first argument is the existing list element (created using getOrderedList or getUnorderedList, for example). Options are the same as for appendParagraph. If the 'style' option is absent, the element is inserted according to the following rule:
Creates a new (empty) list and appends it to the end of the document. In OpenOffice.org 1 documents, an unordered list is the default, and if the 'type' option is given with the value 'ordered', then an ordered list is created. In Open Documents, the 'type' option is ignored because there are generic lists only. The 'style' options controls the list's style (as opposed to each item's style). If absent, the list takes the default paragraph style (see appendParagraph). Like appendParagraph, this method actually creates a new list element. To copy an existing list in the same document or in another, use appendElement or replicateElement instead.
Creates a new paragraph and appends it to the document. Options: 'text' => <paragraph text> 'style' => <paragraph style> An 'attribute' option is also available under the same conditions as for the appendHeader method (see above). If the 'text' option is empty, calling this method is the equivalent of adding a line feed. If the 'style' option is empty, the style from the 'paragraph_style' property of the OODoc::Text instance is used. By default, the new paragraph takes place at the end of the document. But it's possible to attach it as the last child of an existing text container (ex: a table cell). To do so, the container must be provided through an 'attachment' option. For example, to append a new paragraph in a table cell, one can write my $cell = $doc->getCell("Table1", "B12"); $doc->appendParagraph ( text => "The cell, reloaded", attachment => $cell ); Note: this method can only be used with a new paragraph i.e. it adds while it creates. To add an already existing paragraph using getParagraph from the same document or from another document, use the appendElement or replicateElement methods instead which are inherited from OODoc::XPath, or even appendText below. Note: The repeated spaces are not properly processed, so any sequence of spaces (whatever its length) in the 'text' string is replaced by a single space in the target document. See setText() and extendText() in OpenOffice::OODoc::XPath.
Appends a row to the end of the given table either by reference, by logical name or by sequential number. By default, the new row is simply an exact copy of the preceding row (in terms of content and presentation). You can pass an options hash which will give certain attributes to the created row, under the same conditions as for the appendElement method of OODoc::XPath. The returned value is the created row element. Example: open SRC, '<', 'data.txt'; my $table = $doc->getTable("Table1"); my ($h, $l) = $doc->getTableSize($table); for (my $i = 0 ; my $record = <SRC> ; $i++) { last unless $record; chomp $record; my @data = split ';', $record; my $row = $i < $h ? $doc->getRow($table, $i) : $doc->appendRow($table); for (my $j = 0 ; $j < $l ; $j++) { $doc->cellValue($row, $j, $data[$j]); } } The above program reads a CSV format data file sequentially (one record per line, comma-separated fields). Each record is split and put into a row in table Table1. On reading each new record, the reference for the following row is loaded by getRow, until the total number of rows is reached (total obtained previously using getTableSize). If the table is already full, it is lengthened by a row using appendRow. The internal loop loads the read data into the row's cells (pre-existing or newly created). See the sections on getTable, getRow, getTableSize and cellValue for a better understanding of this example. However, if good performance is what you are after, massive repetition of this method is not recommended (e.g. for lengthening a table dynamically, row by row, whilst loading external data into it). Rather than running dozens or hundreds of successive appendRows, it would be better for the application to read the total number of records to be loaded (using, for example, select count if from a relational database or otherwise preloading the data into an ordinary Perl table) and create a table of appropriate size in advance using insertTable or appendTable.
Creates a new section with the given name, and appends it by default to the end of the document body. If the "attachment" option is provided, with an existing element as its value, the new section is appended in the context of this element. For example, if the value of "attachment" is an existing section, the new section is appended as the last sub-section of the existing one. A section may be used either to hold a local content or to insert a subdocument which can be reached through an external link. In order to insert a subdocument link instead of an ordinary section, the application must provide a "link" option whose value is either a local file path or an URL. Example: $doc->appendSection ( "Article", link => "http://mycompany.com/doc/article.odt" ); Other possible options: 'style' allows the application to explicitly select a style for the new section 'protected' write-protects the section when the document is edited through OpenOffice.org; "true" or "false", default "false" 'key' in combination with "protected" => "true", write- protects the section by password (the value of "key" is not the real password, but an encrypted password, so the end-user will never remove the protection by simply typing the key as it is written in the program); see lockSection(), unlockSection() and sectionProtectionKey()
Creates a new table with the given name, number of rows and number of columns, and appends it by default to the end of the document body. The name must be unique within the document (the call is rejected if the name already exists). Returns the created table element if successful. 'rows' and/or 'columns', if omitted, are replaced by the 'max_rows' and 'max_cols' properties of the document (see the properties below). By default, the table is set to fit the entire width between the left and right margins with equal sized columns, cells of type string and without borders or background colour. Possible options: 'table-style' => table style 'cell-type' => default cell type 'cell-style' => default cell style 'text-style' => default cell text style The first option is the name of a table style which defines certain global properties for the table (width, background colour, etc.). See the OpenOffice::OODoc::Styles manual for information about styles. The second option is the cells' default data type. The main types available are string, float, currency, date, percentage. Caution: to be properly treated as having a numeric format in OOo/ODF, a cell needs more than to be just marked 'numeric'. If the cell really needs to be treated properly as a number, you must also give it a cell style which itself refers to a number style. The cell-style parameter can do this. However, even though the OODoc::Styles module is there to otherwise help you create and add styles from a program, this type of exercise can become very labour-intensive. We therefore recommend using basic tables created in advance from document templates or style libraries created from an office application, rather than creating complex number tables from code. The text-style option selects the paragraph style applicable to the text displayed in each cell. Once the table is created, you can obviously modify each cell's type and style individually. Example: my $table = $doc->appendTable ( "Rate", 22, 5, 'table-style' => 'Table1', 'text-style' => 'Text body' );
See appendRow.
Appends a text element, by default to the end of a document. Two type of usage are possible: If the 'attachment' option is used, which indicates an element reference, the new element is attached as a "child" element of the given element. This allows you to place text in special zones, other than in the document body, which is not appropriate in all applications. This method should be used to append unusual text elements (i.e. not paragraphs or headers) or existing elements (in its second usage type) of any type. Remember that: $doc->appendText('text:p', text => 'My text'); is the same as: $doc->appendParagraph(text => 'My text'); ('text:p' refers to a paragraph element, just as 'text:h' refers to a header element.)
Gets, and optionnally sets, the properties of a given (existing) bibliographic entry. The optionally updated properties are provides as a hash. The returned description is a hash. The first argument can be either the logical identifier of the entry (as it appears for the end-user) or a previously found bibliography entry element (see getBibliographyElements()). Example: my %desc = $doc->bibliographyEntryContent ( "GEN99", author => 'Genicorp', pages => 62 ); This sequence updates the "Author" and "Pages" values of the "GEN99" entry, then returns all the content of the entry in %desc. Caution: Several bibliography entries can have the same identifier. This method processes one element at a time. In the example above, only the first occurrence of the "GEN99" entries is updated. So, if the user needs to ensure that all the entries with the same identifier have the same content, the appropriate code should be something like: my @entries = $doc->getBibliographyElements("^GEN99$"); foreach my $entry (@entries) { $doc->bibliographyEntryContent ( $entry, author => 'Genicorp', pages => 62 ) } Caution: This method allows the user to create any new property and to put any value in any property, without control. So we recommend you to have a look at the Open Office XML specification and/or the OOo bibliographic project (http://bibliographic.openoffice.org) in order to know the generally accepted properties.
Puts a bookmark in a text element. Example: my $paragaph = $doc->selectElementByContent ("Eragon and Saphira"); $doc->bookmarkElement($paragraph, 'Mark'); puts a bookmark identified by "Mark" in a paragraph where a given text has been found (of course, the bookmark will remain even if the text of the paragraph is changed later). By default, the bookmark is put at the beginning of the text. But, thanks to the optional offset, it can be put at any position within the text of the bookmarked element.
Get/set the currency unit of a cell. If a currency is provided, the cell value type is automatically switched to 'currency'.
Accessor which returns the formula (or function) contained in the given table cell. Returns undef if no formula is found in the cell. The cell address is the same as for getCellValue(). If a formula is given as the last argument, it is put into the cell, overwriting any existing formula. No check of the syntax is carried out on the inserted formula. It is up to the application to insert a formula which conforms to OOo/ODF syntax. Example: $doc->cellFormula(1,3,2, "sum <C2:C5>"); Note 1: inserting or replacing a formula does not directly modify the value or text of the cell. Proper interpretation of a formula does not happen until the fields are updated when the document is reloaded into OpenOffice.org. Note 2: syntax and functionality of cell formulae differ greatly between the Writer and Calc applications.
In a spreadsheet document, get/set the span of a table cell, knowing that this span can be one or more columns. The cell addressing is the same as with getCell(). Example: $doc->cellSpan($table, "B4", 3); creates a 3-cell span from B4 in a spreadsheet. This method works only for horizontal expansion. The text of the covered cells (if any) is concatenated to the original content of the expanded cell (as in OOo Writer or Calc). Caution: when related to table cells, "span" has not the same meaning as when related to flat text (see getSpan() and setSpan()).
Get or set the style of a table cell.
Without the "value" argument: see getCellValue(). With "value" (and, optionnally, "text"): see updateCell().
Get/set the data type of a table cell. Note: If an application must convert a 'string' cell to a numeric one and fill it with a numeric value, cellValueType() must be called *before* cellValue(). Ex: my $cell = $doc->getCell('Sheet1', 4, 8); $doc->cellValueType($cell, 'float'); $doc->cellValue($cell, 12.34);
Returns the style name of the given column or replaces it with a new one. A column can be indicated either directly by reference or by the pair [table, column number]. The table itself can be indicated either by a table element, its number or its logical name. If the 'style' argument is given, it replaces the old column style. Giving a column a style is actually the only way to control the width of a column in a table. Example: $doc->columnStyle('Table1', 2, 'NewStyle'); Caution: columns are numbered beginning at 0.
This method creates appends a copy of a given table row to the header of the table. It may be called repeatedly, allowing multi-row header creation. A table header is a row, or a sequence of rows, that is displayed at the top of a table and repeated at the top of every page if the table is spanned across more than one page. The given row remains in place unchanged; it's used as a template for the new header row.
Get or set the default terminator character for text export. Example: $doc->defaultOutputTerminator("\n"); After this instruction, a line-break will be appended at the end of every paragraph or header exported by getText(), selectTextContent() or other text extracting methods. To reverse this behaviour, the user can call this method with an empty string. Without argument, returns the currently selecter terminator, if any.
Deletes the given bookmark (if defined).
Deletes a given column in a given table. Caution: Before using this method, the application should ensure that the whole area from the beginning of the table to the last cell of the column to be deleted is "normalized". See normalizeSheet() for details about table normalization.
Deletes a given row in a table.
Returns the internal identifier of a presentation page, and changes it if a second argument is provided. The page id is a positive integer. The first argument must comply to the same rules as with getDrawPage.
Returns the visible name of a presentation or drawing page. The first agument can be a page order number, a page element or the present page name (see getDrawPage). The page is renamed if a second argument is provided. Example: $doc->drawPageName("oldname", "newname");
See deleteColumn().
See deleteRow().
Returns the list of the bibliographic entry elements contained in the document. If an argument is provided, the returned list is restricted to the bibliographic entries matching it (this argument can be a regex). Example: my @biblio = $doc->getBibliographyElements("^W3C"); returns the bibliographic entries where the identifier begins with "W3C".
Returns the bookmark element (if defined) corresponding to the given bookmark name. If the bookmark covers a range of text (i.e. if it's not a position), the returned element is the "bookmark start" one.
Returns the element which represents the given cell. Possible arguments are respectively: the table number or its reference in the document, row number and column number. Each table cell contained in the body of an OOo/ODF document can be referenced in this manner, as if it belonged to a single 3D table irrespective of the rest of the document. If the cell is defined in the spreadsheet but covered (because of a cell merge), the return value is undef. The first argument can be either the sequential number of the table (starting at 0), the logical name of the table, or a 'table' object (which can be retrieved in advance using getTable). If it's a number or a name, getTable() is automatically called by getCell() in order to convert it in a 'table' object. However, if the first argument is a row object (previously obtained via getRow() or getHeaderRow()), the second one is processed as the column number. Before using several cells in the same row, it's a good idea to get the row object and then to use it in every cell selection, in order to minimize the coordinates calculation. In tables including one or more header rows, the best way to get a header cell is to use a header row (previously obtained using getHeaderRow()) as the first argument. If the first argument is a table, getCell() looks in the table body only. Alternatively, the user can provide the cell coordinates in a single alphanumeric argument, beginning with one or two letters and ending with one or more decimal digits, according to the same logic as in a spreadsheet. So, for example $doc->getCell($table, 'B12'); is equivalent to $doc->getCell($table, 11, 1); (Remember that, with the numeric coordinates, the row number is the first argument, while with the alphanumeric, spreadsheet-like ones, the column letter(s) come first.) Numbers can also be negative, where position -1 is the last. For example: $cell = $doc->getCell(-1, -1, -1); returns the very bottom right cell of the very last table in the document $doc. Returns a null value if the given cell does not exist or if it's covered by the span of another cell. Any cellXXX() method in this module uses the same cell addressing logic as getCell(). Note about spreadsheets: Addressing cells in spreadsheets is considerably more complex than in text document tables. However, the same addressing scheme in allowed in the "Calc" documents than in the "Writer" ones, provided the targeted cells belong to a preprocessed workspace (beginnning at the upper-left cell, and ending at a parametrizable position). It's possible to use normalizeSheet() or getTable() in order to make this workspace available. See normalizeSheet() for more explanations. Remember that the table addressing is zero-based and the row comes before the column in OpenOffice::OODoc, so, for example: $cell1 = $doc->getCell($table, 0, 0); $cell2 = $doc->getCell($table, 31, 25); returns respectively the A1 and Z32 cells. Note: in a spreadsheet, (0,0) are the coordinates of the "A1" cell, and, for example, (16, 25) are the coordinates of the "Z17" cell.
Returns the list of the paragraph elements contained in a given table cell (knowing that a single cell can contain one or more paragraphs).
Returns the value of a table cell (and not the cell element as with getCell), if the cell is defined and uncovered. The first form indicates a cell by its 3D coordinates, as with getCell). The second form (quicker) takes a cell element as its only argument (e.g. as returned by a previous getCell call). This method behaves in two different ways depending on the cell type: - returns the cell's text if the cell is set to literal (after any UTF8 decoding. See OODoc::XPath). This difference in handling is designed to allow programs to use returned numeric values directly in calculations. Note: To get information about a cell other than its value (numeric, etc.), the best way is first to get its element reference with getCell and then use it with getAttribute.
This method returns the list of the elements depending on a given header element. The argument and the options are the same as with getHeader(). Example: my @list = $doc->getChapter(2, level => 3); foreach my $element (@list) { my $text = $doc->getText($element); print "$text\n"; } The code above selects and prints all the text elements below the third level 3 header of the document (not including the content of the header itself.
Returns the element reference of the given column in the given table. The first argument is either the table's sequential number in the document, logical name or element reference. The second argument is the column's number in the table. Synonym: getTableColumn. Caution: The application should ensure that the area including the needed column is "normalized". See normalizeSheet() for details about table normalization.
For presentation and drawing documents. Returns the element reference of the given page name or postion. If the argument contains an integer, the page is according to its zero-based position. If the value is negative, the position is counted backwards from the end. If the argument is alphanumeric, it's regarded as a page name, and the page is selected accordingly. Caution: This method can't retrieve a page by name if the name contains numeric characters only; selectDrawPageByName() should be preferred to do so.
Returns the list of all the footnote citations (i.e. references to footnotes included in the text) contained in the document.
Returns the list of all the footnote elements contained in the document.
Returns the nth+1 header element. If n is negative, headers are counted backwards from the last. getHeader(-1) returns the last header element of the document. The only one possible option is "level". It allows the application to select the nth+1 header element for a given header level. Example: my $header = $doc->getHeader(2, level => 3); selects the third level 3 header in the whole document. See also getChapter(). Caution: without the "level" option, this method counts sequentially through all headers along a single plane, irrespective of their level. E.g. if you have a level 1 header then two level 2 headers then a level 1 header, the call getHeader(3) returns the last level 1 header.
Returns a list of header elements (i.e. elements called 'text:h' in the document body). If the "level" option is provided, the list is restricted to the headers having the given level.
See getTableHeaderRow().
Returns the text of the nth+1 header element. Elements are counted in the same way as for getHeader.
Returns a list of document header texts. An optional filter argument can be passed (literal or regular expression). In this case, only headers whose content matches the filter are returned. In a list context, the result is returned in the form of a list of character strings. In a scalar context, the result is a single string in which the headers are separated by a line-feed character ("\n"). Note: This list is "flat". It contains no information about the headers' hierarchy. To get a hierarchical contents list, you must start with the list of headers obtained using getHeaderList and check each element's level attribute ('text:level').
Returns a list of elements which represent items of an ordered or unordered list. The argument is a "list" element (obtained previously e.g. using getItemList, getOrderedList or getUnorderedList). Each element in this list can be used with item handling methods.
Returns the element which represents the nth+1 ordered list in a document if found. WARNING: In the OpenOffice.org 1 documents, only "ordered lists" and "unordered lists" can be present. In the Open Document format, there are generic list objects only, and each one is made "ordered" or "unordered" by its style. So, this method will never return anything from an OOo 1 document.
Returns the element which represents the nth+1 ordered list in a document if found. WARNING: Ordered lists are possible in the OpenOffice.org 1 format only. Don't use it against Open Documents.
Returns the nth+1 paragraph in the document body, or undef if the given number is greater than or equal to the total number of paragraphs in the document. You can also pass a negative argument, in which case paragraphs are counted backwards from the end (-1 being the last paragraph). By paragraphs we mean 'text:p' elements, which excludes headers but includes non-empty table cells, contents of list items and footnotes. Returned value is an element and not the text of the paragraph. All read/write operations involving attributes and content can use this element.
Returns a list of paragraph elements (i.e. 'text:p' elements in the document body).
Returns the text of the nth+1 paragraph, counted using the same rules as for getParagraph.
Returns a list of texts contained in the paragraphs of a document ('text:p' elements). A filter can be passed as an optional argument (literal or regular expression). In this case, only paragraph texts whose content match the filter are returned. In a list context, the result is returned in the form of a list of character strings. In a scalar context, the result is a single string in which the paragraphs are separated by a line-feed character ("\n").
Returns the element reference which corresponds to a row in a table. The first argument is either the table's sequential number in the document, logical name or element reference. The second argument is the row number in the table. Synonym: getTableRow. This methods ignores the table header (if any). It can retrieve a row in the table body only. See getTableHeaderRow().
Returns the list of the uncovered cell elements corresponding to a given table row. The row can be provided either by table ID and row number or by direct row object.
If the first argument is a number, returns the nth+1 section in a document (section numbers are zero-based; if the argument is negative, the sections are counted from the end). The second form allows you to select a section by its logical name (as it would appear to the end user when editing the section's properties). This name is obviously easier to use than a number. Moreover, this type of selection means the application will still work even if a section changes position within a document. The returned object is a "handle" that can be used for subsequent element creations or retrievals in the selected section.
Returns a list of elements which correspond to texts which "stand out" from the document i.e. which have been given a style which makes them stand out from the rest of the paragraph containing them. For example, a word in italics or in font size 12 in a paragraph of mostly standard characters in font size 10 is a 'span' element and would therefore appear in a list returned by getSpanList.
Gets a list of texts which "stand out" in the same way as getSpanList and returns it under the same conditions as getParagraphTextList or getHeaderTextList, with optional filter.
Obsolete. See textStyle.
If the first argument is a number, returns the nth+1 table in a document (table numbers are zero-based; if the argument is negative, the tables are counted from the end). The second form allows you to select a table by its logical name (as it would appear to the end user when editing the table's properties). This name is obviously easier to use than a number. Moreover, this type of selection means the application will still work even if a table changes position within a document. But the retrieval by name works with two restrictions: - if a table name is made of digits only, or if if represents a numeric expression, it's automatically regarded as a table number; - getTable() can't retrieve a table by name if the name contains one or more "$", "{" or "}" characters (these characters are allowed in the table names in OpenOffice.org Writer documents, but not allowed in OpenOffice.org spreadsheets). The returned object is a "handle" that can be used for subsequent accesses to its components (rows, cells). getTable() can be used to retrieve a sheet in a Calc document as well as a table in a Writer document. However, before using any of the row/column/cell manipulation available methods, a special preprocessing should be done if the target table is a spreadsheet. See normalizeSheet() for more information. A getTable() call with the optional length, width arguments produces the same effect as an explicit call of normalizeSheet() with the same arguments. In the text documents, the tables may be used without preprocessing and the paragraph above doesn't apply, as long as the application doesn't to get other objects than rows and cells. However, the table normalization is needed before any column-oriented operation (i.e. getColumn(), insertColumn() or deleteColumn()). The returned value is a table element and not a table's content.
See getColumn.
Returns the element reference which corresponds to a row in a table header, or undef if the given table has no header row. The arguments are processes in the same way as with getRow(), but the second argument is optional; it's required only if the table has more than one header row (the 1st header row is returned by default). The returned elements can be used with subsequent cell access methods in order to process header cells (see getCell()).
Returns a list of table elements in a document.
See getRow.
Returns the list of the rows contained in the given table. When the user needs to process every row in large tables, this method allows some performance improvements, because it's less costly than a lot of successive getRow() calls.
Returns the size of a table as a pair of values which represent the number of rows and columns. The table can be specified either by number, logical name or reference. Example: my ($rows, $columns) = $doc->getTableSize("Table1");
Returns the content of a table, if found, whose number or reference is given as an argument. If not found, returns undef. The content of each cell is extracted according to the rules of getCellValue. In a list context, the returned value is a 2D table with each element containing the corresponding cell in the document. In a scalar context, the content is returned as a single string in CSV format. In this case, the rows are separated by a delimiter set by the instance variable 'line_separator' and the fields by the variable 'field_separator' in the OODoc::Text object. (These delimiters are by default "\n" and ";" respectively.)
Exports the text contained in the given element according to the means appropriate to that type of element. If the 'use_delimiters' flag is set to 'on' (default), the content of each element (others than ordinary paragraphs, table cell, headers) is preceded and/or followed by a character string depending on the type of the element. This also depends on the settings given to the delimiter values 'begin' and 'end' by the 'delimiters' hash. In a default configuration where the application has not provided any specific delimiters, the following delimiters are used: - '<<' before and '>>' after sections of text highlighted within an element (e.g. words in bold or underlined within a paragraph of 'standard' font characters). footnote citations (in text body) are placed between square brackets. '{NOTE:' and '}' for the content of footnotes. (Footnotes are physically inserted into the text at the place where they are called, just after the link element indicating the footnote's number. Its display at the foot of the page or elsewhere is a trick of the graphical interface.) An application can change these delimiters, add more for other types of elements (e.g. paragraphs, headers, tables cells, etc.), or deactivate them using outputDelimitersOff. This depends on where the text is exported to e.g. display in editable "flat" format, conversion to non-OpenOffice.org XML or a markup language other than XML, generating code from text, etc.. A default export (ex: "\n") terminator can be set for any element that is not listed in the 'delimiters' hash (see defaultOutputTerminator() above). If the element is an ordered or unordered list, the text produced is a concatenation of all the lines in the list, each separated by a line-break in addition to any delimiters. The default line break character is "\n", but it can be set to any other string (including an empty string) through the 'line_separator' property of the document object. If the element is a string table cell, getText behaves like getCellValue. If the cell contains more than one paragraph, the text produced is a concatenation of all the paragraph contents, each separated in the same way as list items. If the element is a table, getText behaves like getTableText.
Returns the text of a document, as "flat" editable text. In a list context, the content is returned as a table with one text element (header or paragraph) per element. In a scalar context, the content is returned as a single character string with each text unit (header or paragraph) separated by a line-feed ("\n"). The returned text contains no style or level information, so there is nothing to distinguish a header from a paragraph. Same as selectTextContent('.*').
Returns the list of all the text elements, including headers, paragraphs and item lists.
Same as getParagraph but only considers top level paragraphs. The contents of lists, tables and footnotes are excluded.
Returns the element which represents the nth+1 unordered list in a document, if found. WARNING: Ordered lists are possible in the OpenOffice.org 1 format only. Don't use it against Open Documents.
Returns the element (if defined) representing a user-defined field, and corresponding to the given name. See also userFieldValue().
Returns the user-defined variable identified by the given name. [Contribution by Andrew Layton]
Get/set the URL of an hyperlink element. The first argument may be a previously retrieved hyperlink element (see selectHyperlinkElement below), or the URL of an existing hyperlink. If a second argument is provided, it replaces the URL of the hyperlink element. With only one argument, just returns the existing URL of the link, or undef if the first argument doesn't match an existing hyperlink element.
Returns the UTF8 conversion of the given text, supposed to be in the local character set of the document (see the 'local_encoding' property).
Inserts a new column in an existing table at a given position. The second argument must be the number of an existing column. Caution: this argument must be a column number, and not a column element. The new column is created as a copy of the column a the given position. It's inserted before or after the existing one, according to an optional "position" parameter (default 'before'). Caution: before using insertColumn() against a spreadsheet, the application should ensure that the whole rectangular area from the top left cell ("A1") to the last used cell of the column at the target position is "normalized" (see normalizeSheet() for details about the table normalization).
In a presentation or drawing document, inserts a new page before or after an existing page. Possible options are the same as for appendDrawPage(), with an additional one: position => 'before' or 'after' (default 'before') The new page is inserted before or after the reference page, according to the 'position' option. The first argument can be a draw page element reference (recommended) previously returned, for example, by a previous page retrieval or creation method call. Alternatively, it can be a page position or visible name, so it's regarded in the same way as in getDrawPage(). Returns the new page element, or undef in case of failure.
Same as appendHeader, but inserts the given header at the given position. Position is that of an existing element which can be another header or a paragraph. Can be given by [path, position] or by element reference. Possible options are the same as for appendHeader, with the additional option 'position' which determines if the header is inserted before or after the element at the given position. Possible values for this option are 'before' and 'after'. By default, the element is inserted before the given element.
Same as appendItemList, but a new list is inserted at the given position. The point of insertion can be given either by the pair [path, position] or by element reference. Options are the same as for insertParagraph.
Same as appendParagraph, but a new paragraph is inserted at the given position. Position is that of an existing element which can be another paragraph or a header. Can be given by [path, position] or by element reference. Options are the same as for appendParagraph, with the additional option 'position' which determines whether the paragraph is inserted before or after the element at the given position. Possible values for this options are 'before' and 'after'. By default, the element is inserted before the given element.
Inserts a new row into a table. In its first form, pass the table (reference, logical name or number) and the position number in the table. In its second form, pass the element reference of the existing row which is directly before or after the position where you want to make the insertion. By default, the new row is inserted at the position of the referenced row, which displaces it and the rest of the table down by one row position. However, you can insert it after by using the 'position => after' option. By default, the new row is an exact copy of the referenced row, but you can assign particular attributes to it in the same manner as the insertElement method of OODoc::XPath.
Creates a new section and inserts it immediately before or after an existing element (paragraph, header, table). The referenced element can be indicated as in insertParagraph. There is a "position" option which works in the same way as with insertParagraph() or insertRow(). For other options, see appendSection(). For example, insertSection() may be used in order to insert a subdocument in a master document.
Creates a new table and inserts it immediately before or after another element (paragraph, header, table). The referenced element can be indicated as in insertParagraph. The other arguments and options are the same as for appendTable with the additional option 'position' as in insertParagraph.
See insertColumn().
See insertRow().
As appendText, but a new text element is inserted at the given position. The position is that of an existing element (of any type). It can be given by [path, position] or by element reference. Options are the same as for appendText, with the additional option 'position' which determines whether the element is inserted before or after the element at the given position. Possible values for this option are 'before' and 'after'. By default, the element is inserted before the given element.
Installs a write protection on the given section. Il an second argument is provided, it's stored as an encrypted key which is associated to the write protection. Such a write protection works only when the document is edited through an OpenOffice.org-compatible desktop software. It doesn't prevent the programs using OpenOffice::OODoc from deleting or updating the protected sections.
To be used with spreadsheets. This method preprocesses a given sheet so its components (rows, cells) become available for all the table-oriented methods described in this chapter. normalizeSheet() is useless for tables which can be selected with getTable(); the getTable() method, when executed with the length and width optional arguments, executes the same job. This method is not always needed for tables included in OpenOffice.org Writer (sxw/odt) documents, because their storage is "normalized" (i.e. each component is mapped to an exclusive XML element), with the exception of the column objects. So, normalizeSheet() is required with these tables when the application needs to use a column-focused method such as getColumn(), insertColumn() or deleteColumn(). In Calc (sxc/ods) documents, the XML mapping of the whole content is "denormalized" in order to save memory: several table components can be mapped to a single XML element, so the XML address of each one can't be simply calculated from its logical coordinates (sheet, row, column). In order to allow the spreadsheets components to be addressed with the same methods as the Writer table components, normalizeSheet() reorganizes the XML mapping of the given sheet. Because this method is very time and memory consuming, it should never be used to reorganize the largest possible area of a sheet (meaning thousands of rows and hundreds of columns that will probably never be used). So it's action is limited to a given area, controlled by the rows, columns arguments. When these arguments are not provided, the method uses the 'max_rows' and 'max_cols' properties instead (see the Properties section for other explanations). The first argument can be either the logical name of the sheet (as it's shown in the bottom tab by OOo Calc), the sheet number, or a table object reference, previously returned by getTable(). The return value is the table object (or undef in case of failure). Example: $doc = ooDocument(file => 'report.sxc'); my $sheet = $doc->normalizeSheet('Sheet1', 7, 9); my $result = $doc->cellValue($sheet, 5, 6); In the sequence above, a top left area of 7 rows by 8 columns is pre-processed, so the cells from A1 to H6 of this sheet can be reached according to the same addressing scheme as in Writer tables. The last instruction gets the content of G6. Because a "normalized" sheet has the same XML structure as a Writer table, it's generally possible to directly copy it from a spreadsheet document to a text document. Example: $doc1 = ooDocument(file => "spreadsheet.ods"); $doc2 = ooDocument(file => "text.odt"); $sheet = $doc1->normalizeSheet("Sheet1", 6, 8); $doc2->appendBodyElement($sheet->copy); In this last example, a new table, that is a copy of the A1:H7 area of the "Sheet1" sheet of a Calc document, is attached at the end of a Writer document. The transformed sheets, of course, are readable by OOo Calc. They simply take some more disk space when the processed spreadsheet is saved. If the document is later read then written by OOo Calc, the storage is optimized again, so the effects of normalizeSheet() disappear. normalizeSheet() can be used safely against Writer document tables, with two possible results. If the table size is greater than the given size, the method is neutral. Otherwise, the length and/or the width is increased according to the given arguments. An explicit call to this method can be replaced by getTable() with the additional length and width parameters.
See normalizeSheet().
Turns delimiters on or off. Used to mark up text exported by certain methods like getText or selectTextContent. The delimiters actually used depends on the table loaded into the OODoc::Text instance via the 'delimiters' property.
Returns the conversion in local character set of the given text, supposed to be in UTF8. The local character set of the document is used (see the 'local_encoding' property).
See deleteBookmark().
Removes the header at the given position (first form). Example: $doc->removeHeader(4); removes the 5th header (whatever its level) counted from the beginning of the document. The header to be removed can be indicated by element reference (second form). In this case, the type of element is not checked and this method becomes the equivalent of removeElement.
Removes any hyperlink contained in the given element, leaving in place the previously hyperlinked text.
Removes the paragraph at the given position (first form). The paragraph to be removed can be indicated by element reference (second form). In this case, the type of element is not checked and this method becomes the equivalent of removeElement.
Removes the multi-column span of a table cell. The width of the cell is reduced to the width of its column. The uncovered cells take the same style and data type as the reduced cell.
"Flattens" a text element, removing all presentation distinctions which may mark out some substrings of its content. See also setSpan().
Renames an existing section using the second argument.
Renames an existing table using the second argument.
Reads or modifies a table row's style, in the same way as columnStyle does for columns.
Returns the encrypted key which is associated to the given section, if the section is write-protected by key. This method can't provide the real key (as it should be typed by the end-user to unlock the section), but the returned value may be reused in order to protect more than one section with the same password. See also unlockSection().
Without argument, returns the current style of a given section. If an argument is provided, it becomes the new style of the section.
In a presentation or drawing document, returns the page element identified by the given name, or undef if the name is unknown. The names to be used correspond to the displayed page names in OpenOffice.org Impress.
Returns the element containing the given bookmark.
Returns the first text element whose content matches the 'filter' (which can be an exact string or a regular expression), or undef if no matching content is found. With more than one argument, this method can be used for replacement operations, or user-defined function triggering, in the same conditions as selectElementsByContent.
This method returns a list of text elements such as paragraphs, headers or ordered/unordered lists whose content matches the search criteria contained in 'filter' (which can be an exact string or a regular expression). The first form simply returns the given list without modifying the text. The second form returns the same list, but replaces all strings which match the search criteria with the 'replacement' string as it goes. The third form, where the 'action' argument is a program function reference, launches the given function each time the filter string is matched. If defined, the value returned by the function is used as the replacement value. If the function returns a null value (undef) then no replacement is made. If it returns an empty string, the retrieved text is deleted. The called function receives the rest of the arguments, in this order: 1) all remaining arguments after 'action' ('other_arguments'), if any. 2) the element containing the retrieved text. 3) the string actually selected. If the filter is an exact string, it is equal to the filter. If the filter is a regular expression, it matches the "real" text retrieved. The returned text (if any) must be encoded in UTF8. The returned list is the same one returned by the first two forms. Example: sub action { my ($d, $element, $value) = @_; if ($value < 100) { $d->removeElement($element); return undef; } else { return $value * 2; } } @list = $doc->selectElementsByContent("[0-9]+", \&action, $doc); In the above code, the subroutine "action" is called each time an integer (one or more digits) is found. The subroutine receives the document reference itself as its first argument (an OODoc::Text object given by the application). Next, it automatically receives the reference of the element in which the search string was found (i.e. an integer) and, finally, it receives the exact number found as its second-last and last arguments respectively. If this number is less than 100, the element is removed. This is why the subroutine needed the $doc object, used to invoke the removeElement method. If more than 100, the number is multiplied by two and the result replaces the original value in the element. The list returned by selectElementsByContent contains all elements which contain the search string, including any which might have been removed by the called function while it was running. It is the "main" elements containing strings which matched the filter which are returned and not any of their sub-elements. For example, if the returned string is found in one of the items in an unordered list, the list element is selected and not the item. Similarly, the table is selected when one of its cells matches the filter, and the paragraph which is selected when the search string is found in an attached footnote. However, a character string cannot be considered to match the filter unless it is entirely within the same sub-element and all its characters have the same style. For example, if you were searching for the string "OpenOffice" using selectElementsByContent, the string, if present, can't be found if, say, "Open" and "Office" are not represented with the same font, the same color and/or the same font size. Note: This method can be used with a "non-filtering" regular expression (".*") for unconditional movement through all text elements.
Retrieves the first hyperlink element (if any) whose the URL matches the argument. Example: my $e = $doc->selectHyperlinkElement("cpan"); could return an hyperlink element containing "www.cpan.org" as well as "search.cpan.org", etc. The URL filter is processed as a regex. Note: In order to get the text container (ex: paragraph) where the hyperlink is located, the application can use the parent() element method. Example: my $e = $doc->selectHyperlinkElement("www.cpan.org"); my $p = $e->parent if $e;
Returns the list of the hyperlink elements whose the URL matches the argument (and not only the first one).
Returns the first paragraph (if any) using the given style.
Returns the list of the paragraphs using the given style.
Returns a list of header texts and/or paragraphs (in the document's own order) which match the given search criteria. The filter can be an exact string or a regular expression. A filter set to ".*" (no selection) will result in an export of the entire text. In all three forms, this method behaves like selectElementsByContent, except that it returns text instead of a list of elements. Depending on the context (list or scalar), the result is returned in the form of a list of rows or in the form of a single character string where the elements are separated by a line-feed ("\n"). Note: called with a "non-filtering" regular expression, this method will result in a "flat" export of the document: print $doc->selectTextContent('.*');
Puts an hyperlink on a text area in a given text element. Example: $doc->setHyperlink($para, "CPAN", "http://www.cpan.org"); This method works in the same was as setSpan(), described below, but the text span is hyperlinked, and not presented according a particular style. So, the last argument must be an URL instead of a style.
Applies a "span" to part of the content of a text element. In OpenOffice.org XML language, a "span" is a substring whose presentation style differs from the style of the text element to which it belongs. For example, a given "span" could be in italics while the rest of the paragraph is in normal characters. Caution: the same word has a different meaning when it's used about table cells (see cellSpan()). A "span" is therefore a way to use several styles within the same element, bearing in mind that the paragraph's global style can be modified by setStyle. The properties of a text span can be related to any kind of character string presentation, such as font, font size, font weight, font style, and colors (background and foreground). The desired text element is normally indicated by [path, position] or reference. The optional argument 'context' which consists of an element reference, allows you (when using [path, position]) to limit a search to child elements of a particular element (e.g. headers, footers, unordered lists, etc.). 'expression' is the character string to be highlighted, and 'style' is obviously the style describing the presentation characteristics to give to it. See OODoc::Styles for how to construct styles from code. As a highlighted string can be quite long or not all known in advance, you can represent it with a regular expression. Taking the following paragraph as an example: "OpenOffice.org is my favourite word processor" my @list = $doc->selectElementsByContent("OpenOffice"); foreach my $para (@list) { $doc->setSpan($para, "Open.*Writer", "Style1"); $doc->setSpan($para, "word.*ssor", "Style2"); } This sequence selects all text elements (or, more simply, paragraphs) which contain "OpenOffice". In each of them, the style "Style1" is given to the string beginning with "Open" and ending with "Writer" (if found) and the style "Style2" is given to the string beginning with "word" and ending with "ssor". Defined elsewhere, Style1 and Style2 would correspond to the required presentation characteristics. "Style1" and "Style2" must be defined as text styles (not paragraph styles); these styles can be present in the source document or created (before or later) by the program (see createStyle() in OpenOffice::OODoc::Styles). It's possible, in a single setSpan() call, to give the same style to more than one text area in a text container. To do so, you just need to provide several text strings, separated by pipes ("|"), as the search expression. Example: $doc->setSpan($para, "OpenOffice|Writer", "MyStyle"); Caution: the current version of this method can neither recognise nor handle a string located partly in a "span" and partly outside it. It can, however, create a "span" inside another. See also removeSpan.
Alters the setText method of OODoc::XPath, so that it can handle complex text elements. If the element is a paragraph, a header of a list item (ordered or unordered), its content is replaced by the 'text' argument. Caution: setText deletes and replaces the previous content of the paragraph. If the element is a table cell, this method is the same as updateCell. If the element is a list (ordered or unordered), the content of each 'text' argument (however many) forces the creation of a new item which is appended to the list (existing items remain unchanged). Example: $doc->setText($element, "Peter", "Paul", "John") adds three items to the list if $element is a list. If $element is, for example, a paragraph, then the second argument ("Peter") becomes the content of the paragraph and the other arguments are ignored. For all other types of element, setText behaves normally as defined in OODoc::XPath. Note: setText(), as any other text input method, can't properly process repeated spaces. So, a sequence of spaces, whatever its length, is replaced by a single space. See setText() and extendText() in OpenOffice::OODoc::XPath.
Returns the current name of a given table, or replaces it with a new name given as the second argument. The table can be indicated by number, logical name or reference. Returns undef unless the given table is defined. If the new name is the name of an existing table, the table is not renamed and an error message is produced.
Returns the current style of a given table, or replaces it with a new style given as the second argument. The table can be indicated by number, logical name or reference.
Reads a text element's style or, if a 'style' argument is given, changes it. The element can be indicated by the pair [path, position] or by reference. Note: the returned value is a literal style identifier or the value of the element's 'text:style-name' attribute. Note: this method allows you to attribute a non-existent style to a paragraph or header. Such a style can be created later (e.g. using createStyle) or not at all. The actual existence of the style is only relevant to the needs of the application. Obviously, opening a document which contains references to non-existent styles in OpenOffice.org will give unpredictable results as to the viewing of the given paragraphs or headers.
Removes the write protection (if any) of the given section. If the section was key-protected, the key is removed and provides the return value of the method. Example: my $key = $doc->unlockSection("Section1"); $doc->lockSection("Section2", $key); The two lines above remove the protection of "Section1" and protect "Section2" with the password which previously protected "Section1".
Modifies the content of a table cell. In its first form, indicates a cell by its 3D coordinates, as with getCell(). In its second form, indicates a cell by its element reference. If the cell is set to literal, its content is limited to its text. In this case, the optional argument "text" is of no use (the text equals the value). If the cell is set to numeric (float, currency, date, etc.), you should generally pass a literal argument as well as the value. This method can be replaced by the accessor cellValue which allows reads and writes.
Reads the stored value of a given user field or changes it if a value is provided. The 1st argument can be either the name of the field (as it appears for the end-user) or a previously loaded user field element. See also getUserFieldElement(). This method doesn't create any new user field. It can only read or update an existing one. If the given user field is numeric (ex: date, currency) the returned and/or provided value is the internally stored value, and not the displayed one. The user field is displayed according to a data style by OpenOffice.org. For example, 'Tuesday, March 1, 2005' is a possible displayed value for 38412.
Returns the current value of the given user-defined variable or, if a new value is provided as the second argument, updates the variable accordingly. [Contribution by Andrew Layton]
While all the methods above belong to the document object, some additional methods are defined for individual text containers. These methods belong to the OpenOffice::OODoc::Element class.
A set of "isXXX" methods, returning true or false, allow the to check the type of a given element. Caution, this methods belong to the elements, not to the document. Example: print "This is a list" if $element->isItemList; Here is the list of element type indicators: isBibliographyMark bibliography mark (in the doc. body) isCovered covered (invisible) table cell isDrawPage presentation or drawing page isFootnoteBody footnote body isFootnoteCitation footnote citation isHeader header isItemList list (ordered or unordered) isListItem list item isOrderedList ordered list (OOo 1.x only) isParagraph paragraph isSection section isSequenceDeclarations set of sequence declarations isSpan span element (see setSpan) isTable table isTableCell table cell isTableRow table row isUnorderedList unordered list (OOo 1.x only)
For a neater and more direct access to element types, see the getName method of XML::Twig::Elt. A call to $element->getName returns the element's XML name including its namespace prefix e.g. 'text:p' for a paragraph or 'table:table-row' for a table row. Remember that all the features of XML::Twig::Elt are available for any text container.
No class variables are exported. Instance properties are the same as for OODoc::XPath, plus: 'delimiters' => delimiter table hash giving the relation between element types and the delimiters to use when exporting text (see getText). 'use_delimiters' => delimiter usage (see getText) indicates whether delimiters are to be used by getText or not when exporting text. Set to 'on' by default. Can be set to 'off' or another value to stop or limit use of delimiters. 'header_style' => default header style indicates the default header style to be used by element creation methods when no style is specified. Set to 'Heading 1' by default. 'paragraph_style' => default paragraph style indicates the default paragraph style to be used by element creation methods when no style is specified. Set to 'Standard' by default. 'field_separator' => field separator contains the character string to be used as the field separator when exporting tables. By default it is ";". 'line_separator' => line separator contains the string to be used to separate lines when exporting "flat" text. By default, it is a line-feed ("\n"). 'max_rows' => max table length (default 32) 'max_cols' => max table width (default 26) these 2 properties control the size of the "managed area" in a spreadsheet; the default "managed area" is the A1:Z31 rectangle, corresponding to the (0,0)-(31,25) coordinates; see getTable() and getCell() and normalizeSheet() for more explanations. 'expand_tables' => table transformation usage indicates whether the XML representation of the spreadsheets are to be expanded in order to allow the same cell/row addressing scheme as with the tables belonging to text documents; by default, this property is not set. If this property is set to 'on', the first access to any sheet will automatically trigger this transformation, so the explicit normalizeSheet() method will not be needed. However, this automatic (but costly) transformation has a drawback: it uses the same 'max_rows' and 'max_cols' values for every targeted sheet, whatever the really needed managed area for each one.
Copyright 2004-2005 by Genicorp, S.A. (http://www.genicorp.com)
Initial developer: Jean-Marie Gouarne (http://jean.marie.gouarne.online.fr)
Initial English version of the reference manual by Graeme A. Hunter (graeme.hunter@zen.co.uk)
License:
- Genicorp General Public Licence v1.0 - GNU Lesser General Public License v2.1
Contact: jmgdoc@cpan.org
To install OpenOffice::OODoc, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenOffice::OODoc
CPAN shell
perl -MCPAN -e shell install OpenOffice::OODoc
For more information on module installation, please visit the detailed CPAN module installation guide.