Colorer library Hrc-scripts syntax description
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    So, hrc script. It was  developed very long and stubborn with  all
difficulties  and  disorders.  And  now  this is an extended Html-like
script format, describing syntax rules of lexical highlighting one  or
more file types, connecting them to the one, and managing their work.
    All tag  can be  linear(if they doesn't contain  closing tag)  and
blocked (if there are opened and closed tags). Many tags needs a names
of structures. As a rule, such parameter called 'Name' and it  must be
unique in its context. It  means that, for example,  could  be defined
only  one  scheme with  name 'myname', but there could also be defined
symbolic color name with name 'myname'.

    0. File content.
(in  plugin  distributive  - ColorSet.Hrc). It is closed into the main
block  -   <Colorer  ver=3craze>.  All  other structures are contained
there.   It   has  one   parameter  'ver'  -  I  hope  understandable.

    1.  Linear  tag  <define   name="name"  value="number">  describes
symbolical  alternatives  for  colors  values.  There could be as much
defines,  as  you  want.  In  this  tag  you  can  use already defined
constants.   Parameter   'name'   defines  unique  (in  this  context)
symbolical name. Parameter 'value' defines color value of this 'Name'.
Each color consist of two parts - text color, and background.  Text is
tow low  bytes, and background - high. So, color #00040001 define blue
text on  red  background. there are two reserved values. 0xFFFF - this
is a default text color, and 0xFFFF0000 - defaul background color. So,
0xFFFFFFFF - default color. Of course,  it  is difficult  to enter such
values.  Because of  it, you can use extended form: value="Blue/bkRed"
In this form word before slash - text color,  and color  after slash -
background color. so, slash makes the next operation:
(text&0xFFFF)+(back&0xFFFF0000)
also you can use next form: value="Blue+bkRed". here we have simple
(text)+(back).


    2.  Linear  tag <include name="fname"> includes external file into
the current. Path must be set relatively of the directory with primary
file independently of directory of current file.

    3. Blocked tag <scheme name="schname">.
Each   such  block  -  description  of  one  unique  coloring  scheme.
Parameter  Name  -  system  scheme name.

In Scheme block selection types and their attributes are enumerated.
    3.1. <RegExp Start="//" End="//" ColorX="" Prior="">
defines single-line selection,
    3.2. <Block  Start="//" End="//" Scheme="sname" ColorX="">
defines multi-line selection.
    These 2 types  of selection  based  on  regular   expressions
using. (See regexps RegExpsE.txt). Their parameters:
Start  - start regexp combination.
End    - end regexp, if needed (it may not used in RegExp).
Prior  - equal Low or High. High is default.
         This parameter  manages tags  priority. If  Priority  is
         equal  to Low,  than  parent scheme has higher priority.
         Now it is ignored it Block tag.
Scheme - Only for Block tag. Connects Block  with  needed scheme.
         ColorX  -  Text and Back Color. If BackColor is equal to
         0  (fe  #0C),  it  substitutes  with BackCol(default CN2
         Back Color). If you need Black  BackGround,  use BackCol
         value. Last digit X sets colorize level.

    3.3. <include scheme="sname">
includes  all  defines  and  regexps  from  scheme sname into current.
There are available up to 64 include levels.
    3.4. <KeyWords MatchCase="bool" Color="">
Blocked tag. Includes keyword defines. Parameters:
MatchCase  -  Match symbol cases (true by default).
Color      -  Keywords color.
    Inline KeyWords tags:
    3.4.1. <Word Name="" Color="">
       Defines word coloring.
       Name   - Word name - less than 64 chars.
       Color  - Its color. If absence - used from Keywords.
    3.4.2. <Symb Name="" Color="">
       As  a  Word, but  it  colorized  in all  positions
       (Word selects  only separate words). There are more,
       than  one KeyWords  block  Scheme can  consist of.
       Define order is unimportant.

    4. Block <type >.
<type descr="descr" name="tname" exts="//">
defines one file type and connect it with scheme.
descr   - description of this type.
name    - system name. you must use it for <switch> tag
exts    - Files extensions (regexp).
    4.1. <load value="">
       Load specified files with schemes when selecting this type.
    4.2. <scheme value="sname">
       Define target scheme to use with this file type.
    4.3. <switch type="tname" match="//">
       Used to switch into type 'tname' when matching first line with 'match'
       Note, than tname - system type name, not the description.
    4.4. All other parameters are optional and not supported by colorer
       library instead (applications can use them).

    5. All other Blocks,
       parameters and Text are Ignored. You can use Html-style comments:
<!-- Extended information see
     in RegExpsE.txt file      -->

    6. So, in more details.
In all files  you  can  see, that it is better to use current format -
for big defines use local colors redefinitions. It is better to define
all colors only through the based defines - it  will let user to quickly
change coloring schemes, and provide more compatibility and  integrity
of the Hrc-file with all the base.
Now   many   files  use  macroses - this are often used  small schemes
with  needed  defines.  At  all,  it  is  more  logical  to divide all
highlighting  in  file  to  a  small schemes(if possible). It slightly
increases the speed.
So, the examples.

    6.1. <RegExp Start="/\b(0x|X[\da-fA-F]+)\B/" Color0="dNumbers">
This is a simple hex number with color dNumbers.
    <RegExp Start="/(\/\/.*$)/" Color0="CComment">
And this is a C-style comment // ....
    You  can  ask,  why I need a brackets in regular expression? It is
very  easy.  Each  pair  of brackets sets one color. Because of it you
can  create  more  than one color with one regexp! For example, regexp
    <RegExp Start="/(1)(2)(3)(4)(5)/"
            Color0="1" Color1="2" Color2="3" Color3="4" Color4="5">
will create five colors!
Also  in  RegExp  tag you can put End expression. In this case Colorer
will  highlight  everything from the Start to the End with Color0, and
all  the  brackets  will  be  used  from Color1. Note it. Also you can
make  BackTracing  -  it  the  End  RegExp  make the link to the Start
expression with parameter \yN.

    6.2. Tag Block.
It  also  has  End  parameter. It uses the last to highlight text from
Start  regexp  till the End - but on multilines. Here you can also use
Backttracing. For example, with regexp
    <Block Start="/\b(q(.))/" End="/(\y2)/"
         Color0="PlString" Color1="Cyan"  Color2="Cyan" Color3="Cyan">
You can select any strings with Perl rules:
q!....!    q#.....#  q@.......@
Color0 parameter defines all the block color, and other ColorX  params
used for all pairs of brackets.
    So, the Block tag has no differences of  RegExp tag, except it can
work  on multylines. At this moment colorer works rather fast, but you
must always control performance of you regexps.

    6.3. One more rule.
Order  of  parsing. All the regexps are parsed it  order they defined.
After them keywords are started. Because of it Colorer ignores defined
order  of  regexps  and  keywords. And from other side it is important
to define regexps in a correct order. It  can be strange - but colorer
works better on files with many regexps - some Htmls, all the Hrcs and
other.  The most slow work - if there are defined much regexps, but in
text  there are little of matches.  The  slowest files are text and so
on...

    6.4. And now about smart coloring.
Concept of scheme let you make any rational kind of highlighting. Base
for understanding is that schemes could be inserted in each other more
than  two  times,  and  than  scheme  could  be  inlined  into  itself
(recursion).  Combination  of  this two things let you make any needed
highlighting.  The dignities of this structure is that it is intuition
of scheme concept against different forms of content changes. And what
is  more  schemes concept without difficulties moves to real including
one  scheme  to another: in case of big scheme it will be inheritance,
and  in  case  of a small scheme it will play role of macros. The best
example,  showing  all  schemes  interconnections  is  a  ASP-language
highlighting.   If  you  take  to  pieces  all  its  content, you  can
consider, that you know Hrc-architecture better than I am.

    7. Full structure.
So, at the end take a view of all Hrc-structure format:

<colorer ver=3craze>
  <define name="name" value="color">
  <include name="fname">
  <scheme name="sname" descr="">
    <include Scheme="sname">
    <regexp start="//" end="//" color0="" prior="">
    <block  start="//" end="//" scheme="" color0="">
    <keywords matchcase="" color="">
      <word name="" color="">
      <symb name="" color="">
    </keywords>
  </scheme>
  <type scheme="sname" name="" exts="//">
    <load value="">
    <scheme value="">
    <switch type="tname" match="//">
  </type>
</colorer>


                                It finally happened - happened
                                It finally happened - ooh oh
                                It finally happened - I'm slightly mad
                                Oh dear!