ChatScript 5 Advanced User Manual -- 1 Review

https://github.com/bwilcox-1234/ChatScript/blob/master/WIKI/ChatScript-Advanced-User-Manual.md

5.1  Overview of how CS works

    CS is a scripting language for interactivity. Each time CS communicated with the user, this is called a volley.

    Volleys are always asynchronous. In CS, each volley actually consists of accepting an incoming input from an arbitrary user, loading data about the user and their state, computing a response, writing out a new stae, and sending a response to the user.

     Topic and Rules : Within a topic each rule is considered in turn by matching its pattern component. Patterns can access global data and the user's input, can perform comparisons, and can memorize sections of input data.

     If the pattern fails, the next rule in the topic is considered. If a pattern succeeds, the rule's code section is then executed to  completion ( barring error conditions ).

     A rule's code can be a mixture of CS script to execute and words to say to the user.

     Code can invoke other topics or directly request execution of a specific rule. When the rule code completes, if user output has been generated, then by default no more rules are initiated anywhere in the system. Rules currently in progress complete their code. If no output was generated, the topic continues onto the next rule, trying to match its pattern, when a topic completes without generating output, it merely returns to its caller code, which continues executing normally.

     Rejoinders :  Rejoinders are intended to analyze the specific next input from the user to see if certain expectations are met and decide what to do.

     If CS finds a matching rejoinder rule, it continues in this topic. If it doesn't, CS reverts to globally using whatever the control script dictates it try for any user input.

     User variables : Global variables whose names always start with $. it means they are visible everywhere. e.g

$myvariable = 1 + $yourvariable

      $myvariable is created if it doesn't already exist. And if $yourvariable hasn't been created, it will be interpreted as 0 or null depending on context ( here it is 0 ).

      Facts : The 3 fields of a fact are either text strings or fact references to other facts. So you might have a fact like :

( I eat "meat-loving plants" )

      you could query CS to find what eats meat-loving plants or what do I eat. 

      JSON data retured from website call are all represented using facts so you can query them to find the bits of data you seek.

      Permanent facts are saved across user interactions, transient ones disappear automatically. When you want to point a user variable at a fact, the index of the fact is stored as a text number on the variable.

      Output : There is pending output and committed output. 

      Pending output consists of whatever isolated words that are not part of executing code exist in the code. They accumulate in a pending output stream, and when the rule finishes successfully, the output is committed. If the rule fails, the pending output is canceled.

      Marking :  When CS receives user input, it tokenizes it into sentences and analyzes each sentence in turn. It "marks" each word of sentence with what concepts it belongs to.

      Concepts always begin with ~ .

      Usually concepts are explicit enumerations of words, like ~animals is a list of all known animals.

      CS actually analyzes two streams of input, the original input of the user and a canonical form of it. So the system marks an input sentence of my cat eats mice and also marks the parallel sentence I cat eat mouse, so patterns can be written to catch general meanings of words as well as specific ones.
      Memorizing : CS memorizes both the original input and the canonical form of it.

      Control flow & errors : CS execute everything as a call and return. 

      The return values are the current pending output stream and a code that indicates a control result. That result in part affects how additional rules in the calling topics or functions execute, in that you can make a rule return a failure or success code that propagates and affects the current function, or rule, or topic, or sentence, or input.

       So a failure or success down deep can, if desired, end all further script execution by sending the right code back up the calling sequence.

       When code returns the "noproblem" value, all callers will complete what they are doing, but if user output was created will likely not initiate any new rules.

       Functions : Topics are not functions and do not like arguments. CS provides system functions and you can write user functions in CS.

       Call by value : 

outputmacro: ^myfunction($_argument1 $_argument2)
{
   $_argument1 += 1
}

        Call by reference : 

outputmacro: ^myfunction(^arg1 ^arg2)
{
    ^arg1 += 1
}