home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / jed098-4.zip / JED / DOC / DFA.TXT < prev    next >
Text File  |  1997-02-01  |  8KB  |  200 lines
  1.  
  2. DFA-based Syntax Highlighting
  3. =============================
  4.  
  5. DFA highlighting is an alternative syntax highlighting mechanism to
  6. Jed's original simple one. It's a lot more powerful, but it takes up
  7. more memory and makes the executable larger if it's compiled in.
  8. It's also more difficult to design new highlighting modes for.
  9.  
  10. DFA highlighting works *alongside* Jed's old highlighting system: it
  11. doesn't prevent any language modes from using the old scheme. Any
  12. language modes that want to, however, can use the new scheme.
  13.  
  14. Some examples of what DFA highlighting can do that the old scheme
  15. can't are:
  16.  
  17. - Correct separation of numeric tokens in C. The text `2+3' would
  18.   get highlighted as a single number by the old scheme, since `+' is
  19.   a valid numeric character (when preceded by an E). DFA
  20.   highlighting can spot that the `+' is not a valid numeric
  21.   character in _this_ instance, though, and correctly interpret it
  22.   as an operator.
  23.  
  24. - Highlighting of comments on preprocessor lines.
  25.  
  26. - Enhanced HTML mode, in which tags containing mismatched quotes
  27.   (such as `<a href="filename>') can be highlighted in a different
  28.   colour from correctly formed tags.
  29.  
  30. - Much improved Perl mode, in general.
  31.  
  32. - PostScript mode, in which up to two levels of nested parentheses
  33.   can be detected inside a string constant.
  34.  
  35. Using DFA Highlighting
  36. ----------------------
  37.  
  38. If Jed is compiled with DFA highlighting enabled, it will define the
  39. S-Lang preprocessor name `HAS_DFA_SYNTAX', and also define three
  40. extra functions: `enable_highlight_cache', `define_highlight_rule'
  41. and `build_highlight_table'. These are documented in Jed's ordinary
  42. function help.
  43.  
  44. To implement a DFA highlighting scheme, you define a number of
  45. highlighting rules using `define_highlight_rule', and then enable
  46. the scheme using `build_highlight_table', which will build the
  47. internal data structure (DFA table) that is actually used to do the
  48. highlighting.
  49.  
  50. Generating the DFA table can take a long time, especially for
  51. complex modes such as C (or even more so, PostScript). For this
  52. reason, the DFA tables can be cached by the use of
  53. `enable_highlight_cache'. You call this routine before defining any
  54. highlighting rules. If the cache file exists, the DFA table will be
  55. loaded directly from it, and the subsequent calls to
  56. `define_highlight_rule' and `build_highlight_table' will do nothing.
  57. If the cache file does not exist, then after Jed has built the DFA
  58. table it will attempt to create the cache.
  59.  
  60. Cache files are created in the JED_LIBRARY directory, so on a Unix
  61. system it is likely that you will need to be `root' to create caches.
  62.  
  63. Highlighting Rules
  64. ------------------
  65.  
  66. Highlighting rules are basically regular expressions. You define
  67. regular-expression patterns for the objects that you want to
  68. highlight, and specify the colour that each object should be
  69. highlighted. Colours are specified as `keyword', `normal',
  70. `operator', `delimiter' and so on.
  71.  
  72. A sample highlighting rule, from C mode, might look like this:
  73.  
  74. define_highlight_rule("0[xX][0-9A-Fa-f]*[LlUu]*", "number", "C");
  75.  
  76. This specified that in the syntax table called `C', any object
  77. matching the regular expression `0[xX][0-9A-Fa-f]*[LU]*' should be
  78. highlighted in the colour assigned to numbers. This regular
  79. expression matches C hexadecimal integer constants: a zero, an X (of
  80. either case), a sequence of hex digits, and optionally an L or a U
  81. on the end (for `long' or `unsigned').
  82.  
  83. Regular expression syntax is as follows:
  84.  
  85. - A normal character matches itself. Normal characters include
  86.   everything except special characters, which are ^ $ | * + ? [ ] -
  87.   . ( ) and the backslash \.
  88.  
  89. - A character class [abcde] matches any one of the characters inside
  90.   it. Ranges can be specified with a dash, e.g. [a-e]. A character
  91.   class starting with a caret matches any single character _not_
  92.   inside it, e.g. [^a-e] matches anything except a, b, c, d or e.
  93.  
  94. - A period (.) matches any character.
  95.  
  96. - A character, or a character class, or a regular expression in
  97.   parentheses, can be followed by *, + or ?. If followed by * then
  98.   it will match any number of occurrences of the original
  99.   expression, including none at all; followed by + it will match any
  100.   number *not* including zero; followed by ? it will match zero or
  101.   one.
  102.  
  103. - Two regular expressions separated by | will match either one.
  104.  
  105. - A caret at the beginning of an expression causes it to match only
  106.   when at the beginning of a line. A dollar at the end causes it to
  107.   match only when at the end.
  108.  
  109. - If you want to match one of the special characters, you can remove
  110.   its special properties by placing a backslash before it. This
  111.   includes the backslash itself.
  112.  
  113. So, for example:
  114.  
  115.     apple|banana        matches `apple' or `banana'
  116.     (apple|banana)?        matches `apple', `banana' or nothing
  117.     b[ae]d            matches `bad' or `bed'
  118.     [a-e]            matches `a', `b', `c', `d' or `e'
  119.     [a\-e]            matches `a', `-' or `e'
  120.     ^#include        matches `#include', but only at the start
  121.                 of a line
  122.     '[^']*'            matches any sequence of non-single-quotes
  123.                 with a single-quote at each end, such as
  124.                 a Pascal string literal
  125.     '[^']$            matches any sequence of non-single-quotes
  126.                 with a single-quote at the beginning and
  127.                 occurring at the end of a line, such as
  128.                 a Pascal string literal that the user has
  129.                 not finished typing
  130.  
  131. To define a highlight rule, you think up the regular expression,
  132. express it as an S-Lang string literal, and include it in a call to
  133. `define_highlight_rule'.
  134.  
  135. CAUTION: S-Lang strings obey the same syntax as C strings. This
  136. means that if you need a double quote or a backslash as part of your
  137. regular expression, you have to put *another* backslash before it
  138. when you write it as an S-Lang string. So the fifth example above
  139. might read
  140.  
  141.     define_highlight_rule ("[a\\-e]", ...);
  142.  
  143. with the backslash doubled. Also, the rules in C mode and S-Lang
  144. mode that match string constants have _way_ too many backslashes to
  145. be easily readable, and mostly look like line noise. I know that's a
  146. pain, but I couldn't help it.
  147.  
  148. Extra Magical Bits
  149. ------------------
  150.  
  151. The second argument to `define_highlight_rule' is a colour name.
  152. This colour name can be prefixed by a few special letters for extra
  153. magical effects:
  154.  
  155. `Q' causes the match to be _quick_. Most of the time, the regular
  156. expression matcher finds the _longest_ string starting at the
  157. current position that matches something. A `Q' rule will match with
  158. far higher priority, and will match the _shortest_ string possible.
  159. For example, consider the expression `/\*.*\*/' which matches `/*',
  160. then any sequence of characters, then `*/' - a one-line C comment.
  161. The difficulty is that C comments do not nest, and a sequence like
  162.  
  163. /* comment */ not comment */
  164.  
  165. should only be highlighted as a comment up to the _first_ `*/'. The
  166. normal longest-match heuristic will highlight the _whole_ thing as a
  167. comment, which is wrong. You can get round this by defining the rule
  168. as quick, like this:
  169.  
  170.     define_highlight_rule("/\\*.*\\*/", "Qcomment", "C");
  171.  
  172. `P' denotes a _preprocessor-type_ rule. Preprocessor-type rules
  173. state that not only should the matched text be given the specified
  174. colour, but so should everything on the rest of the line, _except_
  175. things in the comment colour. This allows comments on preprocessor
  176. lines, with quite a high level of sophistication: defining, in C mode,
  177.  
  178.     define_highlight_rule("^[ \t]*#", "PQpreprocess", "C");
  179.  
  180. will cause the following effects:
  181.  
  182.     #define FLAG            comes up in preprocessor colour
  183.     #define FLAG /* comment */    the comment is highlighted right
  184.     #include "/*sdfs*/"        the comment does _not_ get seen!
  185.  
  186. Finally, `K' defines a _keyword_ rule. In a keyword rule, the
  187. matched text is compared to the active keyword tables for the syntax
  188. scheme, and given the correct keyword colour if a match is found.
  189. If no keyword matches the text, the text will be highlighted in the
  190. colour that was _actually_ specified in the rule.
  191.  
  192. Further Reading
  193. ---------------
  194.  
  195. If you want to design _really_ complicated highlighting schemes, it
  196. may be that a full understanding of the principles and theory behind
  197. the DFA scheme may be helpful. Most books on compiler theory will
  198. give a good discussion of this.
  199.  
  200.