PageRenderTime 14ms CodeModel.GetById 1ms app.highlight 10ms RepoModel.GetById 1ms app.codeStats 0ms

/www/tags/NOV_07_2009/htdocs/42docs/users-guide/mode-tag-rules.html

#
HTML | 107 lines | 105 code | 2 blank | 0 comment | 0 complexity | 3fd68fc1c7a94d467a39479fd0c25363 MD5 | raw file
  1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The RULES Tag</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="jEdit 4.2 User's Guide"><link rel="up" href="writing-modes.html" title="Chapter 10. Mode Definition Syntax"><link rel="previous" href="mode-tag-props.html" title="The PROPS Tag"><link rel="next" href="mode-rule-terminate.html" title="The TERMINATE Tag"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">The RULES Tag</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="mode-tag-props.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Mode Definition Syntax</th><td width="20%" align="right"> <a accesskey="n" href="mode-rule-terminate.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mode-tag-rules"></a>The RULES Tag</h2></div></div><div></div></div><p>
  2   <tt class="literal">RULES</tt> tags must be placed inside the
  3   <tt class="literal">MODE</tt> tag. Each <tt class="literal">RULES</tt> tag defines a
  4   <i class="firstterm">ruleset</i>. A ruleset consists of a number of
  5   <i class="firstterm">parser rules</i>, with each parser
  6   rule specifying how to highlight a specific syntax token. There must
  7   be at least one ruleset in each edit mode. There can also be more
  8   than one, with different rulesets being used to highlight different
  9   parts of a buffer (for example, in HTML mode, one rule set
 10   highlights HTML tags, and another highlights inline JavaScript).
 11   For information about using more
 12   than one ruleset, see <a href="mode-rule-span.html" title="The SPAN Tag">the section called &#8220;The SPAN Tag&#8221;</a>.
 13  </p><p>
 14   The <tt class="literal">RULES</tt> tag supports the following attributes, all of
 15   which are optional:
 16  </p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">SET</tt> - the name of this ruleset.
 17   All rulesets other than the first must have a name.
 18   </p></li><li><p><tt class="literal">IGNORE_CASE</tt> - if set to
 19   <tt class="literal">FALSE</tt>, matches will be case sensitive. Otherwise, case
 20   will not matter. Default is <tt class="literal">TRUE</tt>.
 21   </p></li><li><p><tt class="literal">NO_WORD_SEP</tt> - any non-alphanumeric
 22   character <span class="emphasis"><em>not</em></span> in this list is treated as a word separator
 23   for the purposes of syntax highlighting.
 24   </p></li><li><p><tt class="literal">DEFAULT</tt> - the token type for
 25   text which doesn't match
 26   any specific rule. Default is <tt class="literal">NULL</tt>. See
 27   <a href="mode-syntax-tokens.html" title="Token Types">the section called &#8220;Token Types&#8221;</a> for a list of token types.
 28   </p></li><li><p><tt class="literal">HIGHLIGHT_DIGITS</tt>
 29   </p></li><li><p><tt class="literal">DIGIT_RE</tt> - see below for information
 30   about these two attributes.</p></li></ul></div><p>
 31   Here is an example <tt class="literal">RULES</tt> tag:
 32  </p><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting">&lt;RULES IGNORE_CASE="FALSE" HIGHLIGHT_DIGITS="TRUE"&gt;
 33    <i class="replaceable"><tt>... parser rules go here ...</tt></i>
 34&lt;/RULES&gt;</pre></td></tr></table><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2628554"></a>Highlighting Numbers</h3></div></div><div></div></div><p>
 35    If the <tt class="literal">HIGHLIGHT_DIGITS</tt> attribute is set to
 36    <tt class="literal">TRUE</tt>, jEdit will attempt to highlight numbers in this
 37    ruleset.
 38   </p><p>
 39    Any word consisting entirely of digits (0-9) will be highlighted with the
 40    <tt class="literal">DIGIT</tt> token type.
 41    A word that contains other letters in addition to digits will be
 42    highlighted with the
 43    <tt class="literal">DIGIT</tt> token type only if it matches the regular
 44    expression specified in the <tt class="literal">DIGIT_RE</tt> attribute.
 45    If this attribute is not specified, it will not be highlighted.
 46   </p><p>
 47    Here is an example <tt class="literal">DIGIT_RE</tt> regular expression that highlights
 48    Java-style numeric literals (normal numbers, hexadecimals
 49    prefixed with <tt class="literal">0x</tt>, numbers suffixed with various
 50    type indicators, and floating point literals containing an exponent):
 51   </p><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting">DIGIT_RE="(0x[[:xdigit:]]+|[[:digit:]]+(e[[:digit:]]*)?)[lLdDfF]?"</pre></td></tr></table><p>
 52    Regular expression syntax is described in <a href="regexps.html" title="Appendix E. Regular Expressions">Appendix E, <i>Regular Expressions</i></a>.
 53   </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rule-ordering"></a>Rule Ordering Requirements</h3></div></div><div></div></div><p>
 54    You might encounter this very common pitfall when writing your own modes.
 55   </p><p>
 56    Since jEdit checks buffer text against parser rules in the order they appear
 57    in the ruleset, more specific rules must be placed before generalized ones,
 58    otherwise the generalized rules will catch everything.
 59   </p><p>
 60    This is best demonstrated with an example. The following is incorrect rule
 61    ordering:
 62   </p><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting">&lt;SPAN TYPE="MARKUP"&gt;
 63    &lt;BEGIN&gt;[&lt;/BEGIN&gt;
 64    &lt;END&gt;]&lt;/END&gt;
 65&lt;/SPAN&gt;
 66
 67&lt;SPAN TYPE="KEYWORD1"&gt;
 68    &lt;BEGIN&gt;[!&lt;/BEGIN&gt;
 69    &lt;END&gt;]&lt;/END&gt;
 70&lt;/SPAN&gt;</pre></td></tr></table><p>
 71    If you write the above in a rule set, any occurrence of &#8220;<span class="quote">[</span>&#8221;
 72    (even things like &#8220;<span class="quote">[!DEFINE</span>&#8221;, etc) 
 73    will be highlighted using the first rule, because it will be the
 74    first to match. This is most likely not the intended behavior.
 75   </p><p>
 76    The problem can be solved by placing the more specific rule before the
 77    general one:
 78   </p><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting">&lt;SPAN TYPE="KEYWORD1"&gt;
 79    &lt;BEGIN&gt;[!&lt;/BEGIN&gt;
 80    &lt;END&gt;]&lt;/END&gt;
 81&lt;/SPAN&gt;
 82
 83&lt;SPAN TYPE="MARKUP"&gt;
 84    &lt;BEGIN&gt;[&lt;/BEGIN&gt;
 85    &lt;END&gt;]&lt;/END&gt;
 86&lt;/SPAN&gt;</pre></td></tr></table><p>
 87    Now, if the buffer contains the text &#8220;<span class="quote">[!SPECIAL]</span>&#8221;, the
 88    rules will be checked in order, and the first rule will be the first
 89    to match. However, if you write &#8220;<span class="quote">[FOO]</span>&#8221;, it will be highlighted
 90    using the second rule, which is exactly what you would expect.
 91   </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2628673"></a>Per-Ruleset Properties</h3></div></div><div></div></div><p>
 92    The <tt class="literal">PROPS</tt> tag (described in <a href="mode-tag-props.html" title="The PROPS Tag">the section called &#8220;The PROPS Tag&#8221;</a>)
 93    can also be placed inside the <tt class="literal">RULES</tt> tag to define
 94    ruleset-specific properties. The following properties can
 95    be set on a per-ruleset basis:
 96   </p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">commentEnd</tt> - the comment end
 97    string.
 98    </p></li><li><p><tt class="literal">commentStart</tt> - the comment start
 99    string.
100    </p></li><li><p><tt class="literal">lineComment</tt> - the line comment
101    string.
102    </p></li></ul></div><p>
103    This allows different parts of a file to have different comment strings
104    (in the case of HTML, for example, in HTML text and inline JavaScript).
105    For information about the commenting commands,
106    see <a href="commenting.html" title="Commenting Out Code">the section called &#8220;Commenting Out Code&#8221;</a>.
107   </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mode-tag-props.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="writing-modes.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="mode-rule-terminate.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">The PROPS Tag </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> The TERMINATE Tag</td></tr></table></div></body></html>