/jEdit/tags/jedit-4-3-pre14/doc/users-guide/writing-modes.xml

# · XML · 910 lines · 895 code · 10 blank · 5 comment · 0 complexity · e699a133e6b102bf84adb486588096d3 MD5 · raw file 

    

  1. <?xml version="1.0" encoding="UTF-8"?>
    2. 

  2. <chapter id="writing-modes">
    3. 

  3.     <title>Mode Definition Syntax</title>
    4. 

  4.     <!-- jEdit buffer-local properties: -->
    5. 

  5.     <!-- :indentSize=1:noTabs=true: -->
    6. 

  6.     <!-- :xml.root=users-guide.xml: -->
    7. 

  7.     <para>Edit modes are defined using XML, the <firstterm>eXtensible Markup
    8. 

  8.     Language</firstterm>; mode files have the extension
    9. 

  9.     <filename>.xml</filename>. XML is a very simple language, and as a result
    10. 

  10.     edit modes are easy to create and modify. This section will start with a
    11. 

  11.     short XML primer, followed by detailed information about each supported tag
    12. 

  12.     and highlighting rule.</para>
    13. 

  13.     <para>Editing a mode or a mode catalog file within jEdit will cause the
    14. 

  14.     changes to take effect immediately. If you edit modes using another
    15. 

  15.     application, the changes will take effect after the
    16. 

  16.     <guimenu>Utilities</guimenu> &gt; <guisubmenu>Troubleshooting</guisubmenu>
    17. 

  17.     &gt; <guimenuitem>Reload Edit Modes</guimenuitem> command is invoked.</para>
    18. 

  18.     <sect1 id="xml-primer">
    19. 

  19.         <title>An XML Primer</title>
    20. 

  20.         <para>A very simple XML file (which also happens to be an edit mode)
    21. 

  21.         looks like so:</para>
    22. 

  22.         <programlisting>&lt;?xml version="1.0"?&gt;
    23. 

  23. 

  24. &lt;!DOCTYPE MODE SYSTEM "xmode.dtd"&gt;
    25. 

  25. 

  26. &lt;MODE&gt;
    27. 

  27.     &lt;PROPS&gt;
    28. 

  28.         &lt;PROPERTY NAME="commentStart" VALUE="/*" /&gt;
    29. 

  29.         &lt;PROPERTY NAME="commentEnd" VALUE="*/" /&gt;
    30. 

  30.     &lt;/PROPS&gt;
    31. 

  31. 

  32.     &lt;RULES&gt;
    33. 

  33.         &lt;SPAN TYPE="COMMENT1"&gt;
    34. 

  34.             &lt;BEGIN&gt;/*&lt;/BEGIN&gt;
    35. 

  35.             &lt;END&gt;*/&lt;/END&gt;
    36. 

  36.         &lt;/SPAN&gt;
    37. 

  37.     &lt;/RULES&gt;
    38. 

  38. &lt;/MODE&gt;</programlisting>
    39. 

  39.         <para>Note that each opening tag must have a corresponding closing tag.
    40. 

  40.         If there is nothing between the opening and closing tags, for example
    41. 

  41.         <literal>&lt;TAG&gt;&lt;/TAG&gt;</literal>, the shorthand notation
    42. 

  42.         <literal>&lt;TAG /&gt;</literal> may be used. An example of this
    43. 

  43.         shorthand can be seen in the <literal>&lt;PROPERTY&gt;</literal> tags
    44. 

  44.         above.</para>
    45. 

  45.         <para>XML is case sensitive. <literal>Span</literal> or
    46. 

  46.         <literal>span</literal> is not the same as
    47. 

  47.         <literal>SPAN</literal>.</para>
    48. 

  48.         <para>To insert a special character such as &lt; or &gt; literally in
    49. 

  49.         XML (for example, inside an attribute value), you must write it as an
    50. 

  50.         <firstterm>entity</firstterm>. An entity consists of the character's
    51. 

  51.         symbolic name enclosed within <quote>&amp;</quote> and <quote>;</quote>.
    52. 

  52.         The most frequently used entities are:</para>
    53. 

  53.         <itemizedlist>
    54. 

  54.             <listitem>
    55. 

  55.                 <para><literal>&amp;lt;</literal> - The less-than (&lt;)
    56. 

  56.                 character</para>
    57. 

  57.             </listitem>
    58. 

  58.             <listitem>
    59. 

  59.                 <para><literal>&amp;gt;</literal> - The greater-than (&gt;)
    60. 

  60.                 character</para>
    61. 

  61.             </listitem>
    62. 

  62.             <listitem>
    63. 

  63.                 <para><literal>&amp;amp;</literal> - The ampersand (&amp;)
    64. 

  64.                 character</para>
    65. 

  65.             </listitem>
    66. 

  66.         </itemizedlist>
    67. 

  67.         <para>For example, the following will cause a syntax error:</para>
    68. 

  68.         <programlisting>&lt;SEQ TYPE="OPERATOR"&gt;&amp;&lt;/SEQ&gt;</programlisting>
    69. 

  69.         <para>Instead, you must write:</para>
    70. 

  70.         <programlisting>&lt;SEQ TYPE="OPERATOR"&gt;&amp;amp;&lt;/SEQ&gt;</programlisting>
    71. 

  71.         <para>Now that the basics of XML have been covered, the rest of this
    72. 

  72.         section will cover each construct in detail.</para>
    73. 

  73.     </sect1>
    74. 

  74.     <sect1 id="mode-preamble">
    75. 

  75.         <title>The Preamble and MODE tag</title>
    76. 

  76.         <para>Each mode definition must begin with the following:</para>
    77. 

  77.         <programlisting>&lt;?xml version="1.0"?&gt;
    78. 

  78. &lt;!DOCTYPE MODE SYSTEM "xmode.dtd"&gt;</programlisting>
    79. 

  79.         <para>Each mode definition must also contain exactly one
    80. 

  80.         <literal>MODE</literal> tag. All other tags (<literal>PROPS</literal>,
    81. 

  81.         <literal>RULES</literal>) must be placed inside the
    82. 

  82.         <literal>MODE</literal> tag. The <literal>MODE</literal> tag does not
    83. 

  83.         have any defined attributes. Here is an example:</para>
    84. 

  84.         <programlisting>&lt;MODE&gt;
    85. 

  85.     <replaceable>... mode definition goes here ...</replaceable>
    86. 

  86. &lt;/MODE&gt;</programlisting>
    87. 

  87.     </sect1>
    88. 

  88.     <sect1 id="mode-tag-props">
    89. 

  89.         <title>The PROPS Tag</title>
    90. 

  90.         <para>The <literal>PROPS</literal> tag and the
    91. 

  91.         <literal>PROPERTY</literal> tags inside it are used to define
    92. 

  92.         mode-specific properties. Each <literal>PROPERTY</literal> tag must have
    93. 

  93.         a <literal>NAME</literal> attribute set to the property's name, and a
    94. 

  94.         <literal>VALUE</literal> attribute with the property's value.</para>
    95. 

  95.         <para>All buffer-local properties listed in <xref
    96. 

  96.         linkend="buffer-local" /> may be given values in edit modes.</para>
    97. 

  97.         <para>The following mode properties specify commenting strings:</para>
    98. 

  98.         <itemizedlist>
    99. 

  99.             <listitem>
    100. 

  100.                 <para><literal>commentEnd</literal> - the comment end string,
    101. 

  101.                 used by the <guimenuitem>Range Comment</guimenuitem>
    102. 

  102.                 command.</para>
    103. 

  103.             </listitem>
    104. 

  104.             <listitem>
    105. 

  105.                 <para><literal>commentStart</literal> - the comment start
    106. 

  106.                 string, used by the <guimenuitem>Range Comment</guimenuitem>
    107. 

  107.                 command.</para>
    108. 

  108.             </listitem>
    109. 

  109.             <listitem>
    110. 

  110.                 <para><literal>lineComment</literal> - the line comment string,
    111. 

  111.                 used by the <guimenuitem>Line Comment</guimenuitem>
    112. 

  112.                 command.</para>
    113. 

  113.             </listitem>
    114. 

  114.         </itemizedlist>
    115. 

  115.         <para>When performing auto indent, a number of mode properties determine
    116. 

  116.         the resulting indent level:</para>
    117. 

  117.         <itemizedlist>
    118. 

  118.             <listitem>
    119. 

  119.                 <para>The line and the one before it are scanned for brackets
    120. 

  120.                 listed in the <literal>indentCloseBrackets</literal> and
    121. 

  121.                 <literal>indentOpenBrackets</literal> properties. Opening
    122. 

  122.                 brackets in the previous line increase indent.</para>
    123. 

  123.                 <para>If <literal>lineUpClosingBracket</literal> is set to
    124. 

  124.                 <literal>true</literal>, then closing brackets on the current
    125. 

  125.                 line will line up with the line containing the matching opening
    126. 

  126.                 bracket. For example, in Java mode
    127. 

  127.                 <literal>lineUpClosingBracket</literal> is set to
    128. 

  128.                 <literal>true</literal>, resulting in brackets being indented
    129. 

  129.                 like so:</para>
    130. 

  130.                 <programlisting>{
    131. 

  131.     // Code
    132. 

  132.     {
    133. 

  133.         // More code
    134. 

  134.     }
    135. 

  135. }</programlisting>
    136. 

  136.                 <para>If <literal>lineUpClosingBracket</literal> is set to
    137. 

  137.                 <literal>false</literal>, the line <emphasis>after</emphasis> a
    138. 

  138.                 closing bracket will be lined up with the line containing the
    139. 

  139.                 matching opening bracket. For example, in Lisp mode
    140. 

  140.                 <literal>lineUpClosingBracket</literal> is set to
    141. 

  141.                 <literal>false</literal>, resulting in brackets being indented
    142. 

  142.                 like so:</para>
    143. 

  143.                 <programlisting>(foo 'a-parameter
    144. 

  144.     (crazy-p)
    145. 

  145.     (bar baz ()))
    146. 

  146. (print "hello world")</programlisting>
    147. 

  147.             </listitem>
    148. 

  148.             <listitem>
    149. 

  149.                 <para>If the previous line contains no opening brackets, or if
    150. 

  150.                 the <literal>doubleBracketIndent</literal> property is set to
    151. 

  151.                 <literal>true</literal>, the previous line is checked against
    152. 

  152.                 the regular expressions in the <literal>indentNextLine</literal>
    153. 

  153.                 and <literal>indentNextLines</literal> properties. If the
    154. 

  154.                 previous line matches the former, the indent of the current line
    155. 

  155.                 is increased and the subsequent line is shifted back again. If
    156. 

  156.                 the previous line matches the latter, the indent of the current
    157. 

  157.                 and subsequent lines is increased.</para>
    158. 

  158.                 <para>In Java mode, for example, the
    159. 

  159.                 <literal>indentNextLine</literal> property is set to match
    160. 

  160.                 control structures such as <quote>if</quote>,
    161. 

  161.                 <quote>else</quote>, <quote>while</quote>, and so on.</para>
    162. 

  162.                 <para>The <literal>doubleBracketIndent</literal> property, if
    163. 

  163.                 set to the default of <literal>false</literal>, results in code
    164. 

  164.                 indented like so:</para>
    165. 

  165.                 <programlisting>while(objects.hasNext())
    166. 

  166. {
    167. 

  167.     Object next = objects.hasNext();
    168. 

  168.     if(next instanceof Paintable)
    169. 

  169.         next.paint(g);
    170. 

  170. }</programlisting>
    171. 

  171.                 <para>On the other hand, settings this property to
    172. 

  172.                 <quote>true</quote> will give the following result:</para>
    173. 

  173.                 <programlisting>while(objects.hasNext())
    174. 

  174.     {
    175. 

  175.         Object next = objects.hasNext();
    176. 

  176.         if(next instanceof Paintable)
    177. 

  177.             next.paint(g);
    178. 

  178.     }</programlisting>
    179. 

  179.             </listitem>
    180. 

  180.         </itemizedlist>
    181. 

  181.         <para>Here is the complete <literal>&lt;PROPS&gt;</literal> tag for Java
    182. 

  182.         mode:</para>
    183. 

  183.         <programlisting>&lt;PROPS&gt;
    184. 

  184.     &lt;PROPERTY NAME="commentStart" VALUE="/*" /&gt;
    185. 

  185.     &lt;PROPERTY NAME="commentEnd" VALUE="*/" /&gt;
    186. 

  186.     &lt;PROPERTY NAME="lineComment" VALUE="//" /&gt;
    187. 

  187.     &lt;PROPERTY NAME="wordBreakChars" VALUE=",+-=&amp;lt;&amp;gt;/?^&amp;amp;*" /&gt;
    188. 

  188. 

  189.     &lt;!-- Auto indent --&gt;
    190. 

  190.     &lt;PROPERTY NAME="indentOpenBrackets" VALUE="{" /&gt;
    191. 

  191.     &lt;PROPERTY NAME="indentCloseBrackets" VALUE="}" /&gt;
    192. 

  192.     &lt;PROPERTY NAME="unalignedOpenBrackets" VALUE="(" /&gt;
    193. 

  193.     &lt;PROPERTY NAME="unalignedCloseBrackets" VALUE=")" /&gt;
    194. 

  194.     &lt;PROPERTY NAME="indentNextLine"
    195. 

  195.     	VALUE="\s*(((if|while)\s*\(|else\s*|else\s+if\s*\(|for\s*\(.*\))[^{;]*)" /&gt;
    196. 

  196.     &lt;PROPERTY NAME="unindentThisLine"
    197. 

  197.     	VALUE="^.*(default:\s*|case.*:.*)$" /&gt;
    198. 

  198.     &lt;PROPERTY NAME="electricKeys" VALUE=":" /&gt;
    199. 

  199.     &lt;!-- set this to 'true' if you want to use GNU coding style --&gt;
    200. 

  200.     &lt;PROPERTY NAME="doubleBracketIndent" VALUE="false" /&gt;
    201. 

  201.     &lt;PROPERTY NAME="lineUpClosingBracket" VALUE="true" /&gt;
    202. 

  202. &lt;/PROPS&gt;</programlisting>
    203. 

  203.     </sect1>
    204. 

  204.     <sect1 id="mode-tag-rules">
    205. 

  205.         <title>The RULES Tag</title>
    206. 

  206.         <para><literal>RULES</literal> tags must be placed inside the
    207. 

  207.         <literal>MODE</literal> tag. Each <literal>RULES</literal> tag defines a
    208. 

  208.         <firstterm>ruleset</firstterm>. A ruleset consists of a number of
    209. 

  209.         <firstterm>parser rules</firstterm>, with each parser rule specifying
    210. 

  210.         how to highlight a specific syntax token. There must be at least one
    211. 

  211.         ruleset in each edit mode. There can also be more than one, with
    212. 

  212.         different rulesets being used to highlight different parts of a buffer
    213. 

  213.         (for example, in HTML mode, one rule set highlights HTML tags, and
    214. 

  214.         another highlights inline JavaScript). For information about using more
    215. 

  215.         than one ruleset, see <xref linkend="mode-rule-span" />.</para>
    216. 

  216.         <para>The <literal>RULES</literal> tag supports the following
    217. 

  217.         attributes, all of which are optional:</para>
    218. 

  218.         <itemizedlist>
    219. 

  219.             <listitem>
    220. 

  220.                 <para><literal>SET</literal> - the name of this ruleset. All
    221. 

  221.                 rulesets other than the first must have a name.</para>
    222. 

  222.             </listitem>
    223. 

  223.             <listitem>
    224. 

  224.                 <para><literal>IGNORE_CASE</literal> - if set to
    225. 

  225.                 <literal>FALSE</literal>, matches will be case sensitive.
    226. 

  226.                 Otherwise, case will not matter. Default is
    227. 

  227.                 <literal>TRUE</literal>.</para>
    228. 

  228.             </listitem>
    229. 

  229.             <listitem>
    230. 

  230.                 <para><literal>ESCAPE</literal> - specifies a character sequence
    231. 

  231.                 for escaping literals. The first character following the escape
    232. 

  232.                 sequence is not considered as input for syntax highlighting,
    233. 

  233.                 thus being highlighted with default token for the rule set.
    234. 

  234.                 </para>
    235. 

  235.             </listitem>
    236. 

  236.             <listitem>
    237. 

  237.                 <para><literal>NO_WORD_SEP</literal> - any non-alphanumeric
    238. 

  238.                 character <emphasis>not</emphasis> in this list is treated as a
    239. 

  239.                 word separator for the purposes of syntax highlighting.</para>
    240. 

  240.             </listitem>
    241. 

  241.             <listitem>
    242. 

  242.                 <para><literal>DEFAULT</literal> - the token type for text which
    243. 

  243.                 doesn't match any specific rule. Default is
    244. 

  244.                 <literal>NULL</literal>. See <xref
    245. 

  245.                 linkend="mode-syntax-tokens" /> for a list of token
    246. 

  246.                 types.</para>
    247. 

  247.             </listitem>
    248. 

  248.             <listitem>
    249. 

  249.                 <para><literal>HIGHLIGHT_DIGITS</literal></para>
    250. 

  250.             </listitem>
    251. 

  251.             <listitem>
    252. 

  252.                 <para><literal>DIGIT_RE</literal> - see below for information
    253. 

  253.                 about these two attributes.</para>
    254. 

  254.             </listitem>
    255. 

  255.         </itemizedlist>
    256. 

  256.         <para>Here is an example <literal>RULES</literal> tag:</para>
    257. 

  257.         <programlisting>&lt;RULES IGNORE_CASE="FALSE" HIGHLIGHT_DIGITS="TRUE"&gt;
    258. 

  258.     <replaceable>... parser rules go here ...</replaceable>
    259. 

  259. &lt;/RULES&gt;</programlisting>
    260. 

  260.         <sect2>
    261. 

  261.             <title>Highlighting Numbers</title>
    262. 

  262.             <para>If the <literal>HIGHLIGHT_DIGITS</literal> attribute is set to
    263. 

  263.             <literal>TRUE</literal>, jEdit will attempt to highlight numbers in
    264. 

  264.             this ruleset.</para>
    265. 

  265.             <para>Any word consisting entirely of digits (0-9) will be
    266. 

  266.             highlighted with the <literal>DIGIT</literal> token type. A word
    267. 

  267.             that contains other letters in addition to digits will be
    268. 

  268.             highlighted with the <literal>DIGIT</literal> token type only if it
    269. 

  269.             matches the regular expression specified in the
    270. 

  270.             <literal>DIGIT_RE</literal> attribute. If this attribute is not
    271. 

  271.             specified, it will not be highlighted.</para>
    272. 

  272.             <para>Here is an example <literal>DIGIT_RE</literal> regular
    273. 

  273.             expression that highlights Java-style numeric literals (normal
    274. 

  274.             numbers, hexadecimals prefixed with <literal>0x</literal>, numbers
    275. 

  275.             suffixed with various type indicators, and floating point literals
    276. 

  276.             containing an exponent):</para>
    277. 

  277.             <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]))"</programlisting>
    278. 

  278.             <para>Regular expression syntax is described in <xref
    279. 

  279.             linkend="regexps" />.</para>
    280. 

  280.         </sect2>
    281. 

  281.         <sect2 id="rule-ordering">
    282. 

  282.             <title>Rule Ordering Requirements</title>
    283. 

  283.             <para>You might encounter this very common pitfall when writing your
    284. 

  284.             own modes.</para>
    285. 

  285.             <para>Since jEdit checks buffer text against parser rules in the
    286. 

  286.             order they appear in the ruleset, more specific rules must be placed
    287. 

  287.             before generalized ones, otherwise the generalized rules will catch
    288. 

  288.             everything.</para>
    289. 

  289.             <para>This is best demonstrated with an example. The following is
    290. 

  290.             incorrect rule ordering:</para>
    291. 

  291.             <programlisting>&lt;SPAN TYPE="MARKUP"&gt;
    292. 

  292.     &lt;BEGIN&gt;[&lt;/BEGIN&gt;
    293. 

  293.     &lt;END&gt;]&lt;/END&gt;
    294. 

  294. &lt;/SPAN&gt;
    295. 

  295. 

  296. &lt;SPAN TYPE="KEYWORD1"&gt;
    297. 

  297.     &lt;BEGIN&gt;[!&lt;/BEGIN&gt;
    298. 

  298.     &lt;END&gt;]&lt;/END&gt;
    299. 

  299. &lt;/SPAN&gt;</programlisting>
    300. 

  300.             <para>If you write the above in a rule set, any occurrence of
    301. 

  301.             <quote>[</quote> (even things like <quote>[!DEFINE</quote>, etc)
    302. 

  302.             will be highlighted using the first rule, because it will be the
    303. 

  303.             first to match. This is most likely not the intended
    304. 

  304.             behavior.</para>
    305. 

  305.             <para>The problem can be solved by placing the more specific rule
    306. 

  306.             before the general one:</para>
    307. 

  307.             <programlisting>&lt;SPAN TYPE="KEYWORD1"&gt;
    308. 

  308.     &lt;BEGIN&gt;[!&lt;/BEGIN&gt;
    309. 

  309.     &lt;END&gt;]&lt;/END&gt;
    310. 

  310. &lt;/SPAN&gt;
    311. 

  311. 

  312. &lt;SPAN TYPE="MARKUP"&gt;
    313. 

  313.     &lt;BEGIN&gt;[&lt;/BEGIN&gt;
    314. 

  314.     &lt;END&gt;]&lt;/END&gt;
    315. 

  315. &lt;/SPAN&gt;</programlisting>
    316. 

  316.             <para>Now, if the buffer contains the text
    317. 

  317.             <quote>[!SPECIAL]</quote>, the rules will be checked in order, and
    318. 

  318.             the first rule will be the first to match. However, if you write
    319. 

  319.             <quote>[FOO]</quote>, it will be highlighted using the second rule,
    320. 

  320.             which is exactly what you would expect.</para>
    321. 

  321.         </sect2>
    322. 

  322.         <sect2>
    323. 

  323.             <title>Per-Ruleset Properties</title>
    324. 

  324.             <para>The <literal>PROPS</literal> tag (described in <xref
    325. 

  325.             linkend="mode-tag-props" />) can also be placed inside the
    326. 

  326.             <literal>RULES</literal> tag to define ruleset-specific properties.
    327. 

  327.             The following properties can be set on a per-ruleset basis:</para>
    328. 

  328.             <itemizedlist>
    329. 

  329.                 <listitem>
    330. 

  330.                     <para><literal>commentEnd</literal> - the comment end
    331. 

  331.                     string.</para>
    332. 

  332.                 </listitem>
    333. 

  333.                 <listitem>
    334. 

  334.                     <para><literal>commentStart</literal> - the comment start
    335. 

  335.                     string.</para>
    336. 

  336.                 </listitem>
    337. 

  337.                 <listitem>
    338. 

  338.                     <para><literal>lineComment</literal> - the line comment
    339. 

  339.                     string.</para>
    340. 

  340.                 </listitem>
    341. 

  341.             </itemizedlist>
    342. 

  342.             <para>This allows different parts of a file to have different
    343. 

  343.             comment strings (in the case of HTML, for example, in HTML text and
    344. 

  344.             inline JavaScript). For information about the commenting commands,
    345. 

  345.             see <xref linkend="commenting" />.</para>
    346. 

  346.         </sect2>
    347. 

  347.     </sect1>
    348. 

  348.     <sect1 id="mode-rule-terminate">
    349. 

  349.         <title>The TERMINATE Tag</title>
    350. 

  350.         <para>The <literal>TERMINATE</literal> rule, which must be placed inside
    351. 

  351.         a <literal>RULES</literal> tag, specifies that parsing should stop after
    352. 

  352.         the specified number of characters have been read from a line. The
    353. 

  353.         number of characters to terminate after should be specified with the
    354. 

  354.         <literal>AT_CHAR</literal> attribute. Here is an example:</para>
    355. 

  355.         <programlisting>&lt;TERMINATE AT_CHAR="1" /&gt;</programlisting>
    356. 

  356.         <para>This rule is used in Patch mode, for example, because only the
    357. 

  357.         first character of each line affects highlighting.</para>
    358. 

  358.     </sect1>
    359. 

  359.     <sect1 id="mode-rule-span">
    360. 

  360.         <title>The SPAN Tag</title>
    361. 

  361.         <para>The <literal>SPAN</literal> rule, which must be placed inside a
    362. 

  362.         <literal>RULES</literal> tag, highlights text between a start and end
    363. 

  363.         string. The start and end strings are specified inside child elements of
    364. 

  364.         the <literal>SPAN</literal> tag. The following attributes are
    365. 

  365.         supported:</para>
    366. 

  366.         <itemizedlist>
    367. 

  367.             <listitem>
    368. 

  368.                 <para><literal>TYPE</literal> - The token type to highlight the
    369. 

  369.                 span with. See <xref linkend="mode-syntax-tokens" /> for a list
    370. 

  370.                 of token types.</para>
    371. 

  371.             </listitem>
    372. 

  372.             <listitem>
    373. 

  373.                 <para><literal>AT_LINE_START</literal> - If set to
    374. 

  374.                 <literal>TRUE</literal>, the span will only be highlighted if
    375. 

  375.                 the start sequence occurs at the beginning of a line.</para>
    376. 

  376.             </listitem>
    377. 

  377.             <listitem>
    378. 

  378.                 <para><literal>AT_WHITESPACE_END</literal> - If set to
    379. 

  379.                 <literal>TRUE</literal>, the span will only be highlighted if
    380. 

  380.                 the start sequence is the first non-whitespace text in the
    381. 

  381.                 line.</para>
    382. 

  382.             </listitem>
    383. 

  383.             <listitem>
    384. 

  384.                 <para><literal>AT_WORD_START</literal> - If set to
    385. 

  385.                 <literal>TRUE</literal>, the span will only be highlighted if
    386. 

  386.                 the start sequence occurs at the beginning of a word.</para>
    387. 

  387.             </listitem>
    388. 

  388.             <listitem>
    389. 

  389.                 <para><literal>DELEGATE</literal> - text inside the span will be
    390. 

  390.                 highlighted with the specified ruleset. To delegate to a ruleset
    391. 

  391.                 defined in the current mode, just specify its name. To delegate
    392. 

  392.                 to a ruleset defined in another mode, specify a name of the form
    393. 

  393.                 <literal><replaceable>mode</replaceable>::<replaceable>ruleset</replaceable></literal>.
    394. 

  394.                 Note that the first (unnamed) ruleset in a mode is called
    395. 

  395.                 <quote>MAIN</quote>.</para>
    396. 

  396.             </listitem>
    397. 

  397.             <listitem>
    398. 

  398.                 <para><literal>MATCH_TYPE</literal> - Controls how the start and
    399. 

  399.                 end of the sequence will be highlighted. See <xref
    400. 

  400.                 linkend="mode-match-type" /> for more information.</para>
    401. 

  401.             </listitem>
    402. 

  402.             <listitem>
    403. 

  403.                 <para><literal>ESCAPE</literal> - specifies a character sequence
    404. 

  404.                 for escaping characters. The first character following the escape
    405. 

  405.                 sequence is not considered as input for syntax highlighting,
    406. 

  406.                 thus being highlighted with rule's token.
    407. 

  407.                 </para>
    408. 

  408.             </listitem>
    409. 

  409.             <listitem>
    410. 

  410.                 <para><literal>NO_LINE_BREAK</literal> - If set to
    411. 

  411.                 <literal>TRUE</literal>, the span will not cross line
    412. 

  412.                 breaks.</para>
    413. 

  413.             </listitem>
    414. 

  414.             <listitem>
    415. 

  415.                 <para><literal>NO_WORD_BREAK</literal> - If set to
    416. 

  416.                 <literal>TRUE</literal>, the span will not cross word
    417. 

  417.                 breaks.</para>
    418. 

  418.             </listitem>
    419. 

  419.         </itemizedlist>
    420. 

  420.         <para>Note that the <literal>AT_LINE_START</literal>,
    421. 

  421.         <literal>AT_WHITESPACE_END</literal> and
    422. 

  422.         <literal>AT_WORD_START</literal> attributes can also be used on the
    423. 

  423.         <literal>BEGIN</literal> and <literal>END</literal> elements. Setting
    424. 

  424.         these attributes to the same value on both elements has the same effect
    425. 

  425.         as setting them on the <literal>SPAN</literal> element.</para>
    426. 

  426.         <para>Here is a <literal>SPAN</literal> that highlights Java string
    427. 

  427.         literals, which cannot include line breaks:</para>
    428. 

  428.         <programlisting>&lt;SPAN TYPE="LITERAL1" NO_LINE_BREAK="TRUE"&gt;
    429. 

  429.   &lt;BEGIN&gt;"&lt;/BEGIN&gt;
    430. 

  430.   &lt;END&gt;"&lt;/END&gt;
    431. 

  431. &lt;/SPAN&gt;</programlisting>
    432. 

  432.         <para>Here is a <literal>SPAN</literal> that highlights Java
    433. 

  433.         documentation comments by delegating to the <quote>JAVADOC</quote>
    434. 

  434.         ruleset defined elsewhere in the current mode:</para>
    435. 

  435.         <programlisting>&lt;SPAN TYPE="COMMENT2" DELEGATE="JAVADOC"&gt;
    436. 

  436.   &lt;BEGIN&gt;/**&lt;/BEGIN&gt;
    437. 

  437.   &lt;END&gt;*/&lt;/END&gt;
    438. 

  438. &lt;/SPAN&gt;</programlisting>
    439. 

  439.         <para>Here is a <literal>SPAN</literal> that highlights HTML cascading
    440. 

  440.         stylesheets inside <literal>&lt;STYLE&gt;</literal> tags by delegating
    441. 

  441.         to the main ruleset in the CSS edit mode:</para>
    442. 

  442.         <programlisting>&lt;SPAN TYPE="MARKUP" DELEGATE="css::MAIN"&gt;
    443. 

  443.   &lt;BEGIN&gt;&amp;lt;style&amp;gt;&lt;/BEGIN&gt;
    444. 

  444.   &lt;END&gt;&amp;lt;/style&amp;gt;&lt;/END&gt;
    445. 

  445. &lt;/SPAN&gt;</programlisting>
    446. 

  446.     </sect1>
    447. 

  447.     <sect1 id="mode-rule-span-regexp">
    448. 

  448.         <title>The SPAN_REGEXP Tag</title>
    449. 

  449.         <para>The <literal>SPAN_REGEXP</literal> rule is similar to the
    450. 

  450.         <literal>SPAN</literal> rule except the start sequence is taken to be a
    451. 

  451.         regular expression. In addition to the attributes supported by the
    452. 

  452.         <literal>SPAN</literal> tag, the following attributes are
    453. 

  453.         supported:</para>
    454. 

  454.         <itemizedlist>
    455. 

  455.             <listitem>
    456. 

  456.                 <para><literal>HASH_CHAR</literal> - a literal string which must
    457. 

  457.                 be at the start of a regular expression.</para>
    458. 

  458.             </listitem>
    459. 

  459.             <listitem>
    460. 

  460.                 <para><literal>HASH_CHARS</literal> - a list of possible literal
    461. 

  461.                 characters, one of which must match at the start of the regular
    462. 

  462.                 expression.</para>
    463. 

  463.             </listitem>
    464. 

  464.         </itemizedlist>
    465. 

  465.         <para><literal>HASH_CHAR</literal> and <literal>HASH_CHARS</literal>
    466. 

  466.         attributes are both optional, but you may only specify one, not both. If
    467. 

  467.         both are specified, <literal>HASH_CHARS</literal> is ignored and an
    468. 

  468.         error is shown. Whenever possible, use a literal prefix to specify a
    469. 

  469.         <literal>SPAN_REGEXP</literal>. If the starting prefix is always the
    470. 

  470.         same, use <literal>HASH_CHAR</literal> and provide as much prefix as
    471. 

  471.         possible. Only in rare cases would you omit both attributes, such as the
    472. 

  472.         case where there is no other reliable way to get the highlighting you
    473. 

  473.         need, for example, with comments in the Cobol programming
    474. 

  474.         language.</para>
    475. 

  475.         <para>The regular expression match cannot span more than one line. Any
    476. 

  476.         text matched by groups in the <literal>BEGIN</literal> regular
    477. 

  477.         expression is substituted in the <literal>END</literal> string. See
    478. 

  478.         below for an example of where this is useful.</para>
    479. 

  479.         <para>Regular expression syntax is described in <xref
    480. 

  480.         linkend="regexps" />.</para>
    481. 

  481.         <para>Here is a <literal>SPAN_REGEXP</literal> rule that highlights
    482. 

  482.         <quote>read-ins</quote> in shell scripts:</para>
    483. 

  483.         <programlisting>&lt;SPAN_REGEXP HASH_CHAR="&amp;lt;" TYPE="LITERAL1" DELEGATE="LITERAL"&gt;
    484. 

  484.     &lt;BEGIN&gt;&lt;![CDATA[&lt;&lt;[\p{Space}'"]*([\p{Alnum}_]+)[\p{Space}'"]*]]&gt;&lt;/BEGIN&gt;
    485. 

  485.     &lt;END&gt;$1&lt;/END&gt;
    486. 

  486. &lt;/SPAN_REGEXP&gt;</programlisting>
    487. 

  487.         <para>Here is a <literal>SPAN_REGEXP</literal> rule that highlights
    488. 

  488.         constructs placed between <literal>&lt;#ftl</literal> and
    489. 

  489.         <literal>&gt;</literal>, as long as the <literal>&lt;#ftl</literal> is
    490. 

  490.         followed by a word break:</para>
    491. 

  491.         <programlisting>&lt;SPAN_REGEXP TYPE="KEYWORD1" HASH_CHAR="&amp;lt;" DELEGATE="EXPRESSION"&gt;
    492. 

  492.     &lt;BEGIN&gt;&amp;lt;#ftl\b&lt;/BEGIN&gt;
    493. 

  493.     &lt;END&gt;&amp;gt;&lt;/END&gt;
    494. 

  494. &lt;/SPAN_REGEXP&gt;</programlisting>
    495. 

  495.     </sect1>
    496. 

  496.     <sect1 id="mode-rule-eol-span">
    497. 

  497.         <title>The EOL_SPAN Tag</title>
    498. 

  498.         <para>An <literal>EOL_SPAN</literal> is similar to a
    499. 

  499.         <literal>SPAN</literal> except that highlighting stops at the end of the
    500. 

  500.         line, and no end sequence needs to be specified. The text to match is
    501. 

  501.         specified between the opening and closing <literal>EOL_SPAN</literal>
    502. 

  502.         tags. The following attributes are supported:</para>
    503. 

  503.         <itemizedlist>
    504. 

  504.             <listitem>
    505. 

  505.                 <para><literal>TYPE</literal> - The token type to highlight the
    506. 

  506.                 span with. See <xref linkend="mode-syntax-tokens" /> for a list
    507. 

  507.                 of token types.</para>
    508. 

  508.             </listitem>
    509. 

  509.             <listitem>
    510. 

  510.                 <para><literal>AT_LINE_START</literal> - If set to
    511. 

  511.                 <literal>TRUE</literal>, the span will only be highlighted if
    512. 

  512.                 the start sequence occurs at the beginning of a line.</para>
    513. 

  513.             </listitem>
    514. 

  514.             <listitem>
    515. 

  515.                 <para><literal>AT_WHITESPACE_END</literal> - If set to
    516. 

  516.                 <literal>TRUE</literal>, the span will only be highlighted if
    517. 

  517.                 the sequence is the first non-whitespace text in the
    518. 

  518.                 line.</para>
    519. 

  519.             </listitem>
    520. 

  520.             <listitem>
    521. 

  521.                 <para><literal>AT_WORD_START</literal> - If set to
    522. 

  522.                 <literal>TRUE</literal>, the span will only be highlighted if
    523. 

  523.                 the start sequence occurs at the beginning of a word.</para>
    524. 

  524.             </listitem>
    525. 

  525.             <listitem>
    526. 

  526.                 <para><literal>DELEGATE</literal> - text inside the span will be
    527. 

  527.                 highlighted with the specified ruleset. To delegate to a ruleset
    528. 

  528.                 defined in the current mode, just specify its name. To delegate
    529. 

  529.                 to a ruleset defined in another mode, specify a name of the form
    530. 

  530.                 <literal><replaceable>mode</replaceable>::<replaceable>ruleset</replaceable></literal>.
    531. 

  531.                 Note that the first (unnamed) ruleset in a mode is called
    532. 

  532.                 <quote>MAIN</quote>.</para>
    533. 

  533.             </listitem>
    534. 

  534.             <listitem>
    535. 

  535.                 <para><literal>MATCH_TYPE</literal> - Controls how the start of
    536. 

  536.                 the sequence will be highlighted. See <xref
    537. 

  537.                 linkend="mode-match-type" /> for more information.</para>
    538. 

  538.             </listitem>
    539. 

  539.         </itemizedlist>
    540. 

  540.         <para>Here is an <literal>EOL_SPAN</literal> that highlights C++
    541. 

  541.         comments:</para>
    542. 

  542.         <programlisting>&lt;EOL_SPAN TYPE="COMMENT1"&gt;//&lt;/EOL_SPAN&gt;</programlisting>
    543. 

  543.     </sect1>
    544. 

  544.     <sect1 id="mode-rule-eol-span-regexp">
    545. 

  545.         <title>The EOL_SPAN_REGEXP Tag</title>
    546. 

  546.         <para>The <literal>EOL_SPAN_REGEXP</literal> rule is similar to the
    547. 

  547.         <literal>EOL_SPAN</literal> rule except the match sequence is taken to
    548. 

  548.         be a regular expression. In addition to the attributes supported by the
    549. 

  549.         <literal>EOL_SPAN</literal> tag, the following attributes are
    550. 

  550.         supported:</para>
    551. 

  551.         <itemizedlist>
    552. 

  552.             <listitem>
    553. 

  553.                 <para><literal>HASH_CHAR</literal> - a literal string which must
    554. 

  554.                 be at the start of a regular expression.</para>
    555. 

  555.             </listitem>
    556. 

  556.             <listitem>
    557. 

  557.                 <para><literal>HASH_CHARS</literal> - a list of possible literal
    558. 

  558.                 characters, one of which must match at the start of the regular
    559. 

  559.                 expression.</para>
    560. 

  560.             </listitem>
    561. 

  561.         </itemizedlist>
    562. 

  562.         <para><literal>HASH_CHAR</literal> and <literal>HASH_CHARS</literal>
    563. 

  563.         attributes are both optional, but you may only specify one, not both. If
    564. 

  564.         both are specified, <literal>HASH_CHARS</literal> is ignored and an
    565. 

  565.         error is shown. Whenever possible, use a literal prefix to specify a
    566. 

  566.         <literal>EOL_SPAN_REGEXP</literal>. If the starting prefix is always the
    567. 

  567.         same, use <literal>HASH_CHAR</literal> and provide as much prefix as
    568. 

  568.         possible. Only in rare cases would you omit both attributes, such as the
    569. 

  569.         case where there is no other reliable way to get the highlighting you
    570. 

  570.         need, for example, with comments in the Cobol programming
    571. 

  571.         language.</para>
    572. 

  572.         <para>The regular expression match cannot span more than one
    573. 

  573.         line.</para>
    574. 

  574.         <para>Regular expression syntax is described in <xref
    575. 

  575.         linkend="regexps" />.</para>
    576. 

  576.         <para>Here is an <literal>EOL_SPAN_REGEXP</literal> that highlights
    577. 

  577.         MS-DOS batch file comments, which start with <literal>REM</literal>,
    578. 

  578.         followed by any whitespace character, and extend until the end of the
    579. 

  579.         line:</para>
    580. 

  580.         <programlisting>&lt;EOL_SPAN_REGEXP AT_WHITESPACE_END="TRUE" HASH_CHAR="REM" TYPE="COMMENT1"&gt;REM\s&lt;/EOL_SPAN_REGEXP&gt;</programlisting>
    581. 

  581.     </sect1>
    582. 

  582.     <sect1 id="mode-rule-mark-prev">
    583. 

  583.         <title>The MARK_PREVIOUS Tag</title>
    584. 

  584.         <para>The <literal>MARK_PREVIOUS</literal> rule, which must be placed
    585. 

  585.         inside a <literal>RULES</literal> tag, highlights from the end of the
    586. 

  586.         previous syntax token to the matched text. The text to match is
    587. 

  587.         specified between opening and closing <literal>MARK_PREVIOUS</literal>
    588. 

  588.         tags. The following attributes are supported:</para>
    589. 

  589.         <itemizedlist>
    590. 

  590.             <listitem>
    591. 

  591.                 <para><literal>TYPE</literal> - The token type to highlight the
    592. 

  592.                 text with. See <xref linkend="mode-syntax-tokens" /> for a list
    593. 

  593.                 of token types.</para>
    594. 

  594.             </listitem>
    595. 

  595.             <listitem>
    596. 

  596.                 <para><literal>AT_LINE_START</literal> - If set to
    597. 

  597.                 <literal>TRUE</literal>, the sequence will only be highlighted
    598. 

  598.                 if it occurs at the beginning of a line.</para>
    599. 

  599.             </listitem>
    600. 

  600.             <listitem>
    601. 

  601.                 <para><literal>AT_WHITESPACE_END</literal> - If set to
    602. 

  602.                 <literal>TRUE</literal>, the sequence will only be highlighted
    603. 

  603.                 if it is the first non-whitespace text in the line.</para>
    604. 

  604.             </listitem>
    605. 

  605.             <listitem>
    606. 

  606.                 <para><literal>AT_WORD_START</literal> - If set to
    607. 

  607.                 <literal>TRUE</literal>, the sequence will only be highlighted
    608. 

  608.                 if it occurs at the beginning of a word.</para>
    609. 

  609.             </listitem>
    610. 

  610.             <listitem>
    611. 

  611.                 <para><literal>MATCH_TYPE</literal> - Controls how the matched
    612. 

  612.                 region will be highlighted. See <xref
    613. 

  613.                 linkend="mode-match-type" /> for more information.</para>
    614. 

  614.             </listitem>
    615. 

  615.         </itemizedlist>
    616. 

  616.         <para>Here is a rule that highlights labels in Java mode (for example,
    617. 

  617.         <quote>XXX:</quote>):</para>
    618. 

  618.         <programlisting>&lt;MARK_PREVIOUS AT_WHITESPACE_END="TRUE"
    619. 

  619.    MATCH_TYPE="DEFAULT"&gt;:&lt;/MARK_PREVIOUS&gt;</programlisting>
    620. 

  620.     </sect1>
    621. 

  621.     <sect1 id="mode-rule-mark-following">
    622. 

  622.         <title>The MARK_FOLLOWING Tag</title>
    623. 

  623.         <para>The <literal>MARK_FOLLOWING</literal> rule, which must be placed
    624. 

  624.         inside a <literal>RULES</literal> tag, highlights from the start of the
    625. 

  625.         match to the next syntax token. The text to match is specified between
    626. 

  626.         opening and closing <literal>MARK_FOLLOWING</literal> tags. The
    627. 

  627.         following attributes are supported:</para>
    628. 

  628.         <itemizedlist>
    629. 

  629.             <listitem>
    630. 

  630.                 <para><literal>TYPE</literal> - The token type to highlight the
    631. 

  631.                 text with. See <xref linkend="mode-syntax-tokens" /> for a list
    632. 

  632.                 of token types.</para>
    633. 

  633.             </listitem>
    634. 

  634.             <listitem>
    635. 

  635.                 <para><literal>AT_LINE_START</literal> - If set to
    636. 

  636.                 <literal>TRUE</literal>, the sequence will only be highlighted
    637. 

  637.                 if it occurs at the beginning of a line.</para>
    638. 

  638.             </listitem>
    639. 

  639.             <listitem>
    640. 

  640.                 <para><literal>AT_WHITESPACE_END</literal> - If set to
    641. 

  641.                 <literal>TRUE</literal>, the sequence will only be highlighted
    642. 

  642.                 if it is the first non-whitespace text in the line.</para>
    643. 

  643.             </listitem>
    644. 

  644.             <listitem>
    645. 

  645.                 <para><literal>AT_WORD_START</literal> - If set to
    646. 

  646.                 <literal>TRUE</literal>, the sequence will only be highlighted
    647. 

  647.                 if it occurs at the beginning of a word.</para>
    648. 

  648.             </listitem>
    649. 

  649.             <listitem>
    650. 

  650.                 <para><literal>MATCH_TYPE</literal> - Controls how the matched
    651. 

  651.                 region will be highlighted. See <xref
    652. 

  652.                 linkend="mode-match-type" /> for more information.</para>
    653. 

  653.             </listitem>
    654. 

  654.         </itemizedlist>
    655. 

  655.         <para>Here is a rule that highlights variables in Unix shell scripts
    656. 

  656.         (<quote>$CLASSPATH</quote>, <quote>$IFS</quote>, etc):</para>
    657. 

  657.         <programlisting>&lt;MARK_FOLLOWING TYPE="KEYWORD2"&gt;$&lt;/MARK_FOLLOWING&gt;</programlisting>
    658. 

  658.     </sect1>
    659. 

  659.     <sect1 id="mode-rule-seq">
    660. 

  660.         <title>The SEQ Tag</title>
    661. 

  661.         <para>The <literal>SEQ</literal> rule, which must be placed inside a
    662. 

  662.         <literal>RULES</literal> tag, highlights fixed sequences of text. The
    663. 

  663.         text to highlight is specified between opening and closing
    664. 

  664.         <literal>SEQ</literal> tags. The following attributes are
    665. 

  665.         supported:</para>
    666. 

  666.         <itemizedlist>
    667. 

  667.             <listitem>
    668. 

  668.                 <para><literal>TYPE</literal> - the token type to highlight the
    669. 

  669.                 sequence with. See <xref linkend="mode-syntax-tokens" /> for a
    670. 

  670.                 list of token types.</para>
    671. 

  671.             </listitem>
    672. 

  672.             <listitem>
    673. 

  673.                 <para><literal>AT_LINE_START</literal> - If set to
    674. 

  674.                 <literal>TRUE</literal>, the sequence will only be highlighted
    675. 

  675.                 if it occurs at the beginning of a line.</para>
    676. 

  676.             </listitem>
    677. 

  677.             <listitem>
    678. 

  678.                 <para><literal>AT_WHITESPACE_END</literal> - If set to
    679. 

  679.                 <literal>TRUE</literal>, the sequence will only be highlighted
    680. 

  680.                 if it is the first non-whitespace text in the line.</para>
    681. 

  681.             </listitem>
    682. 

  682.             <listitem>
    683. 

  683.                 <para><literal>AT_WORD_START</literal> - If set to
    684. 

  684.                 <literal>TRUE</literal>, the sequence will only be highlighted
    685. 

  685.                 if it occurs at the beginning of a word.</para>
    686. 

  686.             </listitem>
    687. 

  687.             <listitem>
    688. 

  688.                 <para><literal>DELEGATE</literal> - if this attribute is
    689. 

  689.                 specified, all text after the sequence will be highlighted using
    690. 

  690.                 this ruleset. To delegate to a ruleset defined in the current
    691. 

  691.                 mode, just specify its name. To delegate to a ruleset defined in
    692. 

  692.                 another mode, specify a name of the form
    693. 

  693.                 <literal><replaceable>mode</replaceable>::<replaceable>ruleset</replaceable></literal>.
    694. 

  694.                 Note that the first (unnamed) ruleset in a mode is called
    695. 

  695.                 <quote>MAIN</quote>.</para>
    696. 

  696.             </listitem>
    697. 

  697.         </itemizedlist>
    698. 

  698.         <para>The following rules highlight a few Java operators:</para>
    699. 

  699.         <programlisting>&lt;SEQ TYPE="OPERATOR"&gt;+&lt;/SEQ&gt;
    700. 

  700. &lt;SEQ TYPE="OPERATOR"&gt;-&lt;/SEQ&gt;
    701. 

  701. &lt;SEQ TYPE="OPERATOR"&gt;*&lt;/SEQ&gt;
    702. 

  702. &lt;SEQ TYPE="OPERATOR"&gt;/&lt;/SEQ&gt;</programlisting>
    703. 

  703.     </sect1>
    704. 

  704.     <sect1 id="mode-rule-seq-regexp">
    705. 

  705.         <title>The SEQ_REGEXP Tag</title>
    706. 

  706.         <para>The <literal>SEQ_REGEXP</literal> rule is similar to the
    707. 

  707.         <literal>SEQ</literal> rule except the match sequence is taken to be a
    708. 

  708.         regular expression. In addition to the attributes supported by the
    709. 

  709.         <literal>SEQ</literal> tag, the following attributes are
    710. 

  710.         supported:</para>
    711. 

  711.         <itemizedlist>
    712. 

  712.             <listitem>
    713. 

  713.                 <para><literal>HASH_CHAR</literal> - a literal string which must
    714. 

  714.                 be at the start of a regular expression.</para>
    715. 

  715.             </listitem>
    716. 

  716.             <listitem>
    717. 

  717.                 <para><literal>HASH_CHARS</literal> - a list of possible literal
    718. 

  718.                 characters, one of which must match at the start of the regular
    719. 

  719.                 expression.</para>
    720. 

  720.             </listitem>
    721. 

  721.         </itemizedlist>
    722. 

  722.         <para><literal>HASH_CHAR</literal> and <literal>HASH_CHARS</literal>
    723. 

  723.         attributes are both optional, but you may only specify one, not both. If
    724. 

  724.         both are specified, <literal>HASH_CHARS</literal> is ignored and an
    725. 

  725.         error is shown. Whenever possible, use a literal prefix to specify a
    726. 

  726.         <literal>SEQ_REGEXP</literal>. If the starting prefix is always the
    727. 

  727.         same, use <literal>HASH_CHAR</literal> and provide as much prefix as
    728. 

  728.         possible. Only in rare cases would you omit both attributes, such as the
    729. 

  729.         case where there is no other reliable way to get the highlighting you
    730. 

  730.         need, for example, with comments in the Cobol programming
    731. 

  731.         language.</para>
    732. 

  732.         <para>The regular expression match cannot span more than one
    733. 

  733.         line.</para>
    734. 

  734.         <para>Regular expression syntax is described in <xref
    735. 

  735.         linkend="regexps" />.</para>
    736. 

  736.         <para><emphasis role="bold">NOTE</emphasis>: c-style character escaping
    737. 

  737.         for literals (such as the tab char: \t) do not work as attribute values
    738. 

  738.         in XML. Use the XML character entity instead. For example: &amp;#09;
    739. 

  739.         instead of \t.</para>
    740. 

  740.         <para>Here is a <literal>SEQ_REGEXP</literal> rule from moin.xml that
    741. 

  741.         uses the <literal>HASH_CHARS</literal> attribute, to describe a keyword
    742. 

  742.         (wikiword) that can start with any uppercase letter and contain lower
    743. 

  743.         case letters and at least one uppercase letter in the middle.</para>
    744. 

  744.         <programlisting>
    745. 

  745.  		&lt;SEQ_REGEXP HASH_CHARS="ABCDEFGHIJKLMNOPQRSTUVWXYZ" AT_WORD_START="TRUE" TYPE="KEYWORD2"&gt;[A-Z][a-z]+[A-Z][a-zA-Z]+&lt;/SEQ_REGEXP&gt;
    746. 

  746.  </programlisting>
    747. 

  747.     </sect1>
    748. 

  748.     <sect1 id="mode-rule-import">
    749. 

  749.         <title>The IMPORT Tag</title>
    750. 

  750.         <para>The <literal>IMPORT</literal> tag, which must be placed inside a
    751. 

  751.         <literal>RULES</literal> tag, loads all rules defined in a given ruleset
    752. 

  752.         into the current ruleset; in other words, it has the same effect as
    753. 

  753.         copying and pasting the imported ruleset.</para>
    754. 

  754.         <para>The only required attribute <literal>DELEGATE</literal> must be
    755. 

  755.         set to the name of a ruleset. To import a ruleset defined in the current
    756. 

  756.         mode, just specify its name. To import a ruleset defined in another
    757. 

  757.         mode, specify a name of the form
    758. 

  758.         <literal><replaceable>mode</replaceable>::<replaceable>ruleset</replaceable></literal>.
    759. 

  759.         Note that the first (unnamed) ruleset in a mode is called
    760. 

  760.         <quote>MAIN</quote>.</para>
    761. 

  761.         <para>One quirk is that the definition of the imported ruleset is not
    762. 

  762.         copied to the location of the <literal>IMPORT</literal> tag, but rather
    763. 

  763.         to the end of the containing ruleset. This has implications with
    764. 

  764.         rule-ordering; see <xref linkend="rule-ordering" />.</para>
    765. 

  765.         <para>Here is an example from the PHP mode, which extends the inline
    766. 

  766.         JavaScript highlighting to support embedded PHP:</para>
    767. 

  767.         <programlisting>
    768. 

  768.    &lt;RULES SET="JAVASCRIPT+PHP"&gt;
    769. 

  769. 

  770.    &lt;SPAN TYPE="MARKUP" DELEGATE="php::PHP"&gt;
    771. 

  771.        &lt;BEGIN&gt;&amp;lt;?php&lt;/BEGIN&gt;
    772. 

  772.        &lt;END&gt;?&amp;gt;&lt;/END&gt;
    773. 

  773.    &lt;/SPAN&gt;
    774. 

  774. 

  775.    &lt;SPAN TYPE="MARKUP" DELEGATE="php::PHP"&gt;
    776. 

  776.        &lt;BEGIN&gt;&amp;lt;?&lt;/BEGIN&gt;
    777. 

  777.        &lt;END&gt;?&amp;gt;&lt;/END&gt;
    778. 

  778.    &lt;/SPAN&gt;
    779. 

  779. 

  780.    &lt;SPAN TYPE="MARKUP" DELEGATE="php::PHP"&gt;
    781. 

  781.        &lt;BEGIN&gt;&amp;lt;%=&lt;/BEGIN&gt;
    782. 

  782.        &lt;END&gt;%&amp;gt;&lt;/END&gt;
    783. 

  783.    &lt;/SPAN&gt;
    784. 

  784. 

  785.    &lt;IMPORT DELEGATE="javascript::MAIN"/&gt;
    786. 

  786. &lt;/RULES&gt;</programlisting>
    787. 

  787.     </sect1>
    788. 

  788.     <sect1 id="mode-rule-keywords">
    789. 

  789.         <title>The KEYWORDS Tag</title>
    790. 

  790.         <para>The <literal>KEYWORDS</literal> tag, which must be placed inside a
    791. 

  791.         <literal>RULES</literal> tag and can only appear once, specifies a list
    792. 

  792.         of keywords to highlight. Keywords are similar to
    793. 

  793.         <literal>SEQ</literal>s, except that <literal>SEQ</literal>s match
    794. 

  794.         anywhere in the text, whereas keywords only match whole words. Words are
    795. 

  795.         considered to be runs of text separated by non-alphanumeric
    796. 

  796.         characters.</para>
    797. 

  797.         <para>The <literal>KEYWORDS</literal> tag does not define any
    798. 

  798.         attributes.</para>
    799. 

  799.         <para>Each child element of the <literal>KEYWORDS</literal> tag is an
    800. 

  800.         element whose name is a token type, and whose content is the keyword to
    801. 

  801.         highlight. For example, the following rule highlights the most common
    802. 

  802.         Java keywords:</para>
    803. 

  803.         <programlisting>&lt;KEYWORDS&gt;
    804. 

  804.   &lt;KEYWORD1&gt;if&lt;/KEYWORD1&gt;
    805. 

  805.   &lt;KEYWORD1&gt;else&lt;/KEYWORD1&gt;
    806. 

  806.   &lt;KEYWORD3&gt;int&lt;/KEYWORD3&gt;
    807. 

  807.   &lt;KEYWORD3&gt;void&lt;/KEYWORD3&gt;
    808. 

  808. &lt;/KEYWORDS&gt;</programlisting>
    809. 

  809.     </sect1>
    810. 

  810.     <sect1 id="mode-syntax-tokens">
    811. 

  811.         <title>Token Types</title>
    812. 

  812.         <para>Parser rules can highlight tokens using any of the following token
    813. 

  813.         types:</para>
    814. 

  814.         <itemizedlist>
    815. 

  815.             <listitem>
    816. 

  816.                 <para><literal>NULL</literal> - no special highlighting is
    817. 

  817.                 performed on tokens of type <literal>NULL</literal></para>
    818. 

  818.             </listitem>
    819. 

  819.             <listitem>
    820. 

  820.                 <para><literal>COMMENT1</literal></para>
    821. 

  821.             </listitem>
    822. 

  822.             <listitem>
    823. 

  823.                 <para><literal>COMMENT2</literal></para>
    824. 

  824.             </listitem>
    825. 

  825.             <listitem>
    826. 

  826.                 <para><literal>COMMENT3</literal></para>
    827. 

  827.             </listitem>
    828. 

  828.             <listitem>
    829. 

  829.                 <para><literal>COMMENT4</literal></para>
    830. 

  830.             </listitem>
    831. 

  831.             <listitem>
    832. 

  832.                 <para><literal>FUNCTION</literal></para>
    833. 

  833.             </listitem>
    834. 

  834.             <listitem>
    835. 

  835.                 <para><literal>INVALID</literal><!--  - tokens of this type are
    836. 

  836.   automatically added if a <literal>NO_WORD_BREAK</literal> or
    837. 

  837.   <literal>NO_LINE_BREAK</literal> <literal>SPAN</literal> spans more than
    838. 

  838.   one word or line, respectively. --></para>
    839. 

  839.             </listitem>
    840. 

  840.             <listitem>
    841. 

  841.                 <para><literal>KEYWORD1</literal></para>
    842. 

  842.             </listitem>
    843. 

  843.             <listitem>
    844. 

  844.                 <para><literal>KEYWORD2</literal></para>
    845. 

  845.             </listitem>
    846. 

  846.             <listitem>
    847. 

  847.                 <para><literal>KEYWORD3</literal></para>
    848. 

  848.             </listitem>
    849. 

  849.             <listitem>
    850. 

  850.                 <para><literal>KEYWORD4</literal></para>
    851. 

  851.             </listitem>
    852. 

  852.             <listitem>
    853. 

  853.                 <para><literal>LABEL</literal></para>
    854. 

  854.             </listitem>
    855. 

  855.             <listitem>
    856. 

  856.                 <para><literal>LITERAL1</literal></para>
    857. 

  857.             </listitem>
    858. 

  858.             <listitem>
    859. 

  859.                 <para><literal>LITERAL2</literal></para>
    860. 

  860.             </listitem>
    861. 

  861.             <listitem>
    862. 

  862.                 <para><literal>LITERAL3</literal></para>
    863. 

  863.             </listitem>
    864. 

  864.             <listitem>
    865. 

  865.                 <para><literal>LITERAL4</literal></para>
    866. 

  866.             </listitem>
    867. 

  867.             <listitem>
    868. 

  868.                 <para><literal>MARKUP</literal></para>
    869. 

  869.             </listitem>
    870. 

  870.             <listitem>
    871. 

  871.                 <para><literal>OPERATOR</literal></para>
    872. 

  872.             </listitem>
    873. 

  873.         </itemizedlist>
    874. 

  874.     </sect1>
    875. 

  875.     <sect1 id="mode-match-type">
    876. 

  876.         <title>The MATCH_TYPE Attribute</title>
    877. 

  877.         <para>The <literal>MATCH_TYPE</literal> attribute is used by some of the
    878. 

  878.         rules to control how the region matched by the rule will be
    879. 

  879.         highlighted.</para>
    880. 

  880.         <para>For example, when using a <literal>MARK_PREVIOUS</literal> rule to
    881. 

  881.         highlight a function call of the form <literal>fcall()</literal>, the
    882. 

  882.         following rule could be used:</para>
    883. 

  883.         <programlisting>
    884. 

  884.    &lt;MARK_PREVIOUS TYPE="FUNCTION" MATCH_TYPE="OPERATOR"&gt;(&lt;/MARK_PREVIOUS&gt;</programlisting>
    885. 

  885.         <para>This would cause <literal>fcall</literal> to be highlighted as
    886. 

  886.         <literal>FUNCTION</literal>, and <literal>(</literal> to be highlighted
    887. 

  887.         as <literal>OPERATOR</literal>. In this case, to maintain bracket
    888. 

  888.         matching working, a <literal>SEQ</literal> rule would have to be added
    889. 

  889.         to match <literal>)</literal> and mark it as
    890. 

  890.         <literal>OPERATOR</literal>.</para>
    891. 

  891.         <para>The <literal>MATCH_TYPE</literal> attribute value can be any of
    892. 

  892.         the valid token types, or the following special values:</para>
    893. 

  893.         <itemizedlist>
    894. 

  894.             <listitem>
    895. 

  895.                 <para><literal>RULE</literal>: this is the default value. It
    896. 

  896.                 tells the syntax system to use the same token type as the TYPE
    897. 

  897.                 attribute of the rule. This is equivalent to
    898. 

  898.                 <literal>EXCLUDE_MATCH="FALSE"</literal> in 4.2 and earlier mode
    899. 

  899.                 files.</para>
    900. 

  900.             </listitem>
    901. 

  901.             <listitem>
    902. 

  902.                 <para><literal>CONTEXT</literal>: using this value tells the
    903. 

  903.                 syntax system to mark the matched region using the default token
    904. 

  904.                 type for the current rule set. In 4.2 and earlier mode files,
    905. 

  905.                 this was specified by
    906. 

  906.                 <literal>EXCLUDE_MATCH="TRUE"</literal>.</para>
    907. 

  907.             </listitem>
    908. 

  908.         </itemizedlist>
    909. 

  909.     </sect1>
    910. 

  910. </chapter>
    911.