Script2Script Help Documentation.
================================

Free for distribution and reproducing in whole or in part
as long as this copyright notice is retained on all copies:
Copyright (C) 2003, Pharmease, Inc. Author: Konstantin Kirillov.


READABILITY
===========

  Monospaced fonts (like Courier New) and "no wrap" text mode are recommended to
  view this text.


INSTALLATION
============

  After running setup, folder "examples" should be moved to
  application folder (usually "Script2Script") if it is not already there.


INTRODUCTION
============

  Script2Script (S2S) is a program designed to parse, convert, or syntax-check simple scripts. 
  S2S comprises Compi (Script2Script.dll) and Graphic User Interface to Compi (S2S.exe).
  Compi is a Finite State Machine which does actual conversion. 


CONCEPT
=======

  Compi interprets input text as a sequence of text fragments, tokens.
  There are two types of fragments: words and separators which separate words. 
  This phrase is an example of text: space characters are separators and words are fragments.
   
  From Compi's point of view, tokens are events which Compi receives from outside world.



WHAT IS SCHEMA
==============

  As a FSM, Compi needs to know what to do with tokens, 
  so one can give Compi a set of instructions which called schema here. 
  Schema is written in Compi's Script which is a simple language understandable for Compi.

    - Schema tells Compi how to accomodate its Eyes to recognize different
      separators and other types of tokens. 
    - Schema gives rules for Compi how to produce output text. 
    - Using schema, programmer can change Compi's perception of input text as
      to tell Compi to recognize numbers or ignore case.




HOW TO WRITE SCHEMA
===================

  Compi's startup state is "root" state which is denoted "-r" in schema.
  When Compi is in some state, say "-r", and "event" happens, 
  and programmer wants Compi to do an "action", 
  this can be written as simple schema instruction:
 
       -r event action

  This format is basic format for all Compi's schemas. 
  All schema syntax modifications and generalizations 
  are built around this format: "state event action".

  Before starting its work, Compi reads, Compiles, schema.
  Later, when Compi executes a source text and encounters an event
  which matches the pattern "event", Compi executes "action".

  "action" can be not only a single action, but list of 
     actions, 
     actions wich generate event (=event-actions),
     and actions which generate state (=state-actions).
  This list, queue, can be written in one line, or
  continued to next lines.
  
  With more details, schema-line syntax is:

       nest event-pattern queue

  White separators between this three parts are required.
  No indent can be put before nest.
  Event-pattern can start on new line, but in this case,
  it must be indented to be not interpreted as a nest.

  When event happens and Compi reads schema to match this
  event, the first found event-pattern will be used.
  For example in schema,
      
    \\-  hello "Compi is busy."
         hello "Ready to help." 

  string "Compi is busy." will be printed when separator
  "hello" is encountered in the text.

  Precise description can be found in syntax_of_schema_help.


  NEST can be a complex Compi's state:
  ------------------------------------

      state1,state2,state3, .... 

  Why is "nest construct" used? In "real world" state can be considered as a tree of
  simplier states: 

       when Compi parses a phrase "if (x+1)>y then", Compi enters 
          state "if - statement",  then 
              state "condition", and when parsing expression "(x+1)", Compi enters the 
                  state "expression", so at the third step, Compi is in the nest
 
      "if - statement","condition","expression".



  QUEUE 
  -----

  Time order of actions in queue is the same as they were read: 
  actions from the left processed first. 
 
  "Action" can result in generating a new event or triggering Compi to the new nest. 
  In this case terms "event-action" or "nest-action" will be used correspondingly.

  Therefore, queue is a sequence of normal-actions, event-actions, and nest-actions.
  For their complete syntax, please refer to syntax_of_schema_help.txt.

  Compi generates event-actions internaly for himself. If event-action triggers
  its onw queue, then this queue is inserted into the "parent queue".
  Total "parent queue" called global-queue here. 

  Events which come from Tokeneyeser are called external-events. 
  When event-action is fired from global-queue,
  Compi makes "no difference" between external-event and fiered event-action.


  VARIABLES
  ---------

  Compi has own memory: variables where programmer can store data. 
  Some variables provide access to token, type, or direct access to input text. 
  Some simple operations are allowed with variables.

  More details are in the file syntax_of_schema_help.txt.

  ***

  Perhaps the best way to learn CompiScript is to follow examples
  included in installation package.