File: ooolib-perl-0.1.8-doc.html

package info (click to toggle)
ooolib-perl 0.1.9-1.1
  • links: PTS
  • area: main
  • in suites: buster, stretch
  • size: 256 kB
  • ctags: 59
  • sloc: perl: 1,657; makefile: 90; sh: 78
file content (404 lines) | stat: -rw-r--r-- 18,977 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
<html>
<head>
<title>OpenOffice.org Perl Module (ooolib-perl)</title>
</head>
<body bgcolor=ffffff>

<center>
<h1>OpenOffice.org Perl Library (ooolib-perl)<h1>
<h2>Version 0.1.8</h2>
<h2>Documentation</h2>
</center>

<hr>
<a name=table><h1>Table of Contents</h1>
<ol>
<li><a href=#table>Table of Contents</a>

<li><a href=#info>Information</a>
<ul>
<li><a href=#info-contact>Contact Information</a>
<li><a href=#info-license>ooolib-perl License</a>
</ul>

<li><a href=#setup>Setup and Installation</a>
<ul>
<li><a href=#setup-require>Requirements</a>
<li><a href=#setup-contents>Contents</a>
<li><a href=#setup-examples>Example Programs</a>
</ul>

<li><a href=#api>Application Programming Interface (API)</a>
<ul>
<li><a href=#api-basic>Basic Outline</a>
<li><a href=#api-set>oooSet - Property Setting</a>
<li><a href=#api-data>oooData - Documents Data</a>
<li><a href=#api-special>oooSpecial - Special Data</a>
<li><a href=#api-generate>oooGenerate - Document Creation</a>
<li><a href=#api-error>oooError - Error reporting</a>
</ul>

<li><a href=#internal>Library Internals</a>
<ul>
<li><a href=#internal-variable>Internal Variables</a>
<li><a href=#internal-cleantext>oooCleanText</a>
<li><a href=#internal-meta>oooWriteMeta</a>
<li><a href=#internal-contents>oooWriteContests</a>
<li><a href=#internal-styles>oooWriteStyles</a>
<li><a href=#internal-mimetype>oooWriteMimetype</a>
<li><a href=#internal-settings>oooWriteSettings</a>
<li><a href=#internal-manifest>oooWriteManifest</a>
<li><a href=#internal-timestamp>oooTimeStamp</a>
<li><a href=#internal-datetime>oooDateTime</a>
<li><a href=#internal-cellupdate>oooCellUpdate</a>
<li><a href=#internal-cellcheck>oooCellCheck</a>
<li><a href=#internal-stylename>oooStyleName</a>
</ul>

</ol>

<hr>
<a name=info><h1>Information</h1>
Information about the ooolib-perl project.  I am interested in seeing how the ooolib is being used.  If you are using ooolib in a program or on your website, please email me and let me know.<p>

<a name=info-contact><h3>Contact Information</h3>
You can contact me, Joseph Colton, at either of these addresses.  For e-mail:<br>
josephcolton@gmail.com<p>

For mailing or visiting:<br>
55-579 Naniloa Loop<br>
Laie, Hawaii 96762<p>

<a name=info-license><h3>ooolib-perl License</h3>
ooolib-perl - This Perl Library is built to create OpenOffice.org documents.<br>
Copyright (C) 2003-2006  Joseph Colton<p>

This library is free software; you can redistribute it and/or<br>
modify it under the terms of the GNU Lesser General Public<br>
License as published by the Free Software Foundation; either<br>
version 2.1 of the License, or (at your option) any later version.<p>

This library is distributed in the hope that it will be useful,<br>
but WITHOUT ANY WARRANTY; without even the implied warranty of<br>
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU<br>
Lesser General Public License for more details.<p>

You should have received a copy of the GNU Lesser General Public<br>
License along with this library; if not, write to the Free Software<br>
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA<br>

<p>

<hr>

<a name=setup><h1>Setup and Installation</h1>
The setup and installation for ooolib-perl is really quite easy.  Because the library is written in Perl, there is no compiling.  You only need to have the requirements and use the require statement in your program.<p>

<a name=setup-require><h3>Requirements</h3>
In order to use ooolib-perl you will need to have a machine running GNU/Linux and have either the Archive::Zip module or the zip command installed. To view the resulting documents you will need to have OpenOffice.org 1.1 Beta or later.<p>

<a name=setup-contents><h3>Contents</h3>
Below are the files and directories included with the source for ooolib:<p>

<pre>
ChangeLog	This file contains information about changes to ooolib-perl
		in each version.
doc/		This is the documentation directory.
examples/	This directory contains example programs.
ooolib.pm	This is the ooolib-perl module.
README		The readme file.
TODO		This file contains information about tasks that are not yet
		completed.
mime.types	This file contains mime type information you can use with Apache, etc.
</pre>

<a name=setup-examples><h3>Example Programs</h3>
There are currently very few example programs.  The number and use of the example programs are subject to change as the feature set of ooolib grows.<p>

<hr>

<a name=api><h1>Application Programming Interface (API)</h1>
The Application Programming Interface or API is just the collection of functions you use to create programs that use ooolib.<p>

<a name=api-basic><h3>Basic Outline</h3>
Perl scripts using ooolib need a few basic things.  You need to use the module and you need to create the document by specifying what type of document you are creating.  Finally you need to create the document with the generate command.  This is about the shortest a script can be:

#!/usr/bin/perl

use ooolib;

$doc = new ooolib("sxw");
$doc->oooSet("builddir", ".");
$doc->oooSet("author", "The Author");
$filename = $doc->oooGenerate("basic.sxw");

<p>

For you can save and use this code if you like: <a href=base_code>base_code</a>


<a name=api-set><h3>oooSet - Setting Properties</h3>
Sets variables used in creating and processing documents.<br>
<b>Synopsis</b>:<br>
&oooSet(NAME, &lt;DATA&gt;);<br>
<b>Description</b>:<br>
oooSet can only be called after oooInit.  This function sets options such as the author, subject, bold, italics, etc.  The first argument, NAME, refers to what is to be set.  Each NAME argument has different <DATA> options that are needed.  Here are the current names with the <DATA> that they require:<br>
<ul>
<li>"title" - Takes a single string value that is used as the title of the document.
<li>"author" - Takes a single string value that is used as the name of the author for the document.
<li>"subject" - Takes a single string value that is used as the subject of the document.
<li>"comments" - Takes a single string value that is used as the comments for the document.
<li>"builddir" - Takes a single string that is supposed to contain the path for the creation of the document.
<li>"keyword" - Takes a single string containing a single word that is to be added to the keywords for the document.  This may be used multiple times to add multiple keywords to the document.
<li>"meta[1-4]-name" - Takes a single string containing the title of a user defined variable.
<li>"meta[1-4]-value" - Takes a single string containing the value of a user defined variable.
<li>"cell-loc" - Takes x and y coordinates in a spreadsheet.  The next oooData call will print to the resulting cell.
<li>"column-width" - Takes x as the column number and a width in centimeters.  (Sorry for those of you who use inches.  I guess I have spent too much time in foreign countries. 1 inch = 2.54 cm.)
<li>"cell-left" - Moves the writing cell one to the left.
<li>"cell-right" - Moves the writing cell one to the right.
<li>"cell-up" - Moves the writing cell up one.
<li>"cell-down" - Moves the writing cell down one.
<li>"cell-auto" - Takes x and y values.  After each oooData call the writing cell is incremented by these x and y values.
<li>"justify" - Takes a single argument of "right", "left", "center", or "block".  The next text will then be justified accordingly.
<li>"bold" - Takes a single argument of either "on" or "off".
<li>"italic" - Takes a single argument of either "on" or "off".
<li>"underline" - Takes a single argument of either "on" or "off".
<li>"text-color" - Takes a single argument of six hex digits in the form RRGGBB where RR is the red, GG is the green, and BB is the blue for the color of the text.  You may also select the following options "red", "green", "blue", "black", "white", and "default".
<li>"text-bgcolor" - Takes the same argument at "text-color" except it is instead applied to the background or highlighting of the text.
<li>"text-size" - Takes a single argument that must be a number for the size of the font.  The following text will be written in this size.  The exception is the headings.
<li>"text-font" - Takes a single argument for the font.  The following are valid fonts:
<ul>
<li>"Arial"
<li>"Bitstream Vera Sans"
<li>"Bitstream Vera Serif"
<li>"Bookman"
<li>"Courier"
<li>"Courier 10 Pitch"
<li>"Helvetica"
<li>"Lucidabright"
<li>"Lucidasans"
<li>"Lucida Sans Unicode"
<li>"Lucidatypewriter"
<li>"Luxi Mono"
<li>"Luxi Sans"
<li>"Luxi Serif"
<li>"Symbol"
<li>"Tahoma"
<li>"Times"
<li>"Times New Roman"
<li>"Utopia"
<li>"Zapf Chancery"
<li>"Zapf Dingbats"
</ul>
</ul>
<b>Return Value</b>:<br>
On successful completion oooSet returns the string "ok".  If there is a problem, oooSet will return the string "error" and an error message will be available by calling oooError.<br>

<a name=api-data><h3>oooData - Documents Data</h3>
Takes data and formats it for use in the document.<br>
<b>Synopsis</b>:<br>
&oooData(STYLE, TEXT);<br>
<b>Description</b>:<br>
oooData can only be called after oooInit has been called.  It takes a string STYLE and a string of TEXT then uses this information to create the data in the content.xml file.  The TEXT is run through the character filter oooCleanText, then the STYLE is looked up.<br>
In some cases, the style needs to have features such as bold, italics, right, center, or block justification added.  This is also handled by this function call.<br>
This is a list of the different styles currently available:<br>
<ul>
<li>"h" - Heading takes a single additional argument for the heading text.
<li>"h[1-9]" - Headings 1-9 take a single additional argument for the heading text.
<li>"default" - Default or Standard text take an additional argument for the text.
<li>"textbody" - Text body takes a string argument for the text.
<li>"cell-float" - Takes a single number for a cell.
<li>"cell-text" - Takes a single string for a cell's text.
<li>"cell-formula" - Takes a single string for a cell's formula.
<li>"cell-skip" - Just runs the cell-auto increment without writing anything to the cell.
</ul>
<b>Return Value</b>:<br>
Return the string "ok" on successful completion and the string "error" if there is a problem.<br>


<a name=api-special><h3>oooSpecial - Special Data</h3>
This function creates special types of data for documents.<br>
<b>Synopsis</b>:<br>
&oooSpecial(STYLE, &lt;ARGS&gt;);<br>
<b>Description</b>:<br>
oooSpecial takes a single argument for a style and then optional additional arguments required to carry out the style.  Below are the current styles:<br>
<ul>
<li>"pagebreak" - This creates a page break and does not require any additional arguments.
<li>"list-ordered" - This creates an ordered list.  The first call passes in an argument "new" and some text string.  This becomes the first list item.  The return value of the first call is the list ID number.  For future calls on the same list just pass in the list ID instead of "new".
</ul>
<b>Return Value</b>:<br>
Return values vary, but if you get "ok" then everything worked.  If you get "error" then there is a problem.  All other return values also indicate things worked out correctly.  For other return values see the description of the different styles.<br>


<a name=api-generate><h3>oooGenerate - Document Creation</h3>
Creates the end document file.<br>
<b>Synopsis</b>:<br>
&oooGenerate;<br>
&oooGenerate(FILENAME);<br>
<b>Description</b>:<br>
The oooGenerate function is either left empty or is passed a single string argument, FILENAME, that is used to determine the filename for the document being created.<br>
In the event that a FILENAME is picked, oooGenerate will make sure the filename ends with the correct file extension.  If it is not present, oooGenerate will append the correction extension and create the file.<br>
If no FILENAME is supplied, oooGenerate will create a a name consisting of the date and the pid number of the processes running ooolib, and the correction file extension.<br>
<b>Return Value</b>:<br>
Once oooGenerate has successfully completed, it will return a string containing the complete path of the newly created document.  If there is an error, oooGenerate will return the string "error" and an error message will be available by calling oooError.<br>


<a name=api-error><h3>oooError - Error reporting</h3>
Gives error messages to help in debugging code.<br>
<b>Synopsis</b>:<br>
&oooError;<br>
<b>Description</b>:<br>
oooError returns a string containing the last error message.  If two errors are reported to oooError, it will only return the last error.<br>
<b>Return Value</b>:<br>
A string containing the last error message.<br>


<hr>

<a name=internal><h1>Library Internals</h1>
If you are interested in working on the inside of the library you will probably want to know a little bit about how it is setup.

<a name=internal-variable><h3>Internal Variables</h3>

<ul>
<li>$version - This variable holds the version number of the library.
<li>%options - This variable holds lots of information set with the oooSet function.
<li>@keywords - This variable holds a list of the keywords.
<li>@fontdecls - This variable holds information about used fonts.
<li>%cellhash - This variable holds all of the spreadsheet data before writing the document.
<li>@documenttext - This variable holds all of the main text for the content.xml file.
<li>@autostyles - This variable holds any new styles created by making new combinations of bold, italics, justification, etc.
<li>@autolists - This variable holds all of the information needed to create lists.  It is really an extension to the @autostyles variable and comes directly after it in the content.xml file.
<li>$MINX - The minimum allowed x value in the spreadsheet.
<li>$MINY - The minimum allowed y value in the spreadsheet.
<li>$MAXX - The maximum allowed x value in the spreadsheet.
<li>$MAXY - The maximum allowed y value in the spreadsheet.
</ul>

<a name=internal-cleantext><h3>oooCleanText</h3>
This function prepares a text string to be included in the XML for OpenOffice.org documents.<br>
<b>Synopsis</b>:<br>
&oooCleanText(TEXT);<br>
<b>Description</b>:<br>
oooCleanText takes a string, TEXT, and replaces special characters that conflict with the text of the XML for the OpenOffice.org documents.  This is the order of the substitutions:<br>
"&amp;" becomes "&amp;amp;"<br>
"&apos;" becomes "&amp;apos;"<br>
"&lt;" becomes "&amp;lt;"<br>
"&gt;" becomes "&amp;gt;"<br>
<b>Return Value</b>:<br>
Once the text has been modified, the resulting text is returned.<br>


<a name=internal-meta><h3>oooWriteMeta</h3>
Writes the meta.xml file that is included in the document.<br>
<b>Synopsis</b>:<br>
&oooWriteMeta(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteMeta takes two string BUILDDIR and TYPE as input and uses the information previously entered using commands like oooSet to build the meta.xml file.<br>
<b>Return Value</b>:<br>
Return "ok" on success and "error" if an error occurs.<br>


<a name=internal-contents><h3>oooWriteContests</h3>
Writes the content.xml file.<br>
<b>Synopsis</b>:<br>
&oooWriteContents(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteContents takes two strings BUILDDIR and TYPE as input and uses the information previously entered using commands like oooSet and oooData to build the content.xml file.<br>
<b>Return Value</b>:<br>
Returns "ok" on success and "error" if an error occurs.<br>


<a name=internal-styles><h3>oooWriteStyles</h3>
Writes the styles.xml file.<br>
<b>Synopsis</b>:<br>
&oooWriteStyles(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteStyles takes two strings BUILDDIR and TYPE as input and uses the type of document to build a styles.xml file.<br>
<b>Return Value</b>:<br>
Returns "ok" on success and "error" if an error occurs.<br>


<a name=internal-mimetype><h3>oooWriteMimetype</h3>
Writes the mimetype file.<br>
<b>Synopsis</b>:<br>
&oooWriteMimetype(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteMimetype takes two strings BUILDDIR and TYPE as input and uses the type of document to build a mimetype file.<br>
<b>Return Value</b>:<br>
Returns "ok" on success and "error" if an error occurs.<br>


<a name=internal-settings><h3>oooWriteSettings</h3>
Writes the settings.xml file.<br>
<b>Synopsis</b>:<br>
&oooWriteSettings(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteSettings takes two strings BUILDDIR and TYPE as input and uses the type of document to build a settings.xml file.<br>
<b>Return Value</b>:<br>
Returns "ok" on success and "error" if an error occurs.<br>


<a name=internal-manifest><h3>oooWriteManifest</h3>
Writes the manifest file.<br>
<b>Synopsis</b>:<br>
&oooWriteManifest(BUILDDIR, TYPE);<br>
<b>Description</b>:<br>
The function oooWriteManifest takes two strings BUILDDIR and TYPE as input and builds the manifest.xml file.<br>
<b>Return Value</b>:<br>
Returns "ok" on success and "error" if an error occurs.<br>


<a name=internal-timestamp><h3>oooTimeStamp</h3>
Returns a time stamp.<br>
<b>Synopsis</b>:<br>
&oooTimeStamp;<br>
<b>Description</b>:<br>
The oooTimeStamp function calculates the date and returns a string indicating the date.<br>
<b>Return Value</b>:<br>
A string in the form YYYY-MM-DDTHH:MM:SS.<br>


<a name=internal-datetime><h3>oooDateTime</h3>
Returns the date and time: yyyy, mm, dd, hh, mm, ss<br>
<b>Synopsis</b>:<br>
&oooDateTime;<br>
<b>Description</b>:<br>
Gets the date and time information, then returns the results.<br>
<b>Return Value</b>:<br>
Returns an array (year, month, day, hour, minute, second)<br>


<a name=internal-cellupdate><h3>oooCellUpdate</h3>
Updates max values and current values for x and y<br>
<b>Synopsis</b>:<br>
&oooCellUpdate;<br>
<b>Description</b>:<br>
The function oooCellUpdate is called after data is entered in a cell.  It updates the cell location if the cell-auto x and y have been set.  Next it calls oooCellCheck to make sure the resulting x and y values are still valid.<br>
<b>Return Value</b>:<br>
None<br>


<a name=internal-cellcheck><h3>oooCellCheck</h3>
Tests to make sure the x and y values are legal<br>
<b>Synopsis</b>:<br>
&oooCellCheck;<br>
<b>Description</b>:<br>
Checks and makes sure the x ($cellhash{x}) and y ($cellhash{y}) values are between the maximum ($MAXX, $MAXY) and minimum ($MINX, $MINY) allowed values.  If they are too high or too low they are set to the max or min value.<br>
<b>Return Value</b>:<br>
None<br>


<a name=internal-stylename><h3>oooStyleName</h3>
Returns the name of the style to use<br>
<b>Synopsis</b>:<br>
&oooStyleName(STYLE);<br>
<b>Description</b>:<br>
The oooStyleName function keeps track of which combinations of bold, italics, underline, right, left, center, and block justification have auto style aliases.  If there is one it is returned, if not it is created and returned.<br>
<b>Return Value</b>:<br>
Returns a string that contains the style that should be used for the text.<br>

</body>
</html>