/usr/share/doc/the/html/app4.html

<HTML>
<HEAD><TITLE>THE Reference - Appendix 4 </TITLE></HEAD>
<BODY BGCOLOR="#F1EDD1" LINK = "#0000FF" VLINK = "#FF0022" ALINK = "#808000">
<CENTER> <img WIDTH="64" HEIGHT="64" HSPACE="20" SRC="the64.png" ALT="THE"> </CENTER>
<A NAME="APPENDIX4"></A>
<H2> APPENDIX 4 - SYNTAX HIGHLIGHTING IN THE </H2>
<HR>
  This appendix contains details on syntax highlighting in THE.  Syntax highlighting is the mechanism by which different tokens within a file; usually containing source code, are displayed in different colours. <P>
  The model THE uses for its syntax highlighting is based on the model used by KEDIT for Windows from Mansfield Software.  This model is extremely configurable and flexible. While most of the KEDIT features are implemented, THE also adds a couple of other features that make the syntax highlighting even better. <P>
  This appendix concentrates on the format of THE language definition files. For a description of the commands that manipulate other aspects of syntax highlighting in THE, see the descriptions of the following commands: <A HREF = "commset.html#SETAUTOCOLOR">SET AUTOCOLOR</A> , <A HREF = "commset.html#SETCOLORING">SET COLORING</A> , <A HREF = "commset.html#SETECOLOR">SET ECOLOR</A> , <A HREF = "commset.html#SETPARSER">SET PARSER</A> . <P>
<H3> Performance Impact </H3><P>
  Syntax highlighting in an editor comes at a cost; reduced performance. <P>
  Because of the extra processing required to determine which characters are displayed in which colours, displaying the screen is slower.  As THE recalculates the display colours after every displayable key is pressed, then you may notice a reduction in responsiveness. <P>
  The more features that are specified in a TLD, the slower the syntax highlighting will be. To dynamically turn on or off the application of some headers within a TLD file, see the <A HREF = "commset.html#SETHEADER">SET HEADER</A>  command. <P>
  For those languages that allow paired comments (ie they can span multiple lines) performance is impacted even more.  This is because THE has to determine if the lines being displayed are within one of these multi-line comment pairs which may start before the first displayed line. <P>
  THE will incorrectly display syntax highlighting in certain circumstances. This is because THE does not fully parse the complete file to determine the correct colours; that would be too slow.  Instead, THE checks the currently displayed lines and determines the syntax highlighting based on these lines. <P>
  Where THE will get syntax highlighting wrong: <P>
  If all displayed lines are within a multi-line comment block and neither the starting comment token nor the ending comment token are displayed. THE will treat the displayed lines as code. <P>
  When the starting or ending comment tokens for multi-line comments are part of a language string. <P>
  Also bear in mind that excluding large portions of the file with ALL, will dramatically slow down checking of multi-line comments. <P>
<H3> File Extensions Vs Magic Numbers </H3><P>
  A THE extension to the KEDIT syntax highlighting model is support for <A HREF = "glossary.html#MAGICNUMBERS">magic numbers</A> . (See <A HREF = "commset.html#SETAUTOCOLOR">SET AUTOCOLOR</A> for more details).  For the default <A HREF = "glossary.html#PARSER">parser</A> s, where there might be a conflict between setting syntax highlighting based on a file extension or a <A HREF = "glossary.html#MAGICNUMBER">magic number</A> , the file extension mapping takes precedence. <P>
<H3> THE Language Definition Files </H3><P>
  THE Language Definition Files usually have a file extension of .tld. THE comes with a small number of sample TLD files. Look at these files in conjunction with the following descriptions to fully understand how to write your own TLD files. <P>
  TLD files consist of several sections identified by header lines. Header lines start with a colon in column one.  Items within the particular header are listed on separate lines after the header to which they apply. Blank lines are ignored, and so are comments (* as first non-blank). Each item that can be repeated occurs on a separate line. The above definition of what a TLD file looks like is expressed in the TLD file; tld.tld. <P>
  Many items in a TLD are specified as a regular expression (RE).  THE supports a number of RE syntaxes for targets. All REs specified in a TLD are parsed using the EMACS syntax.  For details of RE usage in THE see Appendix 7. <P>
  The purpose of each header and the valid contents are explained below. <P>
<H4> :identifier </H4><P>
  This section specifies, using a regular expression how a keyword in the language is defined.  The only item line contains three regular expressions separated by space characters. <BR>
<I><B>Syntax:</B></I><BR>
<I>first_char_re other_char_re [last_char_re]</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>first_char_re</I><BR>
   This regular expression specifies the valid characters that an identifier can begin with. <BR>
<I>other_char_re</I><BR>
   This regular expression specifies the valid characters that the remainder of characters in an identifier can consist of. <BR>
<I>last_char_re</I><BR>
   This regular expression is optional. If specified, it states the valid characters that an identifier can end with. <P>
<H4> :case </H4><P>
  This section defines whether the case of letters that make up identifiers in the language are case-sensitive or not. Only one of the items below can be included. <BR>
<I><B>Syntax:</B></I><BR>
<I>RESPECT | IGNORE</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>respect</I><BR>
   case is relevant. The keywords  <I>if</I> ,  <I>IF</I>  and  <I>If</I>  are different. <BR>
<I>ignore</I><BR>
   case is irrelevant. The keywords  <I>if</I>  and  <I>IF</I>  are treated as the same identifier. <P>
<H4> :option </H4><P>
  This section specifies different options that can affect other sections. The options below can all be included in the one TLD. <BR>
<I><B>Syntax:</B></I><BR>
<I>REXX</I><BR>
<I>PREPROCESSOR char</I><BR>
<I>FUNCTION char BLANK | NOBLANK [DEFAULT ALTernate x]</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>rexx</I><BR>
   specifies special processing for Rexx. eg. Functions defined in the :functions section, are also highlighted if preceeded by CALL. <BR>
<I>preprocessor char</I><BR>
   languages like C that have preprocessor identifiers usually begin with a special character (specified by  <I>char</I> ) to differentiate these types of keywords from others. <BR>
<I>function char blank | noblank [default alternate x]</I><BR>
   this option is used to identify how keywords specified in the :function section are identified.  <I>char</I>  specifies the character that is used to start a function, usually  <I>(</I> . The  <I>blank</I>  or  <I>noblank</I>  argument determines if blank characters can appear between the function identifier and the function start character. eg a Rexx function call must be written without blanks between the function name and the function start character:  <I>word(</I> . In C  <I>word  (</I>  or  <I>word(</I>  are both valid syntax for a function call. The optional "default alternate x" specifies the color in which functions that are NOT specified in the :function section are to be displayed. See the explanation of alternate colors in the :function section. Without "default alternate x", the color of unknown functions is not changed. <P>
<H4> :number </H4><P>
  This section specifies the format of numbers in the language. Most languages use a small number of generic types of numbers. <BR>
<I><B>Syntax:</B></I><BR>
<I>REXX | C | COBOL</I><BR>
<I><B>Meaning of options:</B></I><BR>
   ECOLOR Value: Numbers are displayed in the colour specified with ECOLOUR  <I>C</I> . <P>
<H4> :string </H4><P>
  This section specifies how strings within the language are defined. Multiple values may be specified, as many languages use both single and double quotes. <BR>
<I><B>Syntax:</B></I><BR>
<I>SINGLE [BACKSLASH] | DOUBLE [BACKSLASH]</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>single</I><BR>
   Specifies that the language uses single quotes to identify a string. <BR>
<I>double</I><BR>
   Specifies that the language uses double quotes to identify a string. <BR>
<I>backslash</I><BR>
   Some languages require a backslash character immediately preceding either a single or double quote to allow the quote to be included in the string. <BR>
<I><B>ECOLOR Character:</B></I><BR>
   For complete strings, the ECOLOUR character used is  <I>B</I> . For incomplete strings, the ECOLOUR character used is  <I>S</I> . <P>
<H4> :comment </H4><P>
  This section specifies the format of comments. Both paired and line comments can be specified, as can multiple occurrences of each. <BR>
<I><B>Syntax:</B></I><BR>
<I>PAIRED open_string close_string [NEST | NONEST]</I><BR>
<I>LINE comment_string ANY | FIRSTNONBLANK | COLUMN n</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>paired</I><BR>
   These types of comments can span multiple lines. They have an opening string and a closing string. <BR>
<I>open_string</I><BR>
   This defines the string that opens a paired comment. <BR>
<I>close_string</I><BR>
   This defines the string that closes a paired comment. <BR>
<I>nest</I><BR>
   Some languages allow paired comments to be nested. (not implemented) <BR>
<I>nonest</I><BR>
   Defining this indicates that the language does not allow nesting of paired comments. The effect of this option will result in the first close_string to end the paired comment no matter how many open_string occurrences there are. (not implemented) <BR>
<I>line</I><BR>
   These type of comments cannot span multiple lines.  Everything on the line after the comment_string is considered part of the comment. <BR>
<I>comment_string</I><BR>
   The string that defines a line comment. <BR>
<I>any</I><BR>
   For line comments, this indicates that the comment_string can occur anywhere on the line, and all characters following it are part of the comment. <BR>
<I>firstnonblank</I><BR>
   For line comments, this indicates that the comment_string can only occur as the first non-blank of the line. <BR>
<I>column n</I><BR>
   For line comments, this indicates that the comment_string must start in the specified column. <BR>
<I><B>ECOLOR Character:</B></I><BR>
   Comments are displayed in the colour specified with ECOLOUR  <I>A</I> . <P>
<H4> :keyword </H4><P>
  This section specifies all of the identifiers that are to be considered language keywords. You must specific the :identifier section in the TLD file before the :keyword section. <BR>
<I><B>Syntax:</B></I><BR>
<I>keyword [ALTernate x] [TYPE x]</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>keyword</I><BR>
   This specifies the string that is considered to be a language keyword. <BR>
<I>alternate x</I><BR>
   All keywords are displayed in the same colour, unless you use this option to specify a different colour.  In KEDIT there are 9 alternate colours that can be used; ECOLOUR 1 through 9. In THE any ECOLOUR character can be used as an alternate colour.  <I>alternate</I>  can be abbreviated to  <I>alt</I> . <BR>
<I>type x</I><BR>
   (not implemented) <BR>
<I><B>ECOLOR Character:</B></I><BR>
   Unless overridden by the  <I>alternate</I>  option, the keyword is displayed in the colour specified with ECOLOUR  <I>D</I> . <P>
<H4> :function </H4><P>
  This section specifies all of the identifiers that are to be considered functions.  Normally this is used for those functions that are builtin into the language, but can be any identifier. You specify the function identifier without the function char specified in the :option section. You must specify the :option and the :identifier sections in the TLD file before the :function section. <BR>
<I><B>Syntax:</B></I><BR>
<I>function [ALTernate x]</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>function</I><BR>
   This specifies the string that is considered to be a language function. <BR>
<I>alternate x</I><BR>
   All functions are displayed in the same colour, unless you use this option to specify a different colour.  In KEDIT there are 9 alternate colours that can be used; ECOLOUR 1 through 9. In THE any ECOLOUR character can be used as an alternate colour.  <I>alternate</I>  can be abbreviated to  <I>alt</I> . <BR>
<I><B>ECOLOR Character:</B></I><BR>
   Unless overridden by the  <I>alternate</I>  option, the function is displayed in the colour specified with ECOLOUR  <I>V</I> . <P>
<H4> :header </H4><P>
  This section specifies the format of headers. Headers are lines within a file that begin with a particular string and usually identify different parts of the file. They are similar to labels. <BR>
<I><B>Syntax:</B></I><BR>
<I>LINE header_string ANY | FIRSTNONBLANK | COLUMN n [ALTernate x]</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>header_string</I><BR>
   The string that defines a header. <BR>
<I>any</I><BR>
   This indicates that the header_string can occur anywhere on the line, and all characters following it are part of the header. <BR>
<I>firstnonblank</I><BR>
   This indicates that the header_string can only occur as the first non-blank of the line. <BR>
<I>column n</I><BR>
   This indicates that the header_string must start in the specified column. <BR>
<I>alternate x</I><BR>
   All headers are displayed in the same colour, unless you use this option to specify a different colour.  In KEDIT there are 9 alternate colours that can be used; ECOLOUR 1 through 9. In THE any ECOLOUR character can be used as an alternate colour.  <I>alternate</I>  can be abbreviated to  <I>alt</I> . <BR>
<I><B>ECOLOR Character:</B></I><BR>
   Unless overridden by the  <I>alternate</I>  option, the function is displayed in the colour specified with ECOLOUR  <I>G</I> . <P>
<H4> :label </H4><P>
  This section specifies the format of labels. Labels are lines within a file that end with a particular string. They are similar to headers. <BR>
<I><B>Syntax:</B></I><BR>
<I>DELIMITER label_string ANY | FIRSTNONBLANK | COLUMN n</I><BR>
<I>COLUMN n</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>label_string</I><BR>
   The string that defines a label. <BR>
<I>any</I><BR>
   This indicates that the label_string can occur anywhere on the line, and all characters up to it are part of the label. <BR>
<I>firstnonblank</I><BR>
   This indicates that the label_string can only occur as the first non-blank of the line. <BR>
<I>column n</I><BR>
   As part of a DELIMITER label, this indicates that the label_string must start in the specified column. If specified by itself, then the label does not require any special delimiter; the non-keyword that starts in the specified column is regarded as a label. <BR>
<I><B>ECOLOR Character:</B></I><BR>
   Labels are displayed in the colour specified with ECOLOUR  <I>E</I> . <P>
<H4> :markup </H4><P>
  This section specifies the delimiters for a markup tag, and optionally the delimiters for references within a markup language. <BR>
<I><B>Syntax:</B></I><BR>
<I>TAG tag_start tag_end [REFERENCE ref_start ref_end]</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>tag_start</I><BR>
   The character that specifies the start of a markup tag. <BR>
<I>tag_end</I><BR>
   The character that specifies the end of a markup tag. <BR>
<I>ref_start</I><BR>
   The character that specifies the start of a markup reference. <BR>
<I>ref_end</I><BR>
   The character that specifies the end of a markup reference. <BR>
<I><B>ECOLOR Character:</B></I><BR>
   Tags are displayed in the colour specified with ECOLOUR  <I>T</I> . References are displayed in the colour spceified with ECOLOUR  <I>U</I> . <P>
<H4> :match </H4><P>
  (Not implemented yet) <P>
<H4> :column </H4><P>
  This section specifies the range of columns in your file which is to have syntax highlighting applied.  For example, columns 1-6 and beyond column 72 in a COBOL source file should be excluded from being parsed. Any number of EXCLUDE clauses are allowed. Note. Not all syntax checking respects excluded columns at this stage. <BR>
<I><B>Syntax:</B></I><BR>
<I>EXCLUDE first_column last_column [ALTernate x]</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>first_column</I><BR>
   The first column to be excluded <BR>
<I>last_column</I><BR>
   The last column to be excluded.  <I>*</I>  can be used to specify to the end of the line. <BR>
<I>alternate x</I><BR>
   All excluded characters are displayed in the same colour, unless you use this option to specify a different colour.  In KEDIT there are 9 alternate colours that can be used; ECOLOUR 1 through 9. In THE any ECOLOUR character can be used as an alternate colour.  <I>alternate</I>  can be abbreviated to  <I>alt</I> . <BR>
<I><B>ECOLOR Character:</B></I><BR>
   Unless overridden by the  <I>alternate</I>  option, the excluded characters are displayed in the colour specified with COLOUR FILEAREA. <P>
<H4> :directory </H4><P>
  This section is applicable only to the pseudo file; DIR.DIR. It is used to specify the colour used to display lines in the DIR.DIR file. <BR>
<I><B>Syntax:</B></I><BR>
<I>DIRectory [ALTernate x]</I><BR>
<I>LINK [ALTernate x]</I><BR>
<I>EXEcutable [ALTernate x]</I><BR>
<I>EXTensions ext1 ext2 ext3 ... ALTernate x</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>directory</I><BR>
   Indicates that directories are to be highlighted. Unless overridden by the  <I>alternate</I>  option, the matched line is displayed with ECOLOUR  <I>W</I> . <BR>
<I>link</I><BR>
   Indicates that symbolic links are to be highlighted. Unless overridden by the  <I>alternate</I>  option, the matched line is displayed with ECOLOUR  <I>X</I> . <BR>
<I>executable</I><BR>
   Used to specify the colour used to display executable files. The checking is simple and simply determines if the executable bit is set for user, group or world. Only applicable to UNIX systems. Unless overridden by the  <I>alternate</I>  option, the matched line is displayed with ECOLOUR  <I>Y</I> . <BR>
<I>extensions</I><BR>
   A space-separated list of extensions to be displayed in the specifed alternate colour.  The complete line is coloured.  The match is applied by checking each extension against the characters at the end of the line, so while it is intended for extensions, any string that is specified as an extension can be matched; it doesn <I>t have to have a period in the matched string. A maximum of 10 extensions can be specified on each line. The </I> alternate <I> keyword and option must be specified.</I> <BR>
<I>alternate x</I><BR>
   In KEDIT there are 9 alternate colours that can be used; ECOLOUR 1 through 9. In THE any ECOLOUR character can be used as an alternate colour.  <I>alternate</I>  can be abbreviated to  <I>alt</I> . <P>
<H4> :postcompare </H4><P>
  This section specifies items that are checked for after all other syntax checking has been completed.  This can be useful if you want to allow user-defined datatypes or other code to be displayed in different colours. <BR>
<I><B>Syntax:</B></I><BR>
<I>CLASS re [ALTernate x]</I><BR>
<I>TEXT string [ALTernate x]</I><BR>
<I><B>Meaning of options:</B></I><BR>
<I>re</I><BR>
   This regular expression specifies the text to be highlighted. <BR>
<I>string</I><BR>
   This indicates the literal string to be highlighted. <BR>
<I>alternate x</I><BR>
   All matched postcompare characters are displayed in the same colour, unless you use this option to specify a different colour.  In KEDIT there are 9 alternate colours that can be used; ECOLOUR 1 through 9. In THE any ECOLOUR character can be used as an alternate colour.  <I>alternate</I>  can be abbreviated to  <I>alt</I> . <BR>
<I><B>ECOLOR Character:</B></I><BR>
   Unless overridden by the  <I>alternate</I>  option, the matched characters are displayed in the colour specified with ECOLOUR  <I>D</I> . <P>
<H3> Builtin Parsers </H3><P>
  THE includes a number of builtin syntax highlighting <A HREF = "glossary.html#PARSER">parser</A> s. The following table lists the default <A HREF = "glossary.html#PARSER">parser</A> s and the files they apply to: <P>
<CENTER><TABLE BORDER=1 CELLSPACING=1 CELLPADDING=2>
<TR><TH>Parser</TH><TH>Filemasks</TH><TH>"Magic Number"</TH></TR>
<TR><TD>REXX<BR><BR><BR><BR><BR></TD><TD>*.rex<BR>*.rexx<BR>*.cmd<BR>*.the<BR>.therc<BR></TD><TD>rexx<BR>regina<BR>rxx<BR><BR><BR></TD></TR>
<TR><TD>C<BR><BR><BR><BR><BR></TD><TD>*.c<BR>*.h<BR>*.cc<BR>*.hpp<BR>*.cpp<BR></TD><TD><BR><BR><BR><BR><BR></TD></TR>
<TR><TD>SH<BR><BR><BR><BR></TD><TD><BR><BR><BR><BR></TD><TD>sh<BR>ksh<BR>bash<BR>zsh<BR></TD></TR>
<TR><TD>TLD<BR></TD><TD>*.tld<BR></TD><TD><BR></TD></TR>
<TR><TD>HTML<BR><BR></TD><TD>*.html<BR>*.htm<BR></TD><TD><BR><BR></TD></TR>
<TR><TD></TD><TD></TD><TD></TD></TR></TABLE></CENTER><P>
  A Rexx macro is provided; tld2c.rex, to convert a .tld file into the C code that can be embedded in default.c. This enables you to configure THE with the default <A HREF = "glossary.html#PARSER">parser</A> s that are more applicable for you. <P>
<HR>
<ADDRESS>
The Hessling Editor is Copyright &copy; <A HREF = "http://www.rexx.org/">Mark Hessling</A>, 1990-2016
&lt;<A HREF = "mailto:mark@rexx.org">mark@rexx.org</A>&gt;
<BR>Generated on: 10 Aug 2016
</ADDRESS><HR>
Return to <A HREF = "index.html#TOC"> Table of Contents </A><BR>
</BODY> </HTML>
the-doc 3.3~rc1-3 / usr / share / doc / the / html / app4.html
