[Prev: TENDLINKIA][Resources][TOC][Next: TEXTENCODE]

TEXTCLIPFUNC


Syntax

Envariable

N/A

Element

<TEXTCLIPFUNC>
function_name;source_file
</TEXTCLIPFUNC>

Command-line Option

N/A


Description

TEXTCLIPFUNC defines the the Perl function to invoke when MHonArc clips text. For example, the function specified would be invoked when a length specifier is used for a resource variable, e.g. $SUBJECTNA:72$.

The syntax for TEXTCLIPFUNC is as follows:

routine-name;file-of-routine

The definition of each semi-colon-separated value is as follows:

routine-name

The actual routine name of the filter. The name should be fully qualified by the package it is defined in (e.g. "mypackage::filter").

file-of-routine

The name of the file that defines routine-name. If the file is not a full pathname, MHonArc finds the file by looking in the standard include paths of Perl, and the paths specified by the PERLINC resource.

file-of-routine can be left blank if it is known that routine-name will already be loaded, as is the case for the default value for this resource since the routine is an internal MHonArc function.

Writing a Clipping Function

If you want to write your own function, you need to know the Perl programming language. The following information assumes you know Perl.

Function Interface

MHonArc interfaces with text clipping function by calling the routine with a specific set of arguments. The prototype of the interface routine is as follows:

sub clip {
    my($text, $clip_length, $is_html, $has_tags) = @_;
    # code here
}
Parameter Descriptions
$text

The text to be clipped.

NOTE: Since Perl allows one to modify the data passed into it, the first argument should NOT be modified. If you copy arguments from @_ as shown above, then you will be okay since the my operation creates a copy of the arguments in @_.

$clip_length

The number of characters $text should be clipped to.

$is_html

The text may contain entity references, e.g. "&amp;". Entity references should be considered a single character when clipping $text.

$has_tags

The text may contain HTML tags, and the tags should be stripped from $text when generating the clip string. For example, if $text equals "<b>MHonArc</b>" and $clip_length equals 2, then the return value of the function should be "MH".

NOTE

The $has_tags argument is currently not used within MHonArc, but it will likely be used in a future release.

Return Value

The return value should be the clipped version of $text.

Writing Tips


Default Setting

mhonarc::clip_text;

Resource Variables

N/A


Examples

See CHARSETCONVERTERS and TEXTENCODE resources for example usages of TEXTCLIPFUNC.

The utf-8.mrc example resource file sets TEXTCLIPFUNC to a routine that understands UTF-8 text.


Version

2.5.10


See Also

CHARSETCONVERTERS, TEXTENCODE

Resource Variables


[Prev: TENDLINKIA][Resources][TOC][Next: TEXTENCODE]

$Date: 2003/10/06 22:04:21 $
MHonArc
Copyright © 2002, Earl Hood, mhonarc@mhonarc.org