Copyright (c)  1994, 1995, 2002  Timothy Rue (

  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.

    SF - process and output Sequenced File lines, with optional line editing.


   (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 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.


        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 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

        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

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.)


        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

        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

**   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)