This is a short description of script files used by the compiler.

What are scripts
----------------
Scripts are used to find and change specified patterns in the
generated assembler code. This is used to optimize (shorten) the
generated assembler and in some specific cases to customize the
code. This is a simple but powerful way to customize the generated
assembler code.

Script location
---------------
The compiler looks for the scripts in its installation directory
in the 'Script' subdirectory. Scripts names should start with 'pic'
for all PIC targets and with 'sx' for all SX targets and should have
the extension 'pat'. (for example 'pictest.pat' or 'sxtest.pat')
The compiler executes all scripts found. There is no way to specify
any sequence the different script files should be executed but if one
script file contains several scripts they are executed each after
other.

Script building blocks
----------------------
Each script file can have one or more scripts. Each scripts is constructed
from the following building blocks:

Script name (optional). Must start with the keyword 'Name:'. The name
should be in double quotes.


Debug mode. Must start with the keyword 'Debug:'. If 'on' the script
name (if present) is printed in the compiler output. The number of
found patterns is also printed.


Pattern to search. The compiler looks for this pattern and if found
it modifies it according to the'Actions' described further. The 
compiler also checks if the previous to the pattern opcode is not
a conditional one (like 'btfsc' or 'snb').
Pattern description must start with the keyword 'Pattern:' and each
pattern line must have a decimal number ended with a dot.
Also up to 16 variables may be used. They have format %v<number>%.


Actions to perform if pattern is found. Must start with the keyword 
'Action:'. There are four actions 'add', 'delete', 'insert' and
'change'. After pattern is found and changed the code is checked from
the beginning.

add - adds a line to the end of the pattern. The line must be between
      double quotes. This is the only action which is performed only
      once per found pattern.
      format:  add "line to add"
      example: add "\tclrf %v0%"

delete - delets a line.
      format:  delete <line number>
      example: delete 02

insert -  inserts one line after another. The line must be between
      double quotes. The line number after each a new one should be
      added is specified. There is no way to insert a line before the
      pattern.
      format:  insert <line number> "line to insert"
      example: insert 00 "\tincf _a, W"

change - change specified line. The new line must be between
      double quotes.
      format:  change <line number> "new line"
      example: change 02 "myLabel"


Comments must start from a new line and must begin with //

Example
-------

The script below searchs for the pattern when W is initialized with
zero and that W is copied into a register. If found the code is changed
in a way that the variable is just cleared.

////////////////////////////////////////////
//Zero initialization script
////////////////////////////////////////////

Name: "System"
Debug: on

Pattern:
00.    movlw D'0'
01.    movwf %v0%

Action:
change 01 "\tclrf %v0%"
delete 00


Assembler Comments
------------------

The comments are skipped by all scripts. This makes 'Action' numbering look
like if some numbers are wrong. In a script like this:

Name: "NonZeroTest"
Debug: on
Pattern:
00.    mov %v0% , w
01.    mov w, #%v1%
02.    mov w, %v0% -w
Action:
change 00 "\txor w, #%v1%"
change 01 "; NonZeroTest pattern optimized"
change 01 "; this line deleted"

the second action changes the code line 01 to a comment. This makes the code
line 02 be actually line 01 and the third action to remove this line will
refer now to 01.


Important notes for Scenix users
--------------------------------

Ther is one major difference in code generation for SX and PIC:

The bank instructions are inserted in the SX assembler from the beginning
of assembler generation everywhere for all variables and later the unnecessary
ones are removed;

For PIC the code is initially generated without bank instructions and later
they are inserted everywhere and than unnecesary ones are deleted.

The pattern optimization is performed for the SX target after the bank
instructions are inserted into the code (and also changed for real numeric
values) but before the unnecessary ones are deleted. So a code like this:

    bank _h
    dec _h
    test _h
    sb 3.2

during a script execution may be like this:

    bank 010h
    dec _h
    bank 010h
    test _h
    sb 3.2


This makes script developing for SX a bit more difficult than for PIC.
A pattern which optimizes code above will look like:

Name: "DecTest0"
Debug: off

Pattern:
00.    dec %v0%
01.    bank %v1%
02.    test %v0%
03.    sb 3.2

Action:
change 00 "\tdecsz %v0%
change 01 "; DecTest0 pattern optimized"
delete 01
delete 02

Note that the line 01 has another variable name. Note also that the action
'delete 01' is not necessary in this particular case as this bank instruction
will be removed by the compiler.

