PageRenderTime 41ms CodeModel.GetById 1ms RepoModel.GetById 0ms app.codeStats 0ms

/jEdit/tags/jedit-4-2-pre4/doc/users-guide/writing-modes.xml

#
XML | 746 lines | 728 code | 10 blank | 8 comment | 0 complexity | 9449d6c0fb69592849fdb4d22ed189de 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. <!-- jEdit buffer-local properties: -->
  2. <!-- :indentSize=1:noTabs=true: -->
  3. <!-- :xml.root=users-guide.xml: -->
  4. <chapter id="writing-modes"><title>Mode Definition Syntax</title>
  5. <para>
  6. Edit modes are defined using XML, the <firstterm>extensible markup
  7. language</firstterm>; mode files have the extension
  8. <filename>.xml</filename>. XML is a very simple language, and as a result
  9. edit modes are easy to create and modify. This section will
  10. start with a short XML primer, followed by detailed information about
  11. each supported tag and highlighting rule.
  12. </para>
  13. <para>
  14. Editing a mode or a mode catalog file within jEdit will cause the
  15. changes to take effect immediately. If you edit modes using another
  16. application, the changes will take effect after the
  17. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Reload Edit Modes</guimenuitem>
  18. command is invoked.
  19. </para>
  20. <sect1 id="xml-primer"><title>An XML Primer</title>
  21. <para>
  22. A very simple XML file (which also happens to be an edit mode) looks like so:
  23. </para>
  24. <programlisting><![CDATA[<?xml version="1.0"?>
  25. <!DOCTYPE MODE SYSTEM "xmode.dtd">
  26. <MODE>
  27. <PROPS>
  28. <PROPERTY NAME="commentStart" VALUE="/*" />
  29. <PROPERTY NAME="commentEnd" VALUE="*/" />
  30. </PROPS>
  31. <RULES>
  32. <SPAN TYPE="COMMENT1">
  33. <BEGIN>/*</BEGIN>
  34. <END>*/</END>
  35. </SPAN>
  36. </RULES>
  37. </MODE>]]></programlisting>
  38. <para>
  39. Note that each opening tag must have a corresponding closing tag.
  40. If there is nothing between the opening and closing tags, for example
  41. <literal>&lt;TAG&gt;&lt;/TAG&gt;</literal>, the shorthand notation
  42. <literal>&lt;TAG /&gt;</literal> may be used. An example of this shorthand
  43. can be seen
  44. in the <literal>&lt;PROPERTY&gt;</literal> tags above.
  45. </para>
  46. <para>
  47. XML is case sensitive. <literal>Span</literal> or <literal>span</literal>
  48. is not the same as <literal>SPAN</literal>.
  49. </para>
  50. <para>
  51. To insert a special character such as &lt; or &gt; literally in XML
  52. (for example, inside an attribute value), you must write it as
  53. an <firstterm>entity</firstterm>. An
  54. entity consists of the character's symbolic name enclosed with
  55. <quote>&amp;</quote> and <quote>;</quote>. The most frequently used entities
  56. are:
  57. </para>
  58. <itemizedlist>
  59. <listitem><para><literal>&amp;lt;</literal> - The less-than (&lt;)
  60. character</para></listitem>
  61. <listitem><para><literal>&amp;gt;</literal> - The greater-than (&gt;)
  62. character</para></listitem>
  63. <listitem><para><literal>&amp;amp;</literal> - The ampersand (&amp;)
  64. character</para></listitem>
  65. </itemizedlist>
  66. <para>
  67. For example, the following will cause a syntax error:
  68. </para>
  69. <programlisting>&lt;SEQ TYPE="OPERATOR"&gt;&amp;&lt;/SEQ&gt;</programlisting>
  70. <para>
  71. Instead, you must write:
  72. </para>
  73. <programlisting>&lt;SEQ TYPE="OPERATOR"&gt;&amp;amp;&lt;/SEQ&gt;</programlisting>
  74. <para>
  75. Now that the basics of XML have been covered, the rest of this
  76. section will cover each construct in detail.
  77. </para>
  78. </sect1>
  79. <sect1 id="mode-preamble"><title>The Preamble and MODE tag</title>
  80. <para>
  81. Each mode definition must begin with the following:
  82. </para>
  83. <programlisting>&lt;?xml version="1.0"?&gt;
  84. &lt;!DOCTYPE MODE SYSTEM "xmode.dtd"&gt;</programlisting>
  85. <para>
  86. Each mode definition must also contain exactly one <literal>MODE</literal>
  87. tag. All other tags (<literal>PROPS</literal>, <literal>RULES</literal>)
  88. must be placed inside the <literal>MODE</literal> tag. The
  89. <literal>MODE</literal> tag does not have any defined attributes.
  90. Here is an example:
  91. </para>
  92. <programlisting><![CDATA[<MODE>]]>
  93. <replaceable>... mode definition goes here ...</replaceable>
  94. <![CDATA[</MODE>]]></programlisting>
  95. </sect1>
  96. <sect1 id="mode-tag-props"><title>The PROPS Tag</title>
  97. <para>
  98. The <literal>PROPS</literal> tag and the <literal>PROPERTY</literal> tags
  99. inside it are used to define mode-specific
  100. properties. Each <literal>PROPERTY</literal> tag must have a
  101. <literal>NAME</literal> attribute set to the property's name, and a
  102. <literal>VALUE</literal> attribute with the property's value.
  103. </para>
  104. <para>
  105. All buffer-local properties listed in <xref linkend="buffer-local" />
  106. may be given values in edit modes.
  107. </para>
  108. <para>
  109. The following mode properties specify commenting strings:
  110. </para>
  111. <itemizedlist>
  112. <listitem><para><literal>commentEnd</literal> - the comment end
  113. string, used by the <guimenuitem>Range Comment</guimenuitem> command.
  114. </para></listitem>
  115. <listitem><para><literal>commentStart</literal> - the comment start
  116. string, used by the <guimenuitem>Range Comment</guimenuitem> command.
  117. </para></listitem>
  118. <listitem><para><literal>lineComment</literal> - the line comment
  119. string, used by the <guimenuitem>Line Comment</guimenuitem> command.
  120. </para></listitem>
  121. </itemizedlist>
  122. <para>
  123. When performing auto indent, a number of mode properties determine the
  124. resulting indent level:
  125. </para>
  126. <itemizedlist>
  127. <listitem><para>The line and the one before it are scanned for brackets
  128. listed in the <literal>indentCloseBrackets</literal> and
  129. <literal>indentOpenBrackets</literal> properties.
  130. Opening brackets in the previous line increase indent.
  131. </para>
  132. <para>
  133. If <literal>lineUpClosingBracket</literal> is set to <literal>true</literal>,
  134. then closing brackets on the current line will line up with
  135. the line containing the matching opening bracket. For example, in Java mode
  136. <literal>lineUpClosingBracket</literal> is set to <literal>true</literal>,
  137. resulting in brackets being indented like so:
  138. </para>
  139. <programlisting>{
  140. // Code
  141. {
  142. // More code
  143. }
  144. }</programlisting>
  145. <para>
  146. If <literal>lineUpClosingBracket</literal> is set to <literal>false</literal>,
  147. the line <emphasis>after</emphasis> a closing bracket will be lined up with
  148. the line containing the matching opening bracket. For example, in Lisp mode
  149. <literal>lineUpClosingBracket</literal> is set to <literal>false</literal>,
  150. resulting in brackets being indented like so:
  151. </para>
  152. <programlisting>(foo 'a-parameter
  153. (crazy-p)
  154. (bar baz ()))
  155. (print "hello world")</programlisting>
  156. </listitem>
  157. <listitem>
  158. <para>If the previous line contains no opening brackets, or if the
  159. <literal>doubleBracketIndent</literal> property is set to <literal>true</literal>,
  160. the previous line is checked against the regular expressions in the
  161. <literal>indentNextLine</literal> and <literal>indentNextLines</literal>
  162. properties. If the previous line matches the former, the indent of the
  163. current line is increased and the subsequent line is shifted back again.
  164. If the previous line matches the latter, the indent of the current
  165. and subsequent lines is increased.
  166. </para>
  167. <para>
  168. In Java mode, for example, the <literal>indentNextLine</literal>
  169. property is set to match control structures such as <quote>if</quote>,
  170. <quote>else</quote>, <quote>while</quote>, and so on.
  171. </para>
  172. <para>
  173. The
  174. <literal>doubleBracketIndent</literal> property, if set to the default of
  175. <literal>false</literal>, results in code indented like so:
  176. </para>
  177. <programlisting>while(objects.hasNext())
  178. {
  179. Object next = objects.hasNext();
  180. if(next instanceof Paintable)
  181. next.paint(g);
  182. }</programlisting>
  183. <para>
  184. On the other hand, settings this property to <quote>true</quote> will
  185. give the following result:
  186. </para>
  187. <programlisting>while(objects.hasNext())
  188. {
  189. Object next = objects.hasNext();
  190. if(next instanceof Paintable)
  191. next.paint(g);
  192. }</programlisting></listitem>
  193. </itemizedlist>
  194. <para>
  195. Here is the complete <literal>&lt;PROPS&gt;</literal> tag for Java mode:
  196. </para>
  197. <programlisting><![CDATA[<PROPS>
  198. <PROPERTY NAME="commentStart" VALUE="/*" />
  199. <PROPERTY NAME="commentEnd" VALUE="*/" />
  200. <PROPERTY NAME="lineComment" VALUE="//" />
  201. <PROPERTY NAME="wordBreakChars" VALUE=",+-=&lt;&gt;/?^&amp;*" />
  202. <!-- Auto indent -->
  203. <PROPERTY NAME="indentOpenBrackets" VALUE="{" />
  204. <PROPERTY NAME="indentCloseBrackets" VALUE="}" />
  205. <PROPERTY NAME="indentNextLine"
  206. VALUE="\s*(((if|while)\s*\(|else\s*|else\s+if\s*\(|for\s*\(.*\))[^{;]*)" />
  207. <!-- set this to 'true' if you want to use GNU coding style -->
  208. <PROPERTY NAME="doubleBracketIndent" VALUE="false" />
  209. <PROPERTY NAME="lineUpClosingBracket" VALUE="true" />
  210. </PROPS>]]></programlisting>
  211. </sect1>
  212. <sect1 id="mode-tag-rules"><title>The RULES Tag</title>
  213. <para>
  214. <literal>RULES</literal> tags must be placed inside the
  215. <literal>MODE</literal> tag. Each <literal>RULES</literal> tag defines a
  216. <firstterm>ruleset</firstterm>. A ruleset consists of a number of
  217. <firstterm>parser rules</firstterm>, with each parser
  218. rule specifying how to highlight a specific syntax token. There must
  219. be at least one ruleset in each edit mode. There can also be more
  220. than one, with different rulesets being used to highlight different
  221. parts of a buffer (for example, in HTML mode, one rule set
  222. highlights HTML tags, and another highlights inline JavaScript).
  223. For information about using more
  224. than one ruleset, see <xref linkend="mode-rule-span" />.
  225. </para>
  226. <para>
  227. The <literal>RULES</literal> tag supports the following attributes, all of
  228. which are optional:
  229. </para>
  230. <itemizedlist>
  231. <listitem><para><literal>SET</literal> - the name of this ruleset.
  232. All rulesets other than the first must have a name.
  233. </para></listitem>
  234. <listitem><para><literal>IGNORE_CASE</literal> - if set to
  235. <literal>FALSE</literal>, matches will be case sensitive. Otherwise, case
  236. will not matter. Default is <literal>TRUE</literal>.
  237. </para></listitem>
  238. <listitem><para><literal>NO_WORD_SEP</literal> - any non-alphanumeric
  239. character <emphasis>not</emphasis> in this list is treated as a word separator
  240. for the purposes of syntax highlighting.
  241. </para></listitem>
  242. <listitem><para><literal>DEFAULT</literal> - the token type for
  243. text which doesn't match
  244. any specific rule. Default is <literal>NULL</literal>. See
  245. <xref linkend="mode-syntax-tokens" /> for a list of token types.
  246. </para></listitem>
  247. <listitem><para><literal>HIGHLIGHT_DIGITS</literal>
  248. </para></listitem>
  249. <listitem><para><literal>DIGIT_RE</literal> - see below for information
  250. about these two attributes.</para></listitem>
  251. </itemizedlist>
  252. <para>
  253. Here is an example <literal>RULES</literal> tag:
  254. </para>
  255. <programlisting>&lt;RULES IGNORE_CASE="FALSE" HIGHLIGHT_DIGITS="TRUE"&gt;
  256. <replaceable>... parser rules go here ...</replaceable>
  257. &lt;/RULES&gt;</programlisting>
  258. <sect2><title>Highlighting Numbers</title>
  259. <para>
  260. If the <literal>HIGHLIGHT_DIGITS</literal> attribute is set to
  261. <literal>TRUE</literal>, jEdit will attempt to highlight numbers in this
  262. ruleset.
  263. </para>
  264. <para>
  265. Any word consisting entirely of digits (0-9) will be highlighted with the
  266. <literal>DIGIT</literal> token type.
  267. A word that contains other letters in addition to digits will be
  268. highlighted with the
  269. <literal>DIGIT</literal> token type only if it matches the regular
  270. expression specified in the <literal>DIGIT_RE</literal> attribute.
  271. If this attribute is not specified, it will not be highlighted.
  272. </para>
  273. <para>
  274. Here is an example <literal>DIGIT_RE</literal> regular expression that highlights
  275. Java-style numeric literals (normal numbers, hexadecimals
  276. prefixed with <literal>0x</literal>, numbers suffixed with various
  277. type indicators, and floating point literals containing an exponent):
  278. </para>
  279. <programlisting>DIGIT_RE="(0x[[:xdigit:]]+|[[:digit:]]+(e[[:digit:]]*)?)[lLdDfF]?"</programlisting>
  280. <para>
  281. Regular expression syntax is described in <xref linkend="regexps" />.
  282. </para>
  283. </sect2>
  284. <sect2><title>Rule Ordering Requirements</title>
  285. <para>
  286. You might encounter this very common pitfall when writing your own modes.
  287. </para>
  288. <para>
  289. Since jEdit checks buffer text against parser rules in the order they appear
  290. in the ruleset, more specific rules must be placed before generalized ones,
  291. otherwise the generalized rules will catch everything.
  292. </para>
  293. <para>
  294. This is best demonstrated with an example. The following is incorrect rule
  295. ordering:
  296. </para>
  297. <programlisting><![CDATA[<SPAN TYPE="MARKUP">
  298. <BEGIN>[</BEGIN>
  299. <END>]</END>
  300. </SPAN>
  301. <SPAN TYPE="KEYWORD1">
  302. <BEGIN>[!</BEGIN>
  303. <END>]</END>
  304. </SPAN>]]></programlisting>
  305. <para>
  306. If you write the above in a rule set, any occurrence of <quote>[</quote>
  307. (even things like <quote>[!DEFINE</quote>, etc)
  308. will be highlighted using the first rule, because it will be the
  309. first to match. This is most likely not the intended behavior.
  310. </para>
  311. <para>
  312. The problem can be solved by placing the more specific rule before the
  313. general one:
  314. </para>
  315. <programlisting><![CDATA[<SPAN TYPE="KEYWORD1">
  316. <BEGIN>[!</BEGIN>
  317. <END>]</END>
  318. </SPAN>
  319. <SPAN TYPE="MARKUP">
  320. <BEGIN>[</BEGIN>
  321. <END>]</END>
  322. </SPAN>]]></programlisting>
  323. <para>
  324. Now, if the buffer contains the text <quote>[!SPECIAL]</quote>, the
  325. rules will be checked in order, and the first rule will be the first
  326. to match. However, if you write <quote>[FOO]</quote>, it will be highlighted
  327. using the second rule, which is exactly what you would expect.
  328. </para>
  329. </sect2>
  330. <sect2><title>Per-Ruleset Properties</title>
  331. <para>
  332. The <literal>PROPS</literal> tag (described in <xref linkend="mode-tag-props"/>)
  333. can also be placed inside the <literal>RULES</literal> tag to define
  334. ruleset-specific properties. The following properties can
  335. be set on a per-ruleset basis:
  336. </para>
  337. <itemizedlist>
  338. <listitem><para><literal>commentEnd</literal> - the comment end
  339. string.
  340. </para></listitem>
  341. <listitem><para><literal>commentStart</literal> - the comment start
  342. string.
  343. </para></listitem>
  344. <listitem><para><literal>lineComment</literal> - the line comment
  345. string.
  346. </para></listitem>
  347. </itemizedlist>
  348. <para>
  349. This allows different parts of a file to have different comment strings
  350. (in the case of HTML, for example, in HTML text and inline JavaScript).
  351. For information about the commenting commands,
  352. see <xref linkend="commenting"/>.
  353. </para>
  354. </sect2>
  355. </sect1>
  356. <sect1 id="mode-rule-terminate"><title>The TERMINATE Tag</title>
  357. <para>
  358. The <literal>TERMINATE</literal> rule, which must be placed inside a
  359. <literal>RULES</literal> tag, specifies that parsing should stop
  360. after the specified number of characters have been read from a line. The
  361. number of characters to terminate after should be specified with the
  362. <literal>AT_CHAR</literal> attribute. Here is an example:
  363. </para>
  364. <programlisting>&lt;TERMINATE AT_CHAR="1" /&gt;</programlisting>
  365. <para>
  366. This rule is used in Patch mode, for example, because only the first
  367. character of each line affects highlighting.
  368. </para>
  369. </sect1>
  370. <sect1 id="mode-rule-span"><title>The SPAN Tag</title>
  371. <para>
  372. The <literal>SPAN</literal> rule, which must be placed inside a
  373. <literal>RULES</literal> tag, highlights text between a start
  374. and end string. The start and end strings are specified inside
  375. child elements of the <literal>SPAN</literal> tag.
  376. The following attributes are supported:
  377. </para>
  378. <itemizedlist>
  379. <listitem><para><literal>TYPE</literal> - The token type to highlight the
  380. span with. See <xref linkend="mode-syntax-tokens" /> for a list of token
  381. types.</para></listitem>
  382. <listitem><para><literal>AT_LINE_START</literal> - If set to
  383. <literal>TRUE</literal>, the span will only be highlighted if the start
  384. sequence occurs at the beginning of a line.</para></listitem>
  385. <listitem><para><literal>AT_WHITESPACE_END</literal> - If set to
  386. <literal>TRUE</literal>, the span will only be highlighted if the
  387. start sequence is the first non-whitespace text in the line.</para>
  388. </listitem>
  389. <listitem><para><literal>AT_WORD_START</literal> - If set to
  390. <literal>TRUE</literal>, the span will only be highlighted if the start
  391. sequence occurs at the beginning of a word.</para></listitem>
  392. <listitem><para><literal>DELEGATE</literal> - text inside the span will be
  393. highlighted with the specified ruleset. To delegate to a ruleset defined
  394. in the current mode, just specify its name. To delegate to a ruleset
  395. defined in another mode, specify a name of the form
  396. <literal><replaceable>mode</replaceable>::<replaceable>ruleset</replaceable></literal>.
  397. Note that the first (unnamed) ruleset in a mode is called
  398. <quote>MAIN</quote>.</para></listitem>
  399. <listitem><para><literal>EXCLUDE_MATCH</literal> - If set to
  400. <literal>TRUE</literal>, the start and end sequences will not be highlighted,
  401. only the text between them will.</para></listitem>
  402. <listitem><para><literal>NO_ESCAPE</literal> - If set to
  403. <literal>TRUE</literal>, the ruleset's escape character will have no
  404. effect before the span's end string. Otherwise, the presence of the escape
  405. character will cause that occurrence of the end string to be ignored.</para></listitem>
  406. <listitem><para><literal>NO_LINE_BREAK</literal> - If set to
  407. <literal>TRUE</literal>, the span will not cross line breaks.</para></listitem>
  408. <listitem><para><literal>NO_WORD_BREAK</literal> - If set to
  409. <literal>TRUE</literal>, the span will not cross word breaks.</para></listitem>
  410. </itemizedlist>
  411. <para>
  412. Note that the <literal>AT_LINE_START</literal>,
  413. <literal>AT_WHITESPACE_END</literal> and
  414. <literal>AT_WORD_START</literal> attributes can also be used on the
  415. <literal>BEGIN</literal> and <literal>END</literal> elements. Setting these
  416. attributes to the same value on both elements has the same effect as
  417. setting them on the <literal>SPAN</literal> element.
  418. </para>
  419. <para>
  420. Here is a <literal>SPAN</literal> that highlights Java string literals,
  421. which cannot include line breaks:
  422. </para>
  423. <programlisting>&lt;SPAN TYPE="LITERAL1" NO_LINE_BREAK="TRUE"&gt;
  424. &lt;BEGIN&gt;"&lt;/BEGIN&gt;
  425. &lt;END&gt;"&lt;/END&gt;
  426. &lt;/SPAN&gt;</programlisting>
  427. <para>
  428. Here is a <literal>SPAN</literal> that highlights Java documentation
  429. comments by delegating to the <quote>JAVADOC</quote> ruleset defined
  430. elsewhere in the current mode:
  431. </para>
  432. <programlisting>&lt;SPAN TYPE="COMMENT2" DELEGATE="JAVADOC"&gt;
  433. &lt;BEGIN&gt;/**&lt;/BEGIN&gt;
  434. &lt;END&gt;*/&lt;/END&gt;
  435. &lt;/SPAN&gt;</programlisting>
  436. <para>
  437. Here is a <literal>SPAN</literal> that highlights HTML cascading stylesheets
  438. inside <literal>&lt;STYLE&gt;</literal> tags by delegating to the main
  439. ruleset in the CSS edit mode:
  440. </para>
  441. <programlisting>&lt;SPAN TYPE="MARKUP" DELEGATE="css::MAIN"&gt;
  442. &lt;BEGIN&gt;&amp;lt;style&amp;gt;&lt;/BEGIN&gt;
  443. &lt;END&gt;&amp;lt;/style&amp;gt;&lt;/END&gt;
  444. &lt;/SPAN&gt;</programlisting>
  445. </sect1>
  446. <sect1 id="mode-rule-span-regexp"><title>The SPAN_REGEXP Tag</title>
  447. <para>
  448. The <literal>SPAN_REGEXP</literal> rule is similar to the
  449. <literal>SPAN</literal> rule except the start sequence is taken to be
  450. a regular expression. In addition to the attributes supported by
  451. the <literal>SPAN</literal> tag, the
  452. <literal>HASH_CHAR</literal> attribute must be specified. It must be set to
  453. the first character that
  454. the regular expression matches. Note that this disallows regular expressions
  455. which can match more than one character at the start position.
  456. </para>
  457. <para>
  458. Any text matched by groups in the <literal>BEGIN</literal> regular
  459. expression is substituted in the <literal>END</literal> string. See
  460. below for an example of where this is useful.
  461. </para>
  462. <para>
  463. Regular expression syntax is described in <xref linkend="regexps" />.
  464. </para>
  465. <para>
  466. Here is a <literal>SPAN_REGEXP</literal> rule that highlights
  467. <quote>read-ins</quote> in shell scripts:
  468. </para>
  469. <programlisting>&lt;SPAN_REGEXP HASH_CHAR="&lt;" TYPE="LITERAL1" DELEGATE="LITERAL"&gt;
  470. &lt;BEGIN&gt;&lt;![CDATA[&lt;&lt;[[:space:]'"]*([[:alnum:]_]+)[[:space:]'"]*]]&gt;&lt;/BEGIN&gt;
  471. &lt;END&gt;$1&lt;/END&gt;
  472. &lt;/SPAN_REGEXP&gt;</programlisting>
  473. <para>
  474. Here is a <literal>SPAN_REGEXP</literal> rule that highlights constructs
  475. placed between <literal>&lt;#ftl</literal> and <literal>&gt;</literal>,
  476. as long as the <literal>&lt;#ftl</literal> is followed by a word break:
  477. </para>
  478. <programlisting><![CDATA[<SPAN_REGEXP TYPE="KEYWORD1" HASH_CHAR="&lt;" DELEGATE="EXPRESSION">
  479. <BEGIN>&lt;#ftl\&gt;</BEGIN>
  480. <END>&gt;</END>
  481. </SPAN_REGEXP>]]></programlisting>
  482. </sect1>
  483. <sect1 id="mode-rule-eol-span"><title>The EOL_SPAN Tag</title>
  484. <para>
  485. An <literal>EOL_SPAN</literal> is similar to a <literal>SPAN</literal>
  486. except that highlighting stops at the end of the line, and no end sequence
  487. needs to be specified. The text to match is specified between the opening and
  488. closing <literal>EOL_SPAN</literal> tags.
  489. The following attributes are supported:
  490. </para>
  491. <itemizedlist>
  492. <listitem><para><literal>TYPE</literal> - The token type to highlight the
  493. span with. See <xref linkend="mode-syntax-tokens" /> for a list of token
  494. types.</para></listitem>
  495. <listitem><para><literal>AT_LINE_START</literal> - If set to
  496. <literal>TRUE</literal>, the span will only be highlighted if the start
  497. sequence occurs at the beginning of a line.</para></listitem>
  498. <listitem><para><literal>AT_WHITESPACE_END</literal> - If set to
  499. <literal>TRUE</literal>, the span will only be highlighted if the
  500. sequence is the first non-whitespace text in the line.</para>
  501. </listitem>
  502. <listitem><para><literal>AT_WORD_START</literal> - If set to
  503. <literal>TRUE</literal>, the span will only be highlighted if the start
  504. sequence occurs at the beginning of a word.</para></listitem>
  505. <listitem><para><literal>DELEGATE</literal> - text inside the span will be
  506. highlighted with the specified ruleset. To delegate to a ruleset defined
  507. in the current mode, just specify its name. To delegate to a ruleset
  508. defined in another mode, specify a name of the form
  509. <literal><replaceable>mode</replaceable>::<replaceable>ruleset</replaceable></literal>.
  510. Note that the first (unnamed) ruleset in a mode is called
  511. <quote>MAIN</quote>.</para></listitem>
  512. <listitem><para><literal>EXCLUDE_MATCH</literal> - If set to
  513. <literal>TRUE</literal>, the start and end sequences will not be highlighted,
  514. only the text between them will.</para></listitem>
  515. </itemizedlist>
  516. <para>
  517. Here is an <literal>EOL_SPAN</literal> that highlights C++ comments:
  518. </para>
  519. <programlisting>&lt;EOL_SPAN TYPE="COMMENT1"&gt;//&lt;/EOL_SPAN&gt;</programlisting>
  520. </sect1>
  521. <sect1 id="mode-rule-eol-span-regexp"><title>The EOL_SPAN_REGEXP Tag</title>
  522. <para>
  523. The <literal>EOL_SPAN_REGEXP</literal> rule is similar to the
  524. <literal>EOL_SPAN</literal> rule except the match sequence is taken to be
  525. a regular expression. In addition to the attributes supported by
  526. the <literal>EOL_SPAN</literal> tag, the
  527. <literal>HASH_CHAR</literal> attribute must be specified. It must be set to
  528. the first character that
  529. the regular expression matches. Note that this disallows regular expressions
  530. which can match more than one character at the start position.
  531. </para>
  532. <para>
  533. Regular expression syntax is described in <xref linkend="regexps" />.
  534. </para>
  535. </sect1>
  536. <sect1 id="mode-rule-mark-prev"><title>The MARK_PREVIOUS Tag</title>
  537. <para>
  538. The <literal>MARK_PREVIOUS</literal> rule, which must be placed inside a
  539. <literal>RULES</literal> tag, highlights from the end of the
  540. previous syntax token to the matched text. The text to match
  541. is specified between opening and closing <literal>MARK_PREVIOUS</literal>
  542. tags. The following attributes are supported:
  543. </para>
  544. <itemizedlist>
  545. <listitem><para><literal>TYPE</literal> - The token type to highlight the
  546. text with. See <xref linkend="mode-syntax-tokens" /> for a list of token
  547. types.</para></listitem>
  548. <listitem><para><literal>AT_LINE_START</literal> - If set to
  549. <literal>TRUE</literal>, the sequence will only be highlighted if it occurs
  550. at the beginning of a line.</para></listitem>
  551. <listitem><para><literal>AT_WHITESPACE_END</literal> - If set to
  552. <literal>TRUE</literal>, the sequence will only be highlighted if it is
  553. the first non-whitespace text in the line.</para>
  554. </listitem>
  555. <listitem><para><literal>AT_WORD_START</literal> - If set to
  556. <literal>TRUE</literal>, the sequence will only be highlighted if
  557. it occurs at the beginning of a word.</para></listitem>
  558. <listitem><para><literal>EXCLUDE_MATCH</literal> - If set to
  559. <literal>TRUE</literal>, the match will not be highlighted,
  560. only the text before it will.</para></listitem>
  561. </itemizedlist>
  562. <para>
  563. Here is a rule that highlights labels in Java mode (for example,
  564. <quote>XXX:</quote>):
  565. </para>
  566. <programlisting>&lt;MARK_PREVIOUS AT_WHITESPACE_END="TRUE"
  567. EXCLUDE_MATCH="TRUE"&gt;:&lt;/MARK_PREVIOUS&gt;</programlisting>
  568. </sect1>
  569. <sect1 id="mode-rule-mark-following"><title>The MARK_FOLLOWING Tag</title>
  570. <para>
  571. The <literal>MARK_FOLLOWING</literal> rule, which must be placed inside a
  572. <literal>RULES</literal> tag, highlights from the start of the
  573. match to the next syntax token. The text to match
  574. is specified between opening and closing <literal>MARK_FOLLOWING</literal>
  575. tags. The following attributes are supported:
  576. </para>
  577. <itemizedlist>
  578. <listitem><para><literal>TYPE</literal> - The token type to highlight the
  579. text with. See <xref linkend="mode-syntax-tokens" /> for a list of token
  580. types.</para></listitem>
  581. <listitem><para><literal>AT_LINE_START</literal> - If set to
  582. <literal>TRUE</literal>, the sequence will only be highlighted if it occurs
  583. at the beginning of a line.</para></listitem>
  584. <listitem><para><literal>AT_WHITESPACE_END</literal> - If set to
  585. <literal>TRUE</literal>, the sequence will only be highlighted if it is
  586. the first non-whitespace text in the line.</para>
  587. </listitem>
  588. <listitem><para><literal>AT_WORD_START</literal> - If set to
  589. <literal>TRUE</literal>, the sequence will only be highlighted if
  590. it occurs at the beginning of a word.</para></listitem>
  591. <listitem><para><literal>EXCLUDE_MATCH</literal> - If set to
  592. <literal>TRUE</literal>, the match will not be highlighted,
  593. only the text after it will.</para></listitem>
  594. </itemizedlist>
  595. <para>
  596. Here is a rule that highlights variables in Unix shell scripts
  597. (<quote>$CLASSPATH</quote>, <quote>$IFS</quote>, etc):
  598. </para>
  599. <programlisting>&lt;MARK_FOLLOWING TYPE="KEYWORD2"&gt;$&lt;/MARK_FOLLOWING&gt;</programlisting>
  600. </sect1>
  601. <sect1 id="mode-rule-seq"><title>The SEQ Tag</title>
  602. <para>
  603. The <literal>SEQ</literal> rule, which must be placed inside a
  604. <literal>RULES</literal> tag, highlights fixed sequences of text. The text
  605. to highlight is specified between opening and closing <literal>SEQ</literal>
  606. tags. The following attributes are supported:
  607. </para>
  608. <itemizedlist>
  609. <listitem><para><literal>TYPE</literal> - the token type to highlight the
  610. sequence with. See <xref linkend="mode-syntax-tokens" /> for a list of token
  611. types.</para></listitem>
  612. <listitem><para><literal>AT_LINE_START</literal> - If set to
  613. <literal>TRUE</literal>, the sequence will only be highlighted if it occurs
  614. at the beginning of a line.</para></listitem>
  615. <listitem><para><literal>AT_WHITESPACE_END</literal> - If set to
  616. <literal>TRUE</literal>, the sequence will only be highlighted if it is
  617. the first non-whitespace text in the line.</para>
  618. </listitem>
  619. <listitem><para><literal>AT_WORD_START</literal> - If set to
  620. <literal>TRUE</literal>, the sequence will only be highlighted if
  621. it occurs at the beginning of a word.</para></listitem>
  622. <listitem><para><literal>DELEGATE</literal> - if this attribute is specified,
  623. all text after the sequence will be highlighted using this ruleset.
  624. To delegate to a ruleset defined
  625. in the current mode, just specify its name. To delegate to a ruleset
  626. defined in another mode, specify a name of the form
  627. <literal><replaceable>mode</replaceable>::<replaceable>ruleset</replaceable></literal>.
  628. Note that the first (unnamed) ruleset in a mode is called
  629. <quote>MAIN</quote>.</para></listitem>
  630. </itemizedlist>
  631. <para>
  632. The following rules highlight a few Java operators:
  633. </para>
  634. <programlisting>&lt;SEQ TYPE="OPERATOR"&gt;+&lt;/SEQ&gt;
  635. &lt;SEQ TYPE="OPERATOR"&gt;-&lt;/SEQ&gt;
  636. &lt;SEQ TYPE="OPERATOR"&gt;*&lt;/SEQ&gt;
  637. &lt;SEQ TYPE="OPERATOR"&gt;/&lt;/SEQ&gt;</programlisting>
  638. </sect1>
  639. <sect1 id="mode-rule-seq-regexp"><title>The SEQ_REGEXP Tag</title>
  640. <para>
  641. The <literal>SEQ_REGEXP</literal> rule is similar to the
  642. <literal>SEQ</literal> rule except the match sequence is taken to be
  643. a regular expression. In addition to the attributes supported by
  644. the <literal>SEQ</literal> tag, the
  645. <literal>HASH_CHAR</literal> attribute must be specified. It must be set to
  646. the first character that
  647. the regular expression matches. Note that this disallows regular expressions
  648. which can match more than one character at the start position.
  649. </para>
  650. <para>
  651. Here is an example of a <literal>SEQ_REGEXP</literal> rule that highlights
  652. Perl's matcher constructions such as <literal>m/(.+):(\d+):(.+)/</literal>:
  653. </para>
  654. <programlisting><![CDATA[<SEQ_REGEXP TYPE="MARKUP"
  655. HASH_CHAR="m"
  656. AT_WORD_START="TRUE"
  657. >m([[:punct:]])(?:.*?[^\\])*?\1[sgiexom]*</SEQ_REGEXP>]]></programlisting>
  658. <para>
  659. Regular expression syntax is described in <xref linkend="regexps" />.
  660. </para>
  661. </sect1>
  662. <sect1 id="mode-rule-keywords"><title>The KEYWORDS Tag</title>
  663. <para>
  664. The <literal>KEYWORDS</literal> tag, which must be placed inside a
  665. <literal>RULES</literal> tag and can only appear once, specifies a list of
  666. keywords to highlight.
  667. Keywords are similar to <literal>SEQ</literal>s, except that
  668. <literal>SEQ</literal>s match anywhere in the text, whereas keywords only
  669. match whole words. Words are considered to be runs of text separated by
  670. non-alphanumeric characters.
  671. </para>
  672. <para>
  673. The <literal>KEYWORDS</literal> tag does not define any attributes.
  674. </para>
  675. <para>
  676. Each child element of the <literal>KEYWORDS</literal> tag is an element
  677. whose name is a token type, and whose content is the keyword to
  678. highlight. For example, the following rule highlights the most common Java
  679. keywords:
  680. </para>
  681. <programlisting>&lt;KEYWORDS&gt;
  682. &lt;KEYWORD1&gt;if&lt;/KEYWORD1&gt;
  683. &lt;KEYWORD1&gt;else&lt;/KEYWORD1&gt;
  684. &lt;KEYWORD3&gt;int&lt;/KEYWORD3&gt;
  685. &lt;KEYWORD3&gt;void&lt;/KEYWORD3&gt;
  686. &lt;/KEYWORDS&gt;</programlisting>
  687. </sect1>
  688. <sect1 id="mode-syntax-tokens"><title>Token Types</title>
  689. <para>
  690. Parser rules can highlight tokens using any of the following token
  691. types:
  692. </para>
  693. <itemizedlist>
  694. <listitem><para><literal>NULL</literal> - no special
  695. highlighting is performed on tokens of type <literal>NULL</literal>
  696. </para></listitem>
  697. <listitem><para><literal>COMMENT1</literal>
  698. </para></listitem>
  699. <listitem><para><literal>COMMENT2</literal>
  700. </para></listitem>
  701. <listitem><para><literal>COMMENT3</literal>
  702. </para></listitem>
  703. <listitem><para><literal>COMMENT4</literal>
  704. </para></listitem>
  705. <listitem><para><literal>FUNCTION</literal>
  706. </para></listitem>
  707. <listitem><para><literal>INVALID</literal><!-- - tokens of this type are
  708. automatically added if a <literal>NO_WORD_BREAK</literal> or
  709. <literal>NO_LINE_BREAK</literal> <literal>SPAN</literal> spans more than
  710. one word or line, respectively. -->
  711. </para></listitem>
  712. <listitem><para><literal>KEYWORD1</literal>
  713. </para></listitem>
  714. <listitem><para><literal>KEYWORD2</literal>
  715. </para></listitem>
  716. <listitem><para><literal>KEYWORD3</literal>
  717. </para></listitem>
  718. <listitem><para><literal>KEYWORD4</literal>
  719. </para></listitem>
  720. <listitem><para><literal>LABEL</literal>
  721. </para></listitem>
  722. <listitem><para><literal>LITERAL1</literal>
  723. </para></listitem>
  724. <listitem><para><literal>LITERAL2</literal>
  725. </para></listitem>
  726. <listitem><para><literal>LITERAL3</literal>
  727. </para></listitem>
  728. <listitem><para><literal>LITERAL4</literal>
  729. </para></listitem>
  730. <listitem><para><literal>MARKUP</literal>
  731. </para></listitem>
  732. <listitem><para><literal>OPERATOR</literal>
  733. </para></listitem>
  734. </itemizedlist>
  735. </sect1>
  736. </chapter>