<!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML//EN">
<title>MHonArc Resources: TEXTCLIPFUNC
</title>
<table border=
0><tr valign=
"top">
<td align=
"left" width=
"50%">[Prev:
<a href=
"tcontend.html">TCONTEND
</a>]
</td><td><nobr>[
<a href=
"../resources.html#textclipfunc">Resources
</a>][
<a href=
"../mhonarc.html">TOC
</a>]
</nobr></td><td align=
"right" width=
"50%">[Next:
<a href=
"tfirstpglink.html">TFIRSTPGLINK
</a>]
</td></tr></table>
<!-- *************************************************************** -->
<dt><strong>Envariable
</strong></dt>
<dt><strong>Element
</strong></dt>
<code><TEXTCLIPFUNC
></code><br>
<var>function_name
</var>;
<var>source_file
</var><br>
<code></TEXTCLIPFUNC
></code><br>
<dt><strong>Command-line Option
</strong></dt>
<!-- *************************************************************** -->
<p>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
<a href=
"../rcvars.html">resource variable
</a>, e.g.
<p>The syntax for TEXTCLIPFUNC is as follows:
<var>routine-name
</var>;
<var>file-of-routine
</var></pre>
<p>The definition of each semi-colon-separated value is as follows:
<dt><var>routine-name
</var></dt>
<dd><p>The actual routine name of the filter. The name
should be fully qualified by the package it is defined in
(e.g.
"<code>mypackage::filter</code>").
<dt><var>file-of-routine
</var></dt>
<dd><p>The name of the file that defines
<var>routine-name
</var>. 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
<A HREF=
"perlinc.html">PERLINC
</A>
<p><var>file-of-routine
</var> can be left blank if it is
known that
<var>routine-name
</var> will already be loaded, as
is the case for the default value for this resource since the
routine is an internal MHonArc function.
<h3><a name=
"writing">Writing a Clipping Function
</a></h3>
<p>If you want to write your own function, you need to know the Perl
programming language. The following information assumes you know Perl.
<h4>Function Interface
</h4>
<P>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:
</P>
my(
<b>$text
</b>,
<b>$clip_length
</b>,
<b>$is_html
</b>,
<b>$has_tags
</b>) = @_;
<h5>Parameter Descriptions
</h5>
<table cellspacing=
1 border=
0 cellpadding=
4>
<td><strong><code>$text
</code></strong></td>
<td><p>The text to be clipped.
<p><b>NOTE:
</b> Since Perl allows one to modify the data passed into
it, the first argument should
<strong>NOT
</strong> be modified. If
you copy arguments from
<tt>@_
</tt> as shown above, then you will be
okay since the
<tt>my
</tt> operation creates a copy of the arguments
<td><strong><code>$clip_length
</code></strong></td>
<td><p>The number of characters
<code>$text
</code> should be clipped to.
<td><strong><code>$is_html
</code></strong></td>
<td><p>The text may contain entity references, e.g.
"<tt>&amp;</tt>".
Entity references should be considered a single character when
clipping
<code>$text
</code>.
<td><strong><code>$has_tags
</code></strong></td>
<td><p>The text may contain HTML tags, and the tags should be stripped
from
<code>$text
</code> when generating the clip string. For example,
if
<code>$text
</code> equals
"<tt><b>MHonArc</b></tt>" and
<code>$clip_length
</code> equals
2, then the return value of the
function should be
"<tt>MH</tt>".
<table border=
0 cellpadding=
4>
<td><strong>NOTE
</strong></td>
<td><p>The
<code>$has_tags
</code> argument is currently
not used within MHonArc, but it will likely be used in a future release.
<p>The return value should be the clipped version of
<code>$text
</code>.
<li><p>Qualify your filter in its own package. This eliminates possible
variable/routine conflicts with MHonArc.
<li><p>Make sure your Perl source file ends with a true statement
(like
"<code>1;</code>"). MHonArc just performs a
<strong><code>require
</code></strong>
on the file, and if the file does not return
true, MHonArc will revert to the default value for TEXTCLIPFUNC.
<li><p>Test your function before production use.
<!-- *************************************************************** -->
<!-- *************************************************************** -->
<h2>Resource Variables
</h2>
<!-- *************************************************************** -->
<p>The
<a href=
"../rcfileexs/utf-8.mrc.html">Unicode
</a> example
resource file sets TEXTCLIPFUNC to a routine that understands UTF-
8
<p>The following is the implementation (as of this writing) of
MHonArc's default clipping function:
my $str = \shift; # Prevent unnecessary copy.
my $len = shift; # Clip length
my $is_html = shift; # If entity references should be considered
my $has_tags = shift; # If html tags should be stripped
return substr($$str,
0, $len);
my $html_len = length($$str);
my($pos, $sublen, $erlen, $real_len);
for ( $pos=
0, $sublen=$len; $pos
< $html_len; ) {
$subtext = substr($$str, $pos, $sublen);
$subtext =~ s/\A[^
<]*
>//; # clipped tag
$subtext =~ s/
<[^
>]*
>//g;
$subtext =~ s/
<[^
>]*\Z//; # clipped tag
# check for clipped entity reference
if (($pos
< $html_len)
&& ($subtext =~ /\
&[^;]*\Z/)) {
my $semi = index($$str, ';', $pos);
# malformed entity reference
$subtext .= substr($$str, $pos);
$subtext .= substr($$str, $pos, $semi-$pos+
1)
# compute entity reference lengths to determine
"real" character
# count and not raw character count.
while ($subtext =~ /(\
&[^;]+);/g) {
$real_len = length($text)-$er_len;
if ($real_len
>= $len) {
$sublen = $len - (length($text)-$er_len);
<!-- *************************************************************** -->
<!-- *************************************************************** -->
<p><a href=
"../rcvars.html"><cite>Resource Variables
</cite></a>
<!-- *************************************************************** -->
<table border=
0><tr valign=
"top">
<td align=
"left" width=
"50%">[Prev:
<a href=
"tcontend.html">TCONTEND
</a>]
</td><td><nobr>[
<a href=
"../resources.html#textclipfunc">Resources
</a>][
<a href=
"../mhonarc.html">TOC
</a>]
</nobr></td><td align=
"right" width=
"50%">[Next:
<a href=
"tfirstpglink.html">TFIRSTPGLINK
</a>]
</td></tr></table>
$Date:
2002/
08/
04 03:
58:
27 $
<br>
<img align=
"top" src=
"../monicon.png" alt=
"">
<a href=
"http://www.mhonarc.org/"><strong>MHonArc
</strong></a><br>
Copyright
© 2002,
<a href=
"http://www.earlhood.com/"
>Earl Hood
</a>,
<a href=
"mailto:mhonarc@mhonarc.org"
>mhonarc@mhonarc.org
</a><br>