PageRenderTime 181ms CodeModel.GetById 168ms app.highlight 8ms RepoModel.GetById 2ms app.codeStats 0ms

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

#
HTML | 77 lines | 75 code | 2 blank | 0 comment | 0 complexity | 48a761b139be17d885797394edb8d6dc 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.73.2"><link rel="start" href="index.html" title="jEdit 4.3 User's Guide"><link rel="up" href="writing-modes.html" title="Chapter 10. Mode Definition Syntax"><link rel="prev" 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><p><code class="literal">RULES</code> tags must be placed inside the
 2        <code class="literal">MODE</code> tag. Each <code class="literal">RULES</code> tag defines a
 3        <em class="firstterm">ruleset</em>. A ruleset consists of a number of
 4        <em class="firstterm">parser rules</em>, with each parser rule specifying
 5        how to highlight a specific syntax token. There must be at least one
 6        ruleset in each edit mode. There can also be more than one, with
 7        different rulesets being used to highlight different parts of a buffer
 8        (for example, in HTML mode, one rule set highlights HTML tags, and
 9        another highlights inline JavaScript). For information about using more
10        than one ruleset, see <a class="xref" href="mode-rule-span.html" title="The SPAN Tag">the section called &#8220;The SPAN Tag&#8221;</a>.</p><p>The <code class="literal">RULES</code> tag supports the following
11        attributes, all of which are optional:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">SET</code> - the name of this ruleset. All
12                rulesets other than the first must have a name.</p></li><li><p><code class="literal">IGNORE_CASE</code> - if set to
13                <code class="literal">FALSE</code>, matches will be case sensitive.
14                Otherwise, case will not matter. Default is
15                <code class="literal">TRUE</code>.</p></li><li><p><code class="literal">ESCAPE</code> - specifies a character sequence
16                for escaping literals. The first character following the escape
17                sequence is not considered as input for syntax highlighting,
18                thus being highlighted with default token for the rule set.
19                </p></li><li><p><code class="literal">NO_WORD_SEP</code> - any non-alphanumeric
20                character <span class="emphasis"><em>not</em></span> in this list is treated as a
21                word separator for the purposes of syntax highlighting.</p></li><li><p><code class="literal">DEFAULT</code> - the token type for text which
22                doesn't match any specific rule. Default is
23                <code class="literal">NULL</code>. See <a class="xref" href="mode-syntax-tokens.html" title="Token Types">the section called &#8220;Token Types&#8221;</a> for a list of token
24                types.</p></li><li><p><code class="literal">HIGHLIGHT_DIGITS</code></p></li><li><p><code class="literal">DIGIT_RE</code> - see below for information
25                about these two attributes.</p></li></ul></div><p>Here is an example <code class="literal">RULES</code> tag:</p><pre class="programlisting">&lt;RULES IGNORE_CASE="FALSE" HIGHLIGHT_DIGITS="TRUE"&gt;
26    <em class="replaceable"><code>... parser rules go here ...</code></em>
27&lt;/RULES&gt;</pre><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2585658"></a>Highlighting Numbers</h3></div></div></div><p>If the <code class="literal">HIGHLIGHT_DIGITS</code> attribute is set to
28            <code class="literal">TRUE</code>, jEdit will attempt to highlight numbers in
29            this ruleset.</p><p>Any word consisting entirely of digits (0-9) will be
30            highlighted with the <code class="literal">DIGIT</code> token type. A word
31            that contains other letters in addition to digits will be
32            highlighted with the <code class="literal">DIGIT</code> token type only if it
33            matches the regular expression specified in the
34            <code class="literal">DIGIT_RE</code> attribute. If this attribute is not
35            specified, it will not be highlighted.</p><p>Here is an example <code class="literal">DIGIT_RE</code> regular
36            expression that highlights Java-style numeric literals (normal
37            numbers, hexadecimals prefixed with <code class="literal">0x</code>, numbers
38            suffixed with various type indicators, and floating point literals
39            containing an exponent):</p><pre class="programlisting">DIGIT_RE="(0[lL]?|[1-9]\d{0,9}(\d{0,9}[lL])?|0[xX]\p{XDigit}{1,8}(\p{XDigit}{0,8}[lL])?|0[0-7]{1,11}([0-7]{0,11}[lL])?|([0-9]+\.[0-9]*|\.[0-9]+)([eE][+-]?[0-9]+)?[fFdD]?|[0-9]+([eE][+-]?[0-9]+[fFdD]?|([eE][+-]?[0-9]+)?[fFdD]))"</pre><p>Regular expression syntax is described in <a class="xref" href="regexps.html" title="Appendix E. Regular Expressions">Appendix E, <i>Regular Expressions</i></a>.</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><p>You might encounter this very common pitfall when writing your
40            own modes.</p><p>Since jEdit checks buffer text against parser rules in the
41            order they appear in the ruleset, more specific rules must be placed
42            before generalized ones, otherwise the generalized rules will catch
43            everything.</p><p>This is best demonstrated with an example. The following is
44            incorrect rule ordering:</p><pre class="programlisting">&lt;SPAN TYPE="MARKUP"&gt;
45    &lt;BEGIN&gt;[&lt;/BEGIN&gt;
46    &lt;END&gt;]&lt;/END&gt;
47&lt;/SPAN&gt;
48
49&lt;SPAN TYPE="KEYWORD1"&gt;
50    &lt;BEGIN&gt;[!&lt;/BEGIN&gt;
51    &lt;END&gt;]&lt;/END&gt;
52&lt;/SPAN&gt;</pre><p>If you write the above in a rule set, any occurrence of
53            &#8220;<span class="quote">[</span>&#8221; (even things like &#8220;<span class="quote">[!DEFINE</span>&#8221;, etc)
54            will be highlighted using the first rule, because it will be the
55            first to match. This is most likely not the intended
56            behavior.</p><p>The problem can be solved by placing the more specific rule
57            before the general one:</p><pre class="programlisting">&lt;SPAN TYPE="KEYWORD1"&gt;
58    &lt;BEGIN&gt;[!&lt;/BEGIN&gt;
59    &lt;END&gt;]&lt;/END&gt;
60&lt;/SPAN&gt;
61
62&lt;SPAN TYPE="MARKUP"&gt;
63    &lt;BEGIN&gt;[&lt;/BEGIN&gt;
64    &lt;END&gt;]&lt;/END&gt;
65&lt;/SPAN&gt;</pre><p>Now, if the buffer contains the text
66            &#8220;<span class="quote">[!SPECIAL]</span>&#8221;, the rules will be checked in order, and
67            the first rule will be the first to match. However, if you write
68            &#8220;<span class="quote">[FOO]</span>&#8221;, it will be highlighted using the second rule,
69            which is exactly what you would expect.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2585828"></a>Per-Ruleset Properties</h3></div></div></div><p>The <code class="literal">PROPS</code> tag (described in <a class="xref" href="mode-tag-props.html" title="The PROPS Tag">the section called &#8220;The PROPS Tag&#8221;</a>) can also be placed inside the
70            <code class="literal">RULES</code> tag to define ruleset-specific properties.
71            The following properties can be set on a per-ruleset basis:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">commentEnd</code> - the comment end
72                    string.</p></li><li><p><code class="literal">commentStart</code> - the comment start
73                    string.</p></li><li><p><code class="literal">lineComment</code> - the line comment
74                    string.</p></li></ul></div><p>This allows different parts of a file to have different
75            comment strings (in the case of HTML, for example, in HTML text and
76            inline JavaScript). For information about the commenting commands,
77            see <a class="xref" href="commenting.html" title="Commenting Out Code">the section called &#8220;Commenting Out Code&#8221;</a>.</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>