Copyright (c) 1994, 1995, 2002 Timothy Rue (3seas@threeseas.net)
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the file fdl.html
-------------------------------------------------------------------------------
(SF) Sequence-Focus, Sequenced-Files.
Brief:
SF - process and output Sequenced File lines, with optional line editing.
Specific:
(SF) Sequence-Focus - The concept of Sequence-Focus is to access and control
the typical "grab the next line of the active sequenced-file", process
it for VIC variables and commands, then pass it (or its return values)
to the device, program, program-port, etc. as set by OP, when there is
something to pass on (not totally consumed by SF processing.)
SF has options to step through the processing of SF file lines and to
limit processing. The ability to allow the user to directly alter the
line being processed and at the different steps in the processing of the
line. The user can insert lines to be processed before and/or after the
current line, and use SF in interactive mode (no SF file being
processed). The option to send the line(s) to a file (tee) with or
(redirection) without sending it to the OP defined device or program.
All this can be done through PK setting the SF-LPC (Line Processing
Control) flags.
SF-LPC flags
------------
A - auto-processing (default)
S - step-processing (S = S1)
S# - Step Processing and level of (optional).
(additional levels yet to be determined)
I - interactive mode = S0 (Step processing is inherently interactive but
at '0' level SF processing doesn't step, but only prompts user for
a SF line to process when it has nothing to do. It does not step in
processing the line.)
E - enable SF processing (default)
B - bypass SF processing (IQ/ID out is directly to OP setting direction)
D - disable SF processing (Suspends SF leaving AI processing available)
+/- Variables: +V variables (default), -V don't process VIC variables
+/- Commands: +C commands (default), -C don't process VIC commands
T filename - tee to file (append to file)
R filename - redirection to file (append to file)
A keyboard key combination (Ctrl-P) can be used to toggle step and auto
processing. It is also possible for an SF file line to select the
processing mode, through a PK command call.
To clearly understand the limitation of SF and PK abilities to alter
the sequence, understand that SF only processes the current line for VIC
variable and commands, optionally with user interaction, before passing
what remains, to the device, program, file, etc. defined by OP. PK, in
altering the SF stack, only alters the coming sequence of files and/or
their next file line number(s) that SF processes. SF updates the PK
files SF stack to the next line to be processed.
First variables are processed to replace variable names with their
values. This happens in a recursive manner so multi-depth variables can
be found and again processed to get to their final value. Then the line
is checked for VIC commands. If VIC commands are found, it executes the
commands and passes any results to the output (as defined by OP.)
It is possible to tell SF not to process VIC variables and/or commands.
(say you want to use Csh "foreach" to call a VIC command, you'd need a
way to escape or pass the VIC commands, and perhaps variables, past SF
to Csh processing.)
"SF" files:
The input SF file(s) can be stdin, a pipe, port, etc. type of temporary
file, as is generated by IQ/ID output, or external program such as
another VIC, where the tee/redirection to file output can be directed as
input to another VIC SF command processor.
The sequenced files can be any text type files. Generally these files
would contain commands for the VIC but would also contain lines for
other programs or output objectives (auto-composing content.) Since what
is not totally processed and consumed by the VIC, is passed to the
output as determined by "OP".
Variables:
Variables are handled in the typical shell manner, where using a '$' in
front of a variable name i.e. $varname will access the variable content
and an escape character '\' to allow the use a '$' as a normal character
rather than a special character, i.e. '\$test' will output '$test'. This
way it is possible to create a variable having content containing
'$variable' or multi-depth variables.
Command Processing:
It is possible to have more than one SF-line, for SF to process in
sequence, per console line-string by using a semicolon ';' to separate
or delimit SF lines to process. It is thru the use of this ';' delimiter
that the user can insert a line for SF to process before and/or after
the currently being processed SF line. But in doing this the next "step"
will only show the first "line to SF process", while what follows is
buffered (not lost.) However, The SF running Stack "filename@line#" does
NOT consider such a "multi-SF line as being more then one file line
(because in the debugging process the line number needs to be the actual
line number in the named file, not how many "SF lines" there are to, or
have been, processed.)
Redirection input '<', output '>' and pipe '|' are also available.
This way it is possible to make a variable contain the returned values
of commands such as the PK commands, that return the PK file lines or
fields. And to then use such variables to reset such PK file content
with PK commands using these variables. See above about variables and
the OI command.
Of course in finding a VIC command the given command function is called
with the given arguments. If a VIC command/function does not yet exist
(i.e. IQ, ID and KE commands) there should still be a dummy function
call to act as a place holder for that command/function parse tree for
when they do exist.
SF Line editing:
As a minimum, the ability to place the cursor anywhere in the SF line
contents and use the typical insert/delete(overwrite) mode of editing,
as well as typical cut and paste abilities. Of course having typical
intelligent shell line editing capabilities and even history can't hurt.
While in step mode, as each line is stepped through, variables being
replaced with their values and piped commands being done in sequence,
the user is allowed to edit the line, but in any case the user is
required to hit the return/enter key to cause the next step to happen.
SF GUI/UI:
The SF user interface for a VIC instance: As a GUI, it may be listed in
an overall VIC AI GUI system list, iconified onto the desktop, sized
just for minimum SF user interaction, or full debug/watch of various
elements but typically watch, step, and edit of the current files used.
Of course a lot regarding such a GUI has to do with the GUI system being
used. Python itself contains no GUI system though Tcl/Tk tkinter is
considered a standard gui system for python, it is not available on all
system Python is available on. Because of this it is important to
make/have a console based user interface as well as generate such output
that a GUI interface can make use of to produce what is mentioned above.
If this VIC system was to only run one instance of a VIC then handling a
console interface would be rather simple and straight forward. But that
is not in the versatility scope of the VIC. Considering several possible
solutions to the problem, from using python os.module to start up a dos
level shell running another python interpreter for each VIC instance, to
using fork(... uh if there is no spoon, there is no fork() usability in
one system named squeeeeeek...windows...) but then there are Threads....
But still, how to manage output from multiple VIC instances with the
possibility of one or more set to watch/debug, step and/or user
interactive mode?
What to do here? A little of both? The use of two consoles/shells, one
specifically for requested and error information output, the other
specifically for user input, editing and stepping of SF line processing.
The use of threads to keep overhead down, interpreter locks to control
sequence focus, and pipes to redirect selected output information to the
output console....?
As a shell/console interface (non-gui) what we are probably better
working from is the AI priority level or just above the VIC instances
of whatever number of SF processor might be running. We can better
manage multiple VIC instances information output and user input through
the common AI processing level, which would in turn interact with
whatever GUI system we might decide to use. User Input/Editing having a
single input console interface...(we only do one thing at a time anyway)
... we need a way "Focus" to the VIC instance we want to work with at
the moment.
We can instruct each VIC instance to output whatever degree of
information we want, i.e. Full watch/debug ... from watching PK file
changes, OI file contents and changes, KE file contents and changes, SF
processing, error out, etc.) to no output, etc.... When this information
is being output to a single console, each output line begins with the
VIC instance identifier responsible for the information. That is the VIC
instance identifier as determined/set at startup of each VIC instance
(See AI and the first field of the PK files AI: line).
To interact with a specific VIC instance, use the command:
SF AI-name.number
Which will set the input/editing prompt to the specified AI-name.number
and focus on interaction with named VIC instance and watch and error
output.
To change the focus, issue the command again but with another named VIC
instance identifier or the command:
SF AI
which will bring focus back to the overall, again outputting requested
information from all VIC instances.
Debugging tools for what the VIC system processes:
Given that any number of things may be processed by the VIC system and
there has yet to be established enough use "experience" of the VIC
system, it is not possible to really determine what useful functionality
to include at this time. A lot may be determined based what GUIs are
created, what information they would find useful and what information/
data they might generate for VIC use.
With these unknowns in mind, the current command options of SF will be
limited.
SF Commands:
------------
SF AI level options (**):
-------------------------
SF AI AI-name.number
Sets interaction focus to given VIC instance.
SF AI
Sets interaction focus to total VIC system.
SF VIC instance level command options:
--------------------------------------
(Available only in VIC instance level as set above, ** unless otherwise noted)
("output" is always to output console, unless redirected.)
SF
Outputs PK SF running Stack line.
** SF -?
Help on SF (help the same way as found in the AI and PK commands)
(**Allowed in AI level)
SF -r
Outputs "contents" of current top-of-stack SF-file@line#. (look ahead,
as the top of stack shows next line to process.)
SF -r#
Outputs "content" of current top-of-stack SF-file@line# up to the # of
lines given. i.e. "SF -r12" will output the next 12 lines of SF-file
stack.
NOTE: This does NOT advance the line# or alter the stack of the SF file
being processed, but only outputs/shows the contents of the given count
of next SF stack lines to process, regardless of which files on the
stack they may be.
** SF filename@line# (opt. -#)
Outputs given filename@line# contents. If opt. -# is used then range of
lines will be output. Range starts at line# given otherwise first line
of file and outputs lines up to the -# of lines given or end-of-file,
which ever comes first. (**Allowed in AI level)
SF -w item,..
Cause a watch of given item(s) in current Focused VIC instance.
A single item may be an individual item like a single variable or a set,
such as the complete current OI file content. i.e.:
SF -w IO:variablename, IO:variable2 - will watch these variables
SF -w IO: - will watch the whole list, IO-file.
Upon setting for a full list, the full content of the item is output,
after that only what is changed is output. i.e. even if the full set
of OI variables is to be watched, only those variables which have been
changed are output to the output watch console, along with their new
values, which can be a messages stating the variable has been removed.
If the OI file is changed then that to is noted on the output along
with new file and list of variables and their content. This as well
applies to PK files and KE files, but NOT IQ, ID or SF files as these
files can be far to large to watch, but their listing/change in the PK
file will be noted.
** SF -W item,...
Cause named item(s) to be watched in any VIC instances it exist in.
(**Allowed in AI level)
** SF -W AI:AI-name.number/item,...
Watch on item(s) in given VIC instance. (**Allowed in AI level)
SF -wr
Outputs the full watch list of current focused VIC instance and their
values.
** SF -Wr
Outputs full watch list and values of all VIC instances.
(**Allowed in AI level)
SF -wr item,...
Outputs item(s) of current focus VIC instance and their value(s).
** SF -Wr item,...
Outputs item(s) in full watch list and their value(s).
(**Allowed in AI level)
SF -wc
Clear the watch list of current focused VIC instance.
** SF -Wc
Clears the Complete watch list. (**Allowed in AI level)
SF -wc item,...
Clears item(s) from watch list of current focused VIC instance.
** SF -Wc item,...
Clears the complete watch list of item(s). (**Allowed in AI level)
** SF -wc AI:AI-name.number/item,...
Clear watch list of given VIC instance item(s) (**Allowed in AI level)