HOW TO USE SCHEMA.
Archive. Probably ... it is related to revision 1.
theoretically, ss-engine schould be able to make translation between any algorithmic languages;
to tune engine, you need to describe from-to translation rules in the schema;
schema
is a text file with following structure:
[text]
[schema_header]
\\schema
states_block
[states_block]
[states_block]
.....
\\schema end
\\file end
text can contain any comments excluding word "\\schema"
and schema_header keyparameters;
schema_header
used to tune schema parameters
schema_header structure:
keyparameter=value
[keyparameter=value]
[keyparameter=value]
....
examples
keyparameter=value strings
:
\\system escape="-"
\\event escape="."
\\debug schema=true
states_block
has following structure:
pre_states [indent dialog_string]
[indent dialog_string]
[indent dialog_string]
.....
indent
is a "space_separator"; and is a not empty set of tabs and/or spaces
schema describes rules of state-machine (ss-engine). As a state machine,
ss-engine can be in different NESTED states in which some events can be accepted from the
imput stream; for example, if ss-engine is parsing typical brackets expression: ((a-b)-(c(f,c))),
such states are (,(,a,- and so on;
events may cause actions which output text to output stream;
pre_states
is a sequence of states at the end of current nest separated by comma;
for above example, it can be (,a ,or a or (,(,a ,or a;
dialog_string
describes coming events, actions, and post-states, post-events, and other post-elements;
dialog_string syntax:
event action shift post_elements
(indent used as a separator in above string)
shift
is a number which tells how to change state machine position along current state nest;
for example, encountering next opening bracket in above example may add one state "("
and increase this position by 1
shift may also be 0 or negative;
post_elements syntax:
[post_states] [\feedback] [+[event]] [`text_to_output`][..x][' comments]
indent must be used between elements in above string;
post_states
(if present) must go from the beginning of post elements;
events in this string create a queue which is inserted between the end of current action,
feedback and coming event;
x
is a macro which can be any letter from a-z; macros accept output stream; in other words, you can
use macros to split or rediect output stream and creates pieces of text which you can use later
in schema to build a final text;
it must be much easier to get used this schema syntax by trying examples;
ss-engine parses tockens from input text; by default, characters with ascii < 33 used as separators;
any thing between separators is a tocken and generates event with reserved name ".id" (identificator);
each event has tocken, tock(which is an event name);
default separators do not generate events for them self; however, you can include your own separators
in the schema which will have their own events; simply putting any name (like !a5.4R ) as an event will register
this event, and it will separate tockens;
as it can be seen now, any tocken has name .id
however, you may have tockens which have their own names; let us call such tockens as keywords;
to mark a tocken as a keyword, use underscore before it and put it in the place of event;
for example, _!a5.4R will generate and event with name !a5.4R, but this keyword will not be used as
a separator;
Events denotation.
Names starting from events escape char, for example, .my_name, are reserved in the schema.
`.` is an escape char in this example. This means that if string `.my_name` is found in the source
text, this won't be considered as any keyword or token and won't cause any event. However, user
may reserve this event by putting `+.my_event` in events queue.
If you like to establish event `.` in the source text, it can be done by escape sequence: `..`.
Actions
usually occupy a second column in events rows.
If actions escape assigned to `.` then:
.t - stands for printing a currrent tocken
. - skips action
.. - means that following imbedded short script command will be performed
Imbedded script actually can include imbedded subroutines and imbedded assembler.
examples of imbedded subroutines:
..tocken#p : changes current with tocken = p & tocken
..tocken_#p : tocken = tocken & p
...
Case "_tocken_": tocken = p & tocken & p
Case "tocken_i": If ttype = "i" Then tocken = p & tocken
Case "tocken_i_": If ttype = "i" Then tocken = tocken & p
Case "save": how_to_save = ".," & file_to_save ' & "," & ttres
Case "reengine": how_to_reengine = p & "," & file_to_save
Case "redirect": how_to_redirect = p
Case "debug": set_debug
Case "debugoff": deb = False
Case "pdebug": pdeb = True: set_debug
Case "pdeboff": pdeb = False
Case "stope": stope p - raises error with error description = p
..replace_in_tocken#key#replacement#
As soon, as process is in a program mode (imbedded script mode, the only way to leave it is
to set event name to any character except `.` or `'` (schema comment char).
Program mode
is a simplified mode for action. In other words, ss-schema allows two modes:
normal and program mode. An example to toggle in program mode:
-a
.some_name some_action 0 + 'sign plus toggles to a program mode
. statement1
. statement2
. =x,2
' this is a comment; it starts from `'`
e . 0 - 'any character different than `.` an `'` toggles schema back to normal mode
String with `e` must have normal mode syntax, so for example aciton must have its escape chars `..` in the string `e` which are skipped in program mode statements ...
In program mode, `..` in action field must be omitted
Imbedded assembler
includes:
operations: "+", "-", "*", "/", "%"
syntax:
@oper1[,oper2] where @ - operation as above
@ is "=", "&", "[", "]", "(", ")", ".", ":"
oper1 - variable or variable keeping index of element in stack ; not a constant!
oper2 if present is a variable or constant
constant is a 9897[%|#|& ..] or "string ... " ; modifiers %,#,& ... are not yet implemented ...
. - offset accepts value of oper1
: - segment accepts value of oper1
[ - stack accepts value of oper1
] - oper1 accepts value of stack
( - offset accepts value of oper1
) - oper1 accepts value of offset
vvv which is a built in array of variables must have the same type "string" now. In the case of ASP engine
version, this type must be preset for every element ...
to debug dialog, action = ..debug
to debug assembler = ..pdebug
to set segment to 33 = ..=sss,33
to set offset to 45 = ..=fff,45
Example of assembler code:
-a
.initiate_begin . 0 +
. [sss,nest
. +tip,1
. =sss,tip
. +nest,1
. =x,0
e ..(x,9 0 ' make rel. stack 9 equal to 0
Events Queue
`internal event escape` (usually `+`) allows to add more events which will be performed right after this string
+.d - stands for defer; puts current event in the queue; it remembers tock, tocken, ttype;
this is only a0 built-in shortcut in events queue part which memorizes them; most of queue shortcuts
just add the name of event in events queue like in the following example:
+.id - generates event with the name `.id`; current tocken and ttocken will be used for this event
Feedback
`\\feedback escape` (usually \) escapes a feedback command performing right after event was performed
\i stands for indent
\lf stands for line feed
\.. `closes all macros`
\uptoX enforces source file tokenizer to read every thing from the next character to character X (excluding char X itself)
\exit - terminates dialog
Done:
action: .`output to console ..a ..\r..\n - these macros work also, do not use . . . together . . .`
."outputs to result file; all works also"
Future modifications:
in schema \\disable delimiters option like \n\r needed
improve VB.Menu in a top bar which is aready done ...
allow shoft syntax option allowing states which do not have any events?
Known bugs
version 1.0.0 had a bug: when dialog_string was on the same line as pre-states,
it caused to register extra and wrong states;
this bug is fixed in the current release 1.0.1;
other bugs - none; your help is required here ...