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.