home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / con2v766.zip / colore01.zip / doc / hrcdoc.txt next >
Text File  |  2000-08-23  |  10KB  |  198 lines
  1.  
  2.     Colorer library Hrc-scripts syntax description
  3.     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  4.  
  5.     So, hrc script. It was  developed very long and stubborn with  all
  6. difficulties  and  disorders.  And  now  this is an extended Html-like
  7. script format, describing syntax rules of lexical highlighting one  or
  8. more file types, connecting them to the one, and managing their work.
  9.     All tag  can be  linear(if they doesn't contain  closing tag)  and
  10. blocked (if there are opened and closed tags). Many tags needs a names
  11. of structures. As a rule, such parameter called 'Name' and it  must be
  12. unique in its context. It  means that, for example,  could  be defined
  13. only  one  scheme with  name 'myname', but there could also be defined
  14. symbolic color name with name 'myname'.
  15.  
  16.     0. File content.
  17. (in  plugin  distributive  - ColorSet.Hrc). It is closed into the main
  18. block  -   <Colorer  ver=3craze>.  All  other structures are contained
  19. there.   It   has  one   parameter  'ver'  -  I  hope  understandable.
  20.  
  21.     1.  Linear  tag  <define   name="name"  value="number">  describes
  22. symbolical  alternatives  for  colors  values.  There could be as much
  23. defines,  as  you  want.  In  this  tag  you  can  use already defined
  24. constants.   Parameter   'name'   defines  unique  (in  this  context)
  25. symbolical name. Parameter 'value' defines color value of this 'Name'.
  26. Each color consist of two parts - text color, and background.  Text is
  27. tow low  bytes, and background - high. So, color #00040001 define blue
  28. text on  red  background. there are two reserved values. 0xFFFF - this
  29. is a default text color, and 0xFFFF0000 - defaul background color. So,
  30. 0xFFFFFFFF - default color. Of course,  it  is difficult  to enter such
  31. values.  Because of  it, you can use extended form: value="Blue/bkRed"
  32. In this form word before slash - text color,  and color  after slash -
  33. background color. so, slash makes the next operation:
  34. (text&0xFFFF)+(back&0xFFFF0000)
  35. also you can use next form: value="Blue+bkRed". here we have simple
  36. (text)+(back).
  37.  
  38.  
  39.     2.  Linear  tag <include name="fname"> includes external file into
  40. the current. Path must be set relatively of the directory with primary
  41. file independently of directory of current file.
  42.  
  43.     3. Blocked tag <scheme name="schname">.
  44. Each   such  block  -  description  of  one  unique  coloring  scheme.
  45. Parameter  Name  -  system  scheme name.
  46.  
  47. In Scheme block selection types and their attributes are enumerated.
  48.     3.1. <RegExp Start="//" End="//" ColorX="" Prior="">
  49. defines single-line selection,
  50.     3.2. <Block  Start="//" End="//" Scheme="sname" ColorX="">
  51. defines multi-line selection.
  52.     These 2 types  of selection  based  on  regular   expressions
  53. using. (See regexps RegExpsE.txt). Their parameters:
  54. Start  - start regexp combination.
  55. End    - end regexp, if needed (it may not used in RegExp).
  56. Prior  - equal Low or High. High is default.
  57.          This parameter  manages tags  priority. If  Priority  is
  58.          equal  to Low,  than  parent scheme has higher priority.
  59.          Now it is ignored it Block tag.
  60. Scheme - Only for Block tag. Connects Block  with  needed scheme.
  61.          ColorX  -  Text and Back Color. If BackColor is equal to
  62.          0  (fe  #0C),  it  substitutes  with BackCol(default CN2
  63.          Back Color). If you need Black  BackGround,  use BackCol
  64.          value. Last digit X sets colorize level.
  65.  
  66.     3.3. <include scheme="sname">
  67. includes  all  defines  and  regexps  from  scheme sname into current.
  68. There are available up to 64 include levels.
  69.     3.4. <KeyWords MatchCase="bool" Color="">
  70. Blocked tag. Includes keyword defines. Parameters:
  71. MatchCase  -  Match symbol cases (true by default).
  72. Color      -  Keywords color.
  73.     Inline KeyWords tags:
  74.     3.4.1. <Word Name="" Color="">
  75.        Defines word coloring.
  76.        Name   - Word name - less than 64 chars.
  77.        Color  - Its color. If absence - used from Keywords.
  78.     3.4.2. <Symb Name="" Color="">
  79.        As  a  Word, but  it  colorized  in all  positions
  80.        (Word selects  only separate words). There are more,
  81.        than  one KeyWords  block  Scheme can  consist of.
  82.        Define order is unimportant.
  83.  
  84.     4. Block <type >.
  85. <type descr="descr" name="tname" exts="//">
  86. defines one file type and connect it with scheme.
  87. descr   - description of this type.
  88. name    - system name. you must use it for <switch> tag
  89. exts    - Files extensions (regexp).
  90.     4.1. <load value="">
  91.        Load specified files with schemes when selecting this type.
  92.     4.2. <scheme value="sname">
  93.        Define target scheme to use with this file type.
  94.     4.3. <switch type="tname" match="//">
  95.        Used to switch into type 'tname' when matching first line with 'match'
  96.        Note, than tname - system type name, not the description.
  97.     4.4. All other parameters are optional and not supported by colorer
  98.        library instead (applications can use them).
  99.  
  100.     5. All other Blocks,
  101.        parameters and Text are Ignored. You can use Html-style comments:
  102. <!-- Extended information see
  103.      in RegExpsE.txt file      -->
  104.  
  105.     6. So, in more details.
  106. In all files  you  can  see, that it is better to use current format -
  107. for big defines use local colors redefinitions. It is better to define
  108. all colors only through the based defines - it  will let user to quickly
  109. change coloring schemes, and provide more compatibility and  integrity
  110. of the Hrc-file with all the base.
  111. Now   many   files  use  macroses - this are often used  small schemes
  112. with  needed  defines.  At  all,  it  is  more  logical  to divide all
  113. highlighting  in  file  to  a  small schemes(if possible). It slightly
  114. increases the speed.
  115. So, the examples.
  116.  
  117.     6.1. <RegExp Start="/\b(0x|X[\da-fA-F]+)\B/" Color0="dNumbers">
  118. This is a simple hex number with color dNumbers.
  119.     <RegExp Start="/(\/\/.*$)/" Color0="CComment">
  120. And this is a C-style comment // ....
  121.     You  can  ask,  why I need a brackets in regular expression? It is
  122. very  easy.  Each  pair  of brackets sets one color. Because of it you
  123. can  create  more  than one color with one regexp! For example, regexp
  124.     <RegExp Start="/(1)(2)(3)(4)(5)/"
  125.             Color0="1" Color1="2" Color2="3" Color3="4" Color4="5">
  126. will create five colors!
  127. Also  in  RegExp  tag you can put End expression. In this case Colorer
  128. will  highlight  everything from the Start to the End with Color0, and
  129. all  the  brackets  will  be  used  from Color1. Note it. Also you can
  130. make  BackTracing  -  it  the  End  RegExp  make the link to the Start
  131. expression with parameter \yN.
  132.  
  133.     6.2. Tag Block.
  134. It  also  has  End  parameter. It uses the last to highlight text from
  135. Start  regexp  till the End - but on multilines. Here you can also use
  136. Backttracing. For example, with regexp
  137.     <Block Start="/\b(q(.))/" End="/(\y2)/"
  138.          Color0="PlString" Color1="Cyan"  Color2="Cyan" Color3="Cyan">
  139. You can select any strings with Perl rules:
  140. q!....!    q#.....#  q@.......@
  141. Color0 parameter defines all the block color, and other ColorX  params
  142. used for all pairs of brackets.
  143.     So, the Block tag has no differences of  RegExp tag, except it can
  144. work  on multylines. At this moment colorer works rather fast, but you
  145. must always control performance of you regexps.
  146.  
  147.     6.3. One more rule.
  148. Order  of  parsing. All the regexps are parsed it  order they defined.
  149. After them keywords are started. Because of it Colorer ignores defined
  150. order  of  regexps  and  keywords. And from other side it is important
  151. to define regexps in a correct order. It  can be strange - but colorer
  152. works better on files with many regexps - some Htmls, all the Hrcs and
  153. other.  The most slow work - if there are defined much regexps, but in
  154. text  there are little of matches.  The  slowest files are text and so
  155. on...
  156.  
  157.     6.4. And now about smart coloring.
  158. Concept of scheme let you make any rational kind of highlighting. Base
  159. for understanding is that schemes could be inserted in each other more
  160. than  two  times,  and  than  scheme  could  be  inlined  into  itself
  161. (recursion).  Combination  of  this two things let you make any needed
  162. highlighting.  The dignities of this structure is that it is intuition
  163. of scheme concept against different forms of content changes. And what
  164. is  more  schemes concept without difficulties moves to real including
  165. one  scheme  to another: in case of big scheme it will be inheritance,
  166. and  in  case  of a small scheme it will play role of macros. The best
  167. example,  showing  all  schemes  interconnections  is  a  ASP-language
  168. highlighting.   If  you  take  to  pieces  all  its  content, you  can
  169. consider, that you know Hrc-architecture better than I am.
  170.  
  171.     7. Full structure.
  172. So, at the end take a view of all Hrc-structure format:
  173.  
  174. <colorer ver=3craze>
  175.   <define name="name" value="color">
  176.   <include name="fname">
  177.   <scheme name="sname" descr="">
  178.     <include Scheme="sname">
  179.     <regexp start="//" end="//" color0="" prior="">
  180.     <block  start="//" end="//" scheme="" color0="">
  181.     <keywords matchcase="" color="">
  182.       <word name="" color="">
  183.       <symb name="" color="">
  184.     </keywords>
  185.   </scheme>
  186.   <type scheme="sname" name="" exts="//">
  187.     <load value="">
  188.     <scheme value="">
  189.     <switch type="tname" match="//">
  190.   </type>
  191. </colorer>
  192.  
  193.  
  194.                                 It finally happened - happened
  195.                                 It finally happened - ooh oh
  196.                                 It finally happened - I'm slightly mad
  197.                                 Oh dear!
  198.