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


*** THIS TEXT IS NOT CURRENT - Provided only for historical reference.

---------------------------------------------------------------------

      |                (IQ) Index-Queue                        |

             IQ - select arguement word definition(s) and output

    (IQ) Index-Queue - The concept of Index-Queue is that of search and
            output. This command has similarities to other search type
            programs (Csh search, grep, etc..), having flags and pattern
            matching wildcards. Also similiar to the Csh "man" command in
            that it can output several consecutive lines from one match.
            But there are some important overall differences. It has
            sub-search abilities of two flavors. One of sub-file, and one
            of sub-definition. KE plays a part in the sub-search choices
            or direction. There is a temporary internal list of files with
            "path, name, date, and time" kept to assist in preventing
            searching through what has already been searched.

            To understand the search and sub-searches consider the IQ
            argument as a word-key to match with a word-keyhole in an
            IQ-file. The IQ-file may also contain file-keyholes and
            definition-keyholes. Again this will clear in understanding
            KE.

          * The objective of the three different keyholes is to allow
            infinite search depth and constraint versatility. Minimum use
            is always best (keep it simple) but use is not limited.

            The successfull search possibilities are:
       -----------------------------------------------------------------
         A) File-keyhole match. (continue search in an additional file)

            A file-keyhole is found in the current IQ-file and a matching
            file-key is available, so the file is made the current IQ-file
            and the search continues in this current IQ-file.

         B) Word-key match. (output definition)

            The word-key finds a match within the current IQ-file.
            There are no file-keyholes or definition-keyholes, so the
            definition is output.

         C) Word-key + definition-keyhole match. (output definition)

            The word-key finds a match within the current IQ-file.
            There is a definition-keyhole and an available matching
            definition-key. The definition does not contain a file-keyhole,
            so the definition is output.

         D) Word-key + file-keyhole match.
            (continue search in an additional file)

            The word-key finds a match within the current IQ-file.
            There are no definition-keyholes but there is a file-keyhole
            and a matching file-key is available, so the file is made the
            current IQ-file and the search continues in the current.

         E) Word-key + definition-keyhole + file-keyhole match.
            (continue search in an additional file)

            The word-key finds a match within the current IQ-file.
            There is a definition-keyhole and an available matching
            definition-key. The definition contains a file-keyhole and a
            matching file-key is available, so the file is made the
            current IQ-file and the search continues in the current.

            --------------------------------------------------------
             Once a file has been searched then the search picks up
             where it left off on the previous file.
            --------------------------------------------------------

         F) If no match was found it is possible to have a "match any
            word" definition at the end of the first file and optionally
            based on a variable *CLASS* tag. This way a default can
            exist.
        -----------------------------------------------------------------

            As you can see, a file-keyhole can be in the place of the
            word-keyhole and definition-keyhole (both non-keyed and keyed).
            But the word-keyhole and definition-keyhole have only one
            position.

            There are a few (default) rules on keyhole placement in an
            IQ-file.

        a)  All keyholes must be on a line by themselves with the two
            following exceptions:

         1) The file-keyhole is followed by the filename which is separated
            by a semi-colon. The semi-colon is preceeded and followed by
            at least one space.

         2) Keyholes are preceeded by one or two consective colons
            starting in the first column followed by at least one space.

        b)  The word-keyhole line starts with a single colon.

        c)  The definition-keyhole line starts with two colons.

        d)  The definition lines have no preceeding colons.

        e)  Comment lines start with three colons.

         3) *CLASS* tags (optional). For the file-keyhole the *CLASS* tag
            follows the filename with a "semi-colon preceeded and followed
            by at least one space." For word and definition keyholes the
            *CLASS* tag follows the keyhole with two consecutive
            semi-colons that are preceeded and followed by at least one
            space.



             ***** These rules can be altered by the KEy flags. ******



             Unless flagged (IQ flag) to go to a file first, output is
             to SF, a line at a time and "IQ@LINECOUNT" is added to the SF
             filename stack.

             Only one IQ/ID command per AI can be running at a time.
             But if SF finds an IQ/ID recursive call it gets PK to make
             a copy of the PK file (including the internal list of files
             searched - appended to the PK file) and proceeds with the
             recursion. Making the original the previous PK file. Upon
             completion returns to the previous PK file and picks up
             where it left off. NOTE - This action is an assumption the
             VIC makes when the IQ/ID definition writer (a user) fails
             to plan otherwise or intends to use the assumption.
                      Any call of IQ or ID from within an IQ or ID
             definition is an obvious recursion. Because IQ and ID are
             so similar in search and definition processing, and there
             are other ways for the definition writer to deal with and
             control this type of recursion, IQ and ID are considered
             the same command in regards to IQ/ID type recursion. The
             VIC assumption lets processing move forward and can be
             used creatively.

             When the internal list of files searched is temporarly
             appended to the PK file, it is read back to internal and
             removed from the PK file when the file again becomes
             current.

             With the option to send output to a file first, if no
             filename is given a temporary file (IQ##AI##.tmp) is used.
             It is up to the user or SF script to do something with it.
             This file(s) will exist until the next "zero level" IQ
             search from the given AI, so user/SF might want to rename
             it upon IQ completition.

             The output file is commented so the user can see exactly
             where the information came from and how IQ got to it.
             Comments come from copying the IQ filename line in the
             PK file as well as from the matching keyholes in the IQ
             file. Comments are not passed by SF (even if SF is
             disabled) so SF can be used as a comment filter if needed,
             but comments are passed by the SF tee to file flag.

 "IQ" files
------------------------------------------------------------------------
::: comments and headers

:

: word-keyhole
                 class-x looks to see if var class is related to class-n
:; class-x (or *CLASS* which looks to see if the class exist in KE file)

: filename-keyhole ; class-x ; filename

: filename-keyhole ;; filename

:; class-x ; filename

:;    <- looks at class in var then if not exist in KE-file

        if var has no key but KE-file has ";;" then

:;; filename


-------------


::

:: definition-keyhole

::; class-x

:: filename-keyhole ; class-x ; filename

:: filename-keyhole ;; filename

::; class-x ; filename

::;

::;; filename
----------------------------------------------------------------

IQ

     IQ                             returns PK IQ line.

     IQ -?                          help on IQ

     IQ -iq                         returns IQ search path based on
                                    KEychain.

     IQ -iq word                    returns IQ search path based on
                                    KEychain and word

     IQ word                        Searches for word using KEychain
                                    access and executes line_contents
                                    commands based on KEychain teeth
                                    and OP set.

     IQ -c word                     Cancels word/line_contents from
                                    file(s) using KEychain access.


     IQ -c word line_contents       Creates or Changes word/line_contents
                                    using KE keychain access for search.
                                    If Creating it will add to the end of
                                    path - end of path is end if first
                                    file.