July 27th 2003 -- Timothy Rue <3seas@threeseas.net> Write README file to include: * to Use the python coded contents of this archive simply copy the main VIC directory and it's recursive contents to some location on your system. Enter a shell or terminal (mac) and CD to the directory containing the code you want to run. Assuming Python is in the general system path, just enter: "python" with the iq.py or id.py or main.py (kingsley code) application arguement... * details about writing iq/id files (following) Actually the details are quite simple (sample files are provided): an IQ/ID files first line is optionally "filekey word: sub: file:" Where the tags "word:" "sub:" "file:" can be any set of character sequence but separated by a single blank space with nothing else (other than the first word "filekey") on the line. i.e.: filekey cat dog bird If this "filekey" is not present than either the builtin default "filekey" will be used (filekey word: sub: file:) or the "filekey" of the file that pointed to this file (via the "file:" tag. Then these "tags" are used throughout the file, starting at the first column and followed by a word, sub and filename (respectively). "word" and "sub" can be blank, but the file tag needs a valid filename. i.e.: --------- catmeow dogbark birdtweety --------- or --------- word:meow sub:bark file:tweety ---------- What is then important is the information or data that is placed after each tag (for "file:" it's the contents of the file it points to). i.e. ------file animal.iq contains--- word:meow kitty wants attention sub:bark Rover gives kitty attention sub:growl Rover bites kittys tail file:tweety (search/test continues in the file "tweet" then picks up where it left off here) ---------end of file ----- -------file tweety contains----- tweety sings -------end of file-------------- How this information is use by IQ/ID is that these tags tell IQ/ID how to read the file in it's searching or testing of the arguements given to IQ/ID on the command line. I.E.: (note "-s" is a flag to suppress tags from output) >Python iq.py -s animal.iq meow growl will output: > kitty wants attention > Rover bites kittys tail > Tweety sings whereas >Python iq.py -s animal.iq meow bark will output: >kitty wants attention >Rover gives kitty attention The contents after a tag can be multipule lines and up to the the line before the next tag. You can also output a list of tags in a file ("*" is a wildcard that selects everything) >python iq.py -k animal "*" "*" will output: >word:meow >sub:bark >sub:growl >file:tweety >total 4 So that you can see what "keys" the tags point to. That's a Quick Start in using IQ. ID is similiar except for instead of pattern matching the word or character string following the word: tag, the follow8ing character string is a test to perform on the arguement (word) given on the command line. Simply provide no arguements to either iq or id to get help information on command usage. ie, >python iq.py NOTE: IQ and ID are not part of the following "Kingsley code" at this time, and I consider the IQ and ID code to be stable enough for general use. NOTE: about the iq/id "-e" (execute) command line flag/option. If used with the above examples and you have following the tags, the path/name of programs or commandlines (instead of the text above), then those programs/commandlines will be run. This might even be ">Python iq.py ......" recursion.... This should provide a idea of the automation ability of IQ/ID as well as the VIC. * BETA Status of VIC integrated - "Kingsley code" Although I hired Kingsley to produce the code for four of the commands (AI, PK, OI and SF) and was happy to give him bonuses for doing it (and will offer him the opportunity to do more), I consider the current code to be in "beta" state. A great deal has been accomplished in the way of producing VIC functionality, but it's not all there and some things don't work quite as desired. I also need to learn Python Object Oriented Programming at least well enough that I can make minor corrections and follow the code so to do some verification (also cross platform compatability is an intended goal having minor problems to deal with.) However, there is usable functionality there now, only limited, so don't be afraid try things out that you find in the documentation. It may be more interesting to get a grip on IQ and ID first and then consider how the rest of the VIC can expand upon the use of IQ and ID. The filename to provide as an arguement to Python is "main.py" in the "VIC/vic/" directory. But be sure to set/edit the vic.rc file. vic.rc - a user editable configuration file to set the VIC "HOME" and "rooms" directory paths as well as the directory where the help files are, and browser path. The VIC is an interactive shell like program. * AI,PK,OI and SF documentation needs to be cross checked with back and forth coding communication (and code) to correct any inconsistancies in docs/help files (ie, the AI -s switch was in part changed and replaced with SF flag use). The VIC help files are copies of some of the vic html files. * Due to python compiling into byte code, it's important to install the VIC in a writeable media (burning a CD won't work unless the bytecode has already been generated for the given platform (and version of python ??) * What's in the directories? VIC (dir) readme-todo.txt (this file) html (dir) (html based information files regarding the VIC) (To use Start with index.html) pics (dir) (a couple pictures used in the html pages) IQ-ID (dir) (the python coded stand-alone[*] programs iq.py and id.py and some related iq/id files) [*]-still need the Python interpreter but no other vic --.py files are needed to run either of these.) vic (dir) (the multi-file python code for an integrated VIC system and a "vic.rc" user editable configuration file.) home (dir) (besides some test files it is here where the vic creates rooms for instances of VICs - if the vic.rc file is edited to have this "home" directory as the home path) AItest (dir) (some simple files used in testing) help (dir) (the basic set of html files regarding the VIC commands duplicated here for VIC access - if the vic.rc file is edited to point to this directory for the help files) doco (dir) (text generated in the back and forth communication between myself and the coder I hired to produce the vic code. May be useful as a reference.) VICtest (dir) (the beginnings of some scripting of tests for AI, PK, OI, and SF to test the code against. Probably of little interests as there is more extensive tests above in the "home" dir.) * Add example and useful iq parseable files and word dictionaries. Some may be found in the IQ-ID directory. Note for making a CD that contains .iq, .id files... **** A Mini CD has 210 megs of space, that's a lot of text!!! An estimated single file size of a converted PHP manual would be around 5 or 6 megs, though a multifile PHP manual would be more space, it still would be well under 20 megs, probably under 10 megs. **** A businesscard CD has about 50 megs of space.