<html> <head> <title>MHonArc Resources: TEXTCLIPFUNC</title> <link rel="stylesheet" type="text/css" href="../docstyles.css"> </head> <body> <!--x-rc-nav--> <table border=0><tr valign="top"> <td align="left" width="50%">[Prev: <a href="tendlinkia.html">TENDLINKIA</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="textencode.html">TEXTENCODE</a>]</td></tr></table> <!--/x-rc-nav--> <hr> <h1>TEXTCLIPFUNC</h1> <!--X-TOC-Start--> <ul> <li><a href="#syntax">Syntax</a> <li><a href="#description">Description</a> <ul> <li><small><a href="#writing">Writing a Clipping Function</a></small> </ul> <li><a href="#default">Default Setting</a> <li><a href="#rcvars">Resource Variables</a> <li><a href="#examples">Examples</a> <li><a href="#version">Version</a> <li><a href="#seealso">See Also</a> </ul> <!--X-TOC-End--> <!-- *************************************************************** --> <hr> <h2><a name="syntax">Syntax</a></h2> <dl> <dt><strong>Envariable</strong></dt> <dd><p>N/A </p> </dd> <dt><strong>Element</strong></dt> <dd><p> <code><TEXTCLIPFUNC></code><br> <var>function_name</var>;<var>source_file</var><br> <code></TEXTCLIPFUNC></code><br> </p> </dd> <dt><strong>Command-line Option</strong></dt> <dd><p>N/A </p> </dd> </dl> <!-- *************************************************************** --> <hr> <h2><a name="description">Description</a></h2> <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. <tt>$SUBJECTNA:72$</tt>. </p> <p>The syntax for TEXTCLIPFUNC is as follows: </p> <pre> <var>routine-name</var>;<var>file-of-routine</var></pre> <p>The definition of each semi-colon-separated value is as follows: </p> <dl> <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>"). </p> <dd> <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> resource. </p> <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. </p> </dd> </dl> <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. </p> <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> <pre> sub <var>clip</var> { my(<b>$text</b>, <b>$clip_length</b>, <b>$is_html</b>, <b>$has_tags</b>) = <!-- -->@<!-- -->_; <var># code here } </pre> <h5>Parameter Descriptions</h5> <table cellspacing=1 border=0 cellpadding=4> <tr valign=top> <td><strong><code>$text</code></strong></td> <td><p>The text to be clipped. </p> <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 in <tt><!-- -->@<!-- -->_</tt>. </p> </td> </tr> <tr valign=top> <td><strong><code>$clip_length</code></strong></td> <td><p>The number of characters <code>$text</code> should be clipped to. </p> </td> </tr> <tr valign=top> <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>. </p> </td> </tr> <tr valign=top> <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>". </p> <table border=0 cellpadding=4> <tr valign=top> <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> </td> </tr> </table> </td> </tr> </table> <h5>Return Value</h5> <p>The return value should be the clipped version of <code>$text</code>. </p> <H4>Writing Tips</h4> <ul> <li><p>Qualify your filter in its own package. This eliminates possible variable/routine conflicts with MHonArc. </p> <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. </p> <li><p>Test your function before production use. </p> </ul> <!-- *************************************************************** --> <hr> <h2><a name="default">Default Setting</a></h2> <pre> mhonarc::clip_text; </pre> <!-- *************************************************************** --> <hr> <h2><a name="rcvars">Resource Variables</a></h2> <p>N/A </p> <!-- *************************************************************** --> <hr> <h2><a name="examples">Examples</a></h2> <p>See <a href="charsetconverters.html">CHARSETCONVERTERS</a> and <a href="textencode.html">TEXTENCODE</a> resources for example usages of TEXTCLIPFUNC. </p> <p>The <a href="../rcfileexs/utf-8.mrc.html">utf-8.mrc</a> example resource file sets TEXTCLIPFUNC to a routine that understands UTF-8 text. </p> <!-- *************************************************************** --> <hr> <h2><a name="version">Version</a></h2> <p>2.5.10 </p> <!-- *************************************************************** --> <hr> <h2><a name="seealso">See Also</a></h2> <p> <a href="charsetconverters.html">CHARSETCONVERTERS</a>, <a href="textencode.html">TEXTENCODE</a> </p> <p><a href="../rcvars.html"><cite>Resource Variables</cite></a> </p> <!-- *************************************************************** --> <hr> <!--x-rc-nav--> <table border=0><tr valign="top"> <td align="left" width="50%">[Prev: <a href="tendlinkia.html">TENDLINKIA</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="textencode.html">TEXTENCODE</a>]</td></tr></table> <!--/x-rc-nav--> <hr> <address> $Date: 2003/10/06 22:04:21 $<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%40mhonarc.org" >mhonarc<!-- -->@<!-- -->mhonarc.org</a><br> </address> </body> </html>