/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
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
- <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>
- <tt class="literal">RULES</tt> tags must be placed inside the
- <tt class="literal">MODE</tt> tag. Each <tt class="literal">RULES</tt> tag defines a
- <i class="firstterm">ruleset</i>. A ruleset consists of a number of
- <i class="firstterm">parser rules</i>, with each parser
- rule specifying how to highlight a specific syntax token. There must
- be at least one ruleset in each edit mode. There can also be more
- than one, with different rulesets being used to highlight different
- parts of a buffer (for example, in HTML mode, one rule set
- highlights HTML tags, and another highlights inline JavaScript).
- For information about using more
- than one ruleset, see <a href="mode-rule-span.html" title="The SPAN Tag">the section called “The SPAN Tag”</a>.
- </p><p>
- The <tt class="literal">RULES</tt> tag supports the following attributes, all of
- which are optional:
- </p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">SET</tt> - the name of this ruleset.
- All rulesets other than the first must have a name.
- </p></li><li><p><tt class="literal">IGNORE_CASE</tt> - if set to
- <tt class="literal">FALSE</tt>, matches will be case sensitive. Otherwise, case
- will not matter. Default is <tt class="literal">TRUE</tt>.
- </p></li><li><p><tt class="literal">NO_WORD_SEP</tt> - any non-alphanumeric
- character <span class="emphasis"><em>not</em></span> in this list is treated as a word separator
- for the purposes of syntax highlighting.
- </p></li><li><p><tt class="literal">DEFAULT</tt> - the token type for
- text which doesn't match
- any specific rule. Default is <tt class="literal">NULL</tt>. See
- <a href="mode-syntax-tokens.html" title="Token Types">the section called “Token Types”</a> for a list of token types.
- </p></li><li><p><tt class="literal">HIGHLIGHT_DIGITS</tt>
- </p></li><li><p><tt class="literal">DIGIT_RE</tt> - see below for information
- about these two attributes.</p></li></ul></div><p>
- Here is an example <tt class="literal">RULES</tt> tag:
- </p><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting"><RULES IGNORE_CASE="FALSE" HIGHLIGHT_DIGITS="TRUE">
- <i class="replaceable"><tt>... parser rules go here ...</tt></i>
- </RULES></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>
- If the <tt class="literal">HIGHLIGHT_DIGITS</tt> attribute is set to
- <tt class="literal">TRUE</tt>, jEdit will attempt to highlight numbers in this
- ruleset.
- </p><p>
- Any word consisting entirely of digits (0-9) will be highlighted with the
- <tt class="literal">DIGIT</tt> token type.
- A word that contains other letters in addition to digits will be
- highlighted with the
- <tt class="literal">DIGIT</tt> token type only if it matches the regular
- expression specified in the <tt class="literal">DIGIT_RE</tt> attribute.
- If this attribute is not specified, it will not be highlighted.
- </p><p>
- Here is an example <tt class="literal">DIGIT_RE</tt> regular expression that highlights
- Java-style numeric literals (normal numbers, hexadecimals
- prefixed with <tt class="literal">0x</tt>, numbers suffixed with various
- type indicators, and floating point literals containing an exponent):
- </p><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting">DIGIT_RE="(0x[[:xdigit:]]+|[[:digit:]]+(e[[:digit:]]*)?)[lLdDfF]?"</pre></td></tr></table><p>
- Regular expression syntax is described in <a 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></div></div><p>
- You might encounter this very common pitfall when writing your own modes.
- </p><p>
- Since jEdit checks buffer text against parser rules in the order they appear
- in the ruleset, more specific rules must be placed before generalized ones,
- otherwise the generalized rules will catch everything.
- </p><p>
- This is best demonstrated with an example. The following is incorrect rule
- ordering:
- </p><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting"><SPAN TYPE="MARKUP">
- <BEGIN>[</BEGIN>
- <END>]</END>
- </SPAN>
- <SPAN TYPE="KEYWORD1">
- <BEGIN>[!</BEGIN>
- <END>]</END>
- </SPAN></pre></td></tr></table><p>
- If you write the above in a rule set, any occurrence of “<span class="quote">[</span>”
- (even things like “<span class="quote">[!DEFINE</span>”, etc)
- will be highlighted using the first rule, because it will be the
- first to match. This is most likely not the intended behavior.
- </p><p>
- The problem can be solved by placing the more specific rule before the
- general one:
- </p><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting"><SPAN TYPE="KEYWORD1">
- <BEGIN>[!</BEGIN>
- <END>]</END>
- </SPAN>
- <SPAN TYPE="MARKUP">
- <BEGIN>[</BEGIN>
- <END>]</END>
- </SPAN></pre></td></tr></table><p>
- Now, if the buffer contains the text “<span class="quote">[!SPECIAL]</span>”, the
- rules will be checked in order, and the first rule will be the first
- to match. However, if you write “<span class="quote">[FOO]</span>”, it will be highlighted
- using the second rule, which is exactly what you would expect.
- </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>
- The <tt class="literal">PROPS</tt> tag (described in <a href="mode-tag-props.html" title="The PROPS Tag">the section called “The PROPS Tag”</a>)
- can also be placed inside the <tt class="literal">RULES</tt> tag to define
- ruleset-specific properties. The following properties can
- be set on a per-ruleset basis:
- </p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">commentEnd</tt> - the comment end
- string.
- </p></li><li><p><tt class="literal">commentStart</tt> - the comment start
- string.
- </p></li><li><p><tt class="literal">lineComment</tt> - the line comment
- string.
- </p></li></ul></div><p>
- This allows different parts of a file to have different comment strings
- (in the case of HTML, for example, in HTML text and inline JavaScript).
- For information about the commenting commands,
- see <a href="commenting.html" title="Commenting Out Code">the section called “Commenting Out Code”</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>