PageRenderTime 48ms CodeModel.GetById 16ms 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
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
  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. &lt;SPAN TYPE="KEYWORD1"&gt;
  67. &lt;BEGIN&gt;[!&lt;/BEGIN&gt;
  68. &lt;END&gt;]&lt;/END&gt;
  69. &lt;/SPAN&gt;</pre></td></tr></table><p>
  70. If you write the above in a rule set, any occurrence of &#8220;<span class="quote">[</span>&#8221;
  71. (even things like &#8220;<span class="quote">[!DEFINE</span>&#8221;, etc)
  72. will be highlighted using the first rule, because it will be the
  73. first to match. This is most likely not the intended behavior.
  74. </p><p>
  75. The problem can be solved by placing the more specific rule before the
  76. general one:
  77. </p><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting">&lt;SPAN TYPE="KEYWORD1"&gt;
  78. &lt;BEGIN&gt;[!&lt;/BEGIN&gt;
  79. &lt;END&gt;]&lt;/END&gt;
  80. &lt;/SPAN&gt;
  81. &lt;SPAN TYPE="MARKUP"&gt;
  82. &lt;BEGIN&gt;[&lt;/BEGIN&gt;
  83. &lt;END&gt;]&lt;/END&gt;
  84. &lt;/SPAN&gt;</pre></td></tr></table><p>
  85. Now, if the buffer contains the text &#8220;<span class="quote">[!SPECIAL]</span>&#8221;, the
  86. rules will be checked in order, and the first rule will be the first
  87. to match. However, if you write &#8220;<span class="quote">[FOO]</span>&#8221;, it will be highlighted
  88. using the second rule, which is exactly what you would expect.
  89. </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>
  90. 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>)
  91. can also be placed inside the <tt class="literal">RULES</tt> tag to define
  92. ruleset-specific properties. The following properties can
  93. be set on a per-ruleset basis:
  94. </p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">commentEnd</tt> - the comment end
  95. string.
  96. </p></li><li><p><tt class="literal">commentStart</tt> - the comment start
  97. string.
  98. </p></li><li><p><tt class="literal">lineComment</tt> - the line comment
  99. string.
  100. </p></li></ul></div><p>
  101. This allows different parts of a file to have different comment strings
  102. (in the case of HTML, for example, in HTML text and inline JavaScript).
  103. For information about the commenting commands,
  104. see <a href="commenting.html" title="Commenting Out Code">the section called &#8220;Commenting Out Code&#8221;</a>.
  105. </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>