9. Text Processing - TextFun, TextTee, PlainText, HTMLText, LaTeXText

CEETRON SAM supports a set of text formatting functions to deal with text processing, including images, in a general way. The text formatting functions are designed to form an abstract interface for directing text and images to any number of formatted documents. Currently the text formatting interfaces HTMLText to HTML, LaTeXText to LaTex and PlainText to plain text documents are provided. The module TextTee allows a single text formatting stream to be directed to any number of text formatting interfaces simultaneously.

9.1. Text Functions - TextFun

The text function module, TextFun maintains function pointers to text functions which form a high level text formatting interface. Each of the associated modules such as TextTee, HTMLText, etc., are designed to implement a specific variety of text processing functions and to load the corresponding function pointers into a TextFun object. Rather than accessing the functions of a particular object such as HTMLText directly, the user accesses the functions through a TextFun object. In this way text processing independence is achieved. The TextFun module contains the following functions.

The text formatting interface is patterned after the concepts of HTML formatted documents. Depending upon the underlying text formatting interface, some text functions may be more or less successfully implemented. For example, back ground color is ignored if a plain text document is formatted using the PlainText module. The abstract text formatting interface contains the following functions.

9.2. File Operations

The text processing is normally directed to a file, or more generally, a file descriptor. The text functions support opening and closing files as well as connecting and disconnecting to previously existing file descriptors.

Before text formatting can occur to a file, a formatting object and associated text function object must be instanced and a file opened. The following illustrates instancing HTMLText and TextFun objects and setting HTML formatting functions.

vsy_HTMLText *htmltext;
vsy_TextFun *tf;
                /* create text function */
tf = vsy_TextFunBegin();
                /* create HTML formatting object */
htmltext = vsy_HTMLTextBegin();
                /* load text functions for HTML formatting */
vsy_HTMLTextTextFun (htmltext,tf);
                /* open file */
vsy_TextFunOpenFile (tf,"example.htm");

At this point a file is open and ready to receive text. To close a file and terminate text formatting reverse the process described above. The following code fragment illustrates this process:

                /* close file */
vsy_TextFunCloseFile (tf);
                /* delete objects */
vsy_HTMLTextEnd (htmltext);
vsy_TextFunEnd (tf);

9.3. Text Attributes and Modes

Text attributes are designed to modify the appearance of text primitives and forms. Examples of a text attribute are the width of a horizontal rule primitive or the background color of a page. Forms and form actions are modified by attributes such as the list type for list forms, heading level for heading forms and column alignment for table forms. Note that all colors are specified as floating point red, green, blue components in the interval [0.,1.]. All color components are silently clamped to this interval.

Text modes are attributes which may be enabled and disabled. If a mode is enabled then all subsequent text primitives are affected by the mode until the mode is disabled. An example of a text mode is enabling and disabling an italics font for text string primitives. Not every primitive is affected by a given mode. For example, image files are not affected by the italics mode.

9.4. Text Primitives

Text primitives include character strings and character space, image files and horizontal rules.

9.5. Forms and Form Actions

The concept of a form is used to refer to the format in which text primitives are meant to be arranged. Forms include free format, lists and list items, tables and table rows and columns, headings, and titles. The default form is free format. All other forms must be initiated by calling vsy_TextFunFormInit() and terminated by calling vsy_TextFunFormTerm(). Forms must be nested for certain forms such as lists and tables. Form actions include paragraph and line breaks.

9.5.1. Function Descriptions

The currently available TextFun object functions are described in detail in this section.

vsy_TextFun *vsy_TextFunBegin(void)

create an instance of a TextFun object

Create an instance of a TextFun object. Memory is allocated for the object private data and the pointer to the data is returned. By default all function pointers are NULL.

Destroy an instance of a TextFun object using 

void vsy_TextFunEnd (vsy_TextFun *textfun)

Return the current value of a TextFun object error flag using 

Vint vsy_TextFunError (vsy_TextFun *textfun)

Make a copy of a TextFun object. The private data from the fromtextfun object is copied to the textfun object. Any previous private data in textfun is lost. 

void vsy_TextFunCopy (vsy_TextFun *textfun,vsy_TextFun *fromtextfun)

Returns:

The function returns a pointer to the newly created TextFun object. If the object creation fails, NULL is returned.

void vsy_TextFunEnd(vsy_TextFun *p)

destroy an instance of a TextFun object

See vsy_TextFunBegin()

Vint vsy_TextFunError(vsy_TextFun *p)

return the current value of a TextFun object error flag

See vsy_TextFunBegin()

void vsy_TextFunSet(vsy_TextFun *p, Vint type, Vfunc *function)

set pointer to text function

Set pointers to text functions.

Errors

SYS_ERROR_ENUM is generated if an improper type is input.

Parameters:

  • p – Pointer to TextFun object.

  • type – Function type being set 

    x=TEXTFUN_BACKCOLOR        Set BackColor function
 =TEXTFUN_BORDERWIDTH      Set BorderWidth function
 =TEXTFUN_CLOSEFILE        Set CloseFile function
 =TEXTFUN_CONNECTFILE      Set ConnectFile function
 =TEXTFUN_DISCONNECTFILE   Set DisconnectFile function
 =TEXTFUN_FORMACTION       Set FormAction function
 =TEXTFUN_FORMINIT         Set FormInit function
 =TEXTFUN_FORMTERM         Set FormTerm function
 =TEXTFUN_HEADINGLEVEL     Set HeadingLevel function
 =TEXTFUN_HORIZONTALRULE   Set HorizontalRule function
 =TEXTFUN_IMAGEFILE        Set ImageFile function
 =TEXTFUN_LISTTYPE         Set ListType function
 =TEXTFUN_OPENFILE         Set OpenFile function
 =TEXTFUN_QUERYFILE        Set QueryFile function
 =TEXTFUN_RULEWIDTH        Set RuleWidth function
 =TEXTFUN_SETMODE          Set SetMode function
 =TEXTFUN_SPACE            Set Space function
 =TEXTFUN_STRING           Set String function
 =TEXTFUN_TABLECOLOR       Set TableColor function
 =TEXTFUN_TABLEWIDTH       Set TableWidth function
 =TEXTFUN_TEXTCOLOR        Set TextColor function

  • function – Pointer to text function

void vsy_TextFunSetErrorFunction(vsy_TextFun *p, VfuncInt *function)

set pointer to error function

Set pointers to error functions

Parameters:

  • p – Pointer to TextFun object.

  • function – Pointer to error function

void vsy_TextFunGet(vsy_TextFun *p, Vint type, Vfunc **function)

get pointer to text function

See vsy_TextFunSet()

void vsy_TextFunSetObj(vsy_TextFun *p, Vobject *obj)

set pointer to auxiliary object

Set pointer to text function auxiliary object.

Get obj as an output argument using 

void vsy_TextFunGetObj (vsy_TextFun *textfun,
                        Vobject **obj)

Parameters:

  • p – Pointer to TextFun object.

  • obj – Pointer to auxiliary object

void vsy_TextFunGetObj(vsy_TextFun *p, Vobject **obj)

get pointer to auxiliary object

See vsy_TextFunSetObj()

void vsy_TextFunCopy(vsy_TextFun *p, vsy_TextFun *fromp)

make a copy of a TextFun object

See vsy_TextFunBegin()

void vsy_TextFunAPI(vsy_TextFun *p, Vint api)

set built-in text functions

Set built in text functions. The TEXTFUN_APIPRINT text functions print each graphics primitive to standard output. The TEXTFUN_APIRETURN text functions simply return.

Errors

SYS_ERROR_ENUM is generated if an improper api is input.

Parameters:

  • p – Pointer to TextFun object.

  • api – Type of built-in text function to return. 

    x=TEXTFUN_APIPRINT       Set printing text functions
 =TEXTFUN_APIRETURN      Set return text functions

void vsy_TextFunOpenFile(vsy_TextFun *p, Vchar *pathname)

open file

Open a file which will be used to output formatted text. Close the file with vsy_TextFunCloseFile().

Parameters:

  • p – Pointer to TextFun object.

  • pathname – Name of file to open

void vsy_TextFunCloseFile(vsy_TextFun *p)

close file

Close file. The file must have been previously opened with vsy_TextFunOpenFile().

Parameters:

p – Pointer to TextFun object.

void vsy_TextFunConnectFile(vsy_TextFun *p, FILE *fd)

connect to preexisting file

Connect to a previously opened file. The text interface will now format output to file descriptor fd. Use vsy_TextFunDisconnectFile() to disconnect from an existing file.

Parameters:

  • p – Pointer to TextFun object.

  • fd – File descriptor of file to connect to

void vsy_TextFunDisconnectFile(vsy_TextFun *p)

disconnect from file

Disconnect from a file descriptor. This function does not close the file.

Parameters:

p – Pointer to TextFun object.

void vsy_TextFunQueryFile(vsy_TextFun *p, FILE **fd)

query current file

Return the currently open or connected file descriptor.

Parameters:

  • p – Pointer to TextFun object.

  • fd – [out] Current connected or opened file descriptor

void vsy_TextFunListType(vsy_TextFun *p, Vint listtype)

set current list type

Set the current list type. A list is formatted using form actions. The default listtype is SYS_TEXT_UNORDERED.

Errors

SYS_ERROR_ENUM is generated if an improper listtype is specified.

Parameters:

  • p – Pointer to TextFun object.

  • listtype – Current listtype 

    x=SYS_TEXT_UNORDERED       Unordered list
 =SYS_TEXT_ORDERED         Ordered list
 =SYS_TEXT_MENU            Menu list

void vsy_TextFunHeadingLevel(vsy_TextFun *p, Vint level)

set heading level

Set the current heading level A heading is formatted using form actions. The default level is 1.

Errors

SYS_ERROR_VALUE is generated if a level out of range is specified.

Parameters:

  • p – Pointer to TextFun object.

  • level – Heading level 1 <= level <= 5.

void vsy_TextFunRuleWidth(vsy_TextFun *p, Vint rulewidth)

set rule width

Set the current horizontal rule width. The rule width must be a positive integer. A horizontal rule is formatted using vsy_TextFunHorizontalRule(). The default rulewidth is 1.

Errors

SYS_ERROR_VALUE is generated if an improper a rulewidth is specified

Parameters:

  • p – Pointer to TextFun object.

  • rulewidth – Current horizontal rule width

void vsy_TextFunSetMode(vsy_TextFun *p, Vint mode, Vint flag)

set text mode

Enable and disable a text formatting modes.

The SYS_TEXT_BOLD mode is used to format text using the bold form of the current font. By default SYS_TEXT_BOLD mode is off.

The SYS_TEXT_CENTER mode is used to center text. By default SYS_TEXT_CENTER mode is off.

The SYS_TEXT_ITALICS mode is used to format text using the italic form of the current font. By default SYS_TEXT_ITALICS mode is off.

The SYS_TEXT_PREFORMATTED mode is used to format text in a preformatted form. By default SYS_TEXT_PREFORMATTED mode is off.

The SYS_TEXT_TYPEWRITER mode is used to format text using a monospaced font. By default SYS_TEXT_TYPEWRITER mode is off.

The SYS_TEXT_HANDLEERR mode is used to toggle invoking the error handler if an error is detected. In some applications an error handler is used which utilizes text functions. If an error occurs within the text functions it is possible to create an infinite loop of the text functions calling themselves. By default SYS_TEXT_HANDLEERR mode is off.

Errors

SYS_ERROR_ENUM is generated if an improper mode is specified.

Parameters:

  • p – Pointer to TextFun object.

  • mode – Text mode 

    x=SYS_TEXT_BOLD            Bold font
 =SYS_TEXT_CENTER          Center text
 =SYS_TEXT_ITALICS         Italics font
 =SYS_TEXT_PREFORMATTED    Preformatted text
 =SYS_TEXT_TYPEWRITER      Typewriter font
 =SYS_TEXT_HANDLEERR       Invoke error handler

  • flag – Mode flag 

    =SYS_OFF      Turn mode off
=SYS_ON       Turn mode on

void vsy_TextFunFormInit(vsy_TextFun *p, Vint form)

initiate form

Initiate a text format. Each text form is terminated using vsy_TextFunFormTerm().

Parameters:

  • p – Pointer to TextFun object.

  • form – Text form 

    x=SYS_TEXT_TITLE           Page title
 =SYS_TEXT_HEADING         Heading
 =SYS_TEXT_LIST            List
 =SYS_TEXT_ITEM            List item
 =SYS_TEXT_TABLE           Table
 =SYS_TEXT_COLUMN          Table column
 =SYS_TEXT_ROW             Table row

void vsy_TextFunFormTerm(vsy_TextFun *p, Vint form)

terminate form

Terminate a text format.

Parameters:

  • p – Pointer to TextFun object.

  • form – Text form

void vsy_TextFunFormAction(vsy_TextFun *p, Vint formaction)

perform form action

Perform a form action.

The action SYS_TEXT_PARAGRAPH marks the beginning of a new paragraph. A line break is performed and a blank line is inserted.

The action SYS_TEXT_LINEBREAK forces text immediately after the line break onto the next line.

Parameters:

  • p – Pointer to TextFun object.

  • formaction – Text form action 

    x=SYS_TEXT_PARAGRAPH       Paragraph break
 =SYS_TEXT_LINEBREAK       Line break

void vsy_TextFunHorizontalRule(vsy_TextFun *p)

horizontal rule

Generate a horizontal line across the width of the page. The width the of the horizontal rule is determined by the current rule width set using vsy_TextFunRuleWidth().

Parameters:

p – Pointer to TextFun object.

void vsy_TextFunImageFile(vsy_TextFun *p, Vchar *pathname)

image file

Define an image file primitive. The pathname contains the image.

Parameters:

  • p – Pointer to TextFun object.

  • pathname – Name of image file primitive

void vsy_TextFunString(vsy_TextFun *p, const Vchar *string)

character string

Generate a text string primitive.

Parameters:

  • p – Pointer to TextFun object.

  • string – Character string primitive

void vsy_TextFunSpace(vsy_TextFun *p, Vint nspaces)

character spaces

Generate a text primitive consisting of a number, nspaces, of character spaces.

Parameters:

  • p – Pointer to TextFun object.

  • nspaces – Number of character spaces in space primitive

void vsy_TextFunTextColor(vsy_TextFun *p, Vfloat c[3])

set text RGB color

Set the text color. The text color may be set before any string primitive using vsy_TextFunString(). By default the text color is black, (0.,0.,0.).

Parameters:

  • p – Pointer to TextFun object.

  • c – Current text color RGB values

void vsy_TextFunTableColor(vsy_TextFun *p, Vfloat c[3])

set table RGB color

Set the table color. The table color may be set before any call to vsy_TextFunFormInit() with SYS_TEXT_ROW or SYS_TEXT_COLUMN to affect the following table row or column respectively. By default the table color is a light blue, (0.733333,0.866666,1.0). This is the same as the default background color

Parameters:

  • p – Pointer to TextFun object.

  • c – Current table color RGB values

void vsy_TextFunBackColor(vsy_TextFun *p, Vfloat c[3])

set background RGB color

Set the background color. The background color must be set before any other text attributes, primitives or form actions. By default the background color is a light blue, (0.733333,0.866666,1.0).

Parameters:

  • p – Pointer to TextFun object.

  • c – Current background color RGB values

void vsy_TextFunBorderWidth(vsy_TextFun *p, Vint borderwidth)

set table border width

Set the width of table cell borders. If the border width is zero then the table cells will have no borders. By default borderwidth is 0.

Errors

SYS_ERROR_VALUE is generated if an improper borderwidth is specified.

Parameters:

  • p – Pointer to TextFun object.

  • borderwidth – Width of table cell borders in pixels, borderwidth >= 0

void vsy_TextFunTableWidth(vsy_TextFun *p, Vint tablewidth)

set table width

Set the width of a table. If the table width is zero then the table will be sized by contents. By default tablewidth is 0.

Errors

SYS_ERROR_VALUE is generated if an improper tablewidth is specified.

Parameters:

  • p – Pointer to TextFun object.

  • tablewidth – Width of table in percent of page, tablewidth >= 0

void vsy_TextFunColumnAlign(vsy_TextFun *p, Vint align)

set column alignment

Set alignment of text in a table column. A table is formatted using form actions.

Errors

SYS_ERROR_ENUM is generated if an improper align is specified.

Parameters:

  • p – Pointer to TextFun object.

  • align – Table column alignment 

    x=SYS_TEXT_LEFT            Left
 =SYS_TEXT_RIGHT           Right
 =SYS_TEXT_MIDDLE          Middle

9.6. Text Tee - TextTee

Use a TextTee object to split or tee text functions. A TextTee object accepts text functions as input and immediately calls one or more text function objects as output. In this way a stream of text primitives may be directed to many text formatting interfaces simultaneously.

Use vsy_TextTeeBegin() to instance a TextTee object. Establish the input text functions in a TextFun object using vsy_TextTeeTextFun(). Use up to eight calls to vsy_TextTeeSetObject() to set the TextFun objects used as output.

9.6.1. Function Descriptions

The currently available TextTee functions are described in detail in this section.

vsy_TextTee *vsy_TextTeeBegin(void)

create an instance of a TextTee object

Create an instance of a TextTee object. Memory is allocated for the object private data and the pointer to the data is returned. The output text function objects are set to NULL.

Destroy an instance of a TextTee object using 

void vsy_TextTeeEnd (vsy_TextTee *texttee)

Return the current value of a TextTee object error flag using 

Vint vsy_TextTeeError (vsy_TextTee *texttee)

Returns:

The function returns a pointer to the newly created TextTee object. If the object creation fails, NULL is returned.

void vsy_TextTeeEnd(vsy_TextTee *p)

destroy an instance of a TextTee object

See vsy_TextTeeBegin()

Vint vsy_TextTeeError(vsy_TextTee *p)

return the current value of a TextTee object error flag

See vsy_TextTeeBegin()

void vsy_TextTeeSetObject(vsy_TextTee *p, Vint objecttype, Vobject *object)

set pointers to output text function objects

Set a pointer to an output text function object. This function may be called repeatedly to set up to 8 output text functions. Note that VSY_TEXTFUN is the same as VSY_TEXTFUN_0, VSY_TEXTFUN_TEE is the same as VSY_TEXTFUN_1 and VSY_TEXTFUN_n is the same as VSY_TEXTFUN + n.

Errors

SYS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to TextTee object.

  • objecttype – The name of the object type to be set. 

    x=VSY_TEXTFUN            TextFun object
 =VSY_TEXTFUN_TEE        TextFun object
 =VSY_TEXTFUN_0          TextFun object
 =VSY_TEXTFUN_1          TextFun object
 =VSY_TEXTFUN_2          TextFun object
 =VSY_TEXTFUN_3          TextFun object
 =VSY_TEXTFUN_4          TextFun object
 =VSY_TEXTFUN_5          TextFun object
 =VSY_TEXTFUN_6          TextFun object
 =VSY_TEXTFUN_7          TextFun object

  • object – Pointer to the object to be set.

void vsy_TextTeeTextFun(vsy_TextTee *p, vsy_TextFun *textfun)

return pointers to text functions

Fill a TextFun object with text functions.

Parameters:

  • p – Pointer to TextTee object.

  • textfun – Pointer to TextFun object to be filled with text functions

9.7. Plain Text Format - PlainText

Use a PlainText object to format to plain text documents. Plain text documents contain only simple text with no special embedded formatting text strings. The PlainText module contains the following functions.

Use vsy_PlainTextBegin() to instance a PlainText object. Establish the input text functions in a TextFun object using vsy_PlainTextTextFun(). The character width of the plain text document may be specified using vsy_PlainTextSetPageWidth(). Destroy a PlainText object using vsy_PlainTextEnd().

9.7.1. Function Descriptions

The currently available PlainText functions are described in detail in this section.

vsy_PlainText *vsy_PlainTextBegin(void)

create an instance of a PlainText object

Create an instance of a PlainText object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a PlainText object using 

void vsy_PlainTextEnd (vsy_PlainText *plaintext)

Return the current value of a PlainText object error flag using 

Vint vsy_PlainTextError (vsy_PlainText *plaintext)

Returns:

The function returns a pointer to the newly created PlainText object. If the object creation fails, NULL is returned.

void vsy_PlainTextEnd(vsy_PlainText *p)

destroy an instance of a PlainText object

See vsy_PlainTextBegin()

Vint vsy_PlainTextError(vsy_PlainText *p)

return the current value of a PlainText object error flag

See vsy_PlainTextBegin()

void vsy_PlainTextSetPageWidth(vsy_PlainText *p, Vint pagewidth)

specify page width

Specify the plain text page width in characters. The default pagewidth is 80.

Errors

SYS_ERROR_VALUE is generated if an improper pagewidth is specified.

Parameters:

  • p – Pointer to PlainText object.

  • pagewidth – Page width in characters, pagewidth >= 20

void vsy_PlainTextTextFun(vsy_PlainText *p, vsy_TextFun *textfun)

return pointers to text functions

Fill a TextFun object with text functions.

Parameters:

  • p – Pointer to PlainText object.

  • textfun – Pointer to TextFun object to be filled with text functions

9.8. HTML Text Format - HTMLText

Use a HTMLText object to format to HTML text documents. HTML text documents contain HTML formatting text strings. The HTMLText module contains the following functions.

Use vsy_HTMLTextBegin() to instance a HTMLText object. Establish the input text functions in a TextFun object using vsy_HTMLTextTextFun(). Destroy a HTMLText object using vsy_HTMLTextEnd().

9.8.1. Function Descriptions

The currently available HTMLText functions are described in detail in this section.

vsy_HTMLText *vsy_HTMLTextBegin(void)

create an instance of an HTMLText object

Create an instance of a HTMLText object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a HTMLText object using 

void vsy_HTMLTextEnd (vsy_HTMLText *htmltext)

Return the current value of a HTMLText object error flag using 

Vint vsy_HTMLTextError (vsy_HTMLText *htmltext)

Returns:

The function returns a pointer to the newly created HTMLText object. If the object creation fails, NULL is returned.

void vsy_HTMLTextEnd(vsy_HTMLText *p)

destroy an instance of a HTMLText object

See vsy_HTMLTextBegin()

Vint vsy_HTMLTextError(vsy_HTMLText *p)

return the current value of an HTMLText object error flag

See vsy_HTMLTextBegin()

void vsy_HTMLTextTextFun(vsy_HTMLText *p, vsy_TextFun *textfun)

return pointers to text functions

Fill a TextFun object with text functions.

Parameters:

  • p – Pointer to HTMLText object.

  • textfun – Pointer to TextFun object to be filled with text functions

9.9. LaTeX Text Format - LaTeXText

Use a LaTeXText object to format to LaTeX text documents. LaTeX text documents contain LaTeX formatting text strings. The LaTeXText module contains the following functions.

Use vsy_LaTeXTextBegin() to instance a LaTeXText object. Establish the input text functions in a TextFun object using vsy_LaTeXTextTextFun(). Destroy a LaTeXText object using vsy_LaTeXTextEnd().

9.9.1. Function Descriptions

The currently available LaTeXText functions are described in detail in this section.

vsy_LaTeXText *vsy_LaTeXTextBegin(void)

create an instance of a LaTeXText object

Create an instance of a LaTeXText object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a LaTeXText object using 

void vsy_LaTeXTextEnd (vsy_LaTeXText *latextext)

Return the current value of a LaTeXText object error flag using 

Vint vsy_LaTeXTextError (vsy_LaTeXText *latextext)

Returns:

The function returns a pointer to the newly created LaTeXText object. If the object creation fails, NULL is returned.

void vsy_LaTeXTextEnd(vsy_LaTeXText *p)

destroy an instance of a LaTeXText object

See vsy_LaTeXTextBegin()

Vint vsy_LaTeXTextError(vsy_LaTeXText *p)

return the current value of a LaTeXText object error flag

See vsy_LaTeXTextBegin()

void vsy_LaTeXTextTextFun(vsy_LaTeXText *p, vsy_TextFun *textfun)

return pointers to text functions

Fill a TextFun object with text functions.

Parameters:

  • p – Pointer to LaTeXText object.

  • textfun – Pointer to TextFun object to be filled with text functions