
The Viewglob CVS repository is accessible from here:

	http://sourceforge.net/cvs/?group_id=116249


Preamble
--------

Viewglob looks like a little program, but it's actually been fairly
complicated to implement (certainly more so than it should need to be).
Viewglob's usefulness hinges on knowing the developing command line, but
there's no functionality within bash or zsh to present the command line to
another program.  So Viewglob fakes it by pretending to be a terminal, reading
ALL of bash's output as the user does his or her thing, and tries to isolate
command line information.

This is very hard to do well, so Viewglob's tracking is far from perfect - and
it probably won't substantially improve using this method (it's just a huge
hack).  The only good solution is for there to be a hook from the shell, but
this would require a code change to the shells themselves.  That would be
great, but it's not something I'm going to pursue right now.

Still, for general usage Viewglob is usually Good Enough at tracking the
command line; and when it fails, it usually catches up on the next command.


Overview
--------

These are the main pieces of Viewglob:

	viewglob (also symlinked at install as gviewglob)
	 - A bash script which parses the command line flags and config file,
	   validates them, and passes them along to seer.

	seer
	- The engine; when called, this program forks two shells connected
	  through pseudo terminals.  The user types in one, and seer uses the
	  other as a "sandbox".  Seer examines all data coming into and out of
	  the user shell, looking at different times for different groups of
	  character sequences (some of which are general terminal sequences,
	  some of which are placed by Viewglob as semaphores).
	- When seer finds the command line, it tries to track changes to it by
	  watching changes in the terminal, NOT by emulating the shell (that
	  would be a lost cause).  Every time the command line changes, seer
	  submits it as an argument to glob-expand in its sandbox shell.
	- Seer also forks the display, gviewglob, which it connects to with
	  two fifos.  One of the fifos is used to pass data from glob-expand
	  and the other is used to pass non-glob data (such as the command
	  line or navigation commands).  Two fifos are required because
	  otherwise the glob data can bleed into the command data, because the
	  sandbox shell's timing is unpredictable.

	init-viewglob.bashrc
	init-viewglob.zshrc (installed as .zshrc)
	- Initialization files for the shells forked by seer.  These try to
	  "harden" the sandbox shell, and insert Viewglob semaphores into the
	  user shell.

	glob-expand
	- A little program which examines its arguments (which are from the
	  developing command line as expanded by the sandbox shell) and prints
	  to stdout the listings for referenced directories, showing file
	  selections and predicted name completions.

	gviewglob
	- The display, written in GTK+ 2.  Basically this makes graphical
	  representations of the glob-expand data.

Only the viewglob shell script is callable from PATH.


Source Files
------------

seer:
	sequences.c, sequences.h, circular.h
	- Defines "sequence groups" for each "process level", which are defined
	  only for Viewglob's purposes.  The sequence group for PL_EXECUTING is
	  checked against while Viewglob has not located the command line
	  (usually after a command has been run) and PL_AT_PROMPT while at the
	  command line.  These are mostly differentiated for performance
	  reasons (the PL_EXECUTING sequence group is much smaller than for
	  PL_PROMPT) and to decrease the chance of hitting false positives.
	  A sequence match in a sequence group can modify Viewglob's command
	  line, remove itself from the buffer (so the destination never knows
	  it's there), and/or change the process level.
	- Determining which sequences should be in each process level has been
	  done completely based on what I see the shells spitting out.  That
	  is, I don't check for any terminal sequences which I haven't seen
	  the shells use.  This means if your shell usage is substantially
	  different from mine, Viewglob may be less accomodating to you.
	  Improvement here requires feedback.
	- I don't use regular expressions for the sequence matching, but I
	  wish I could.  The problem is that regexes either match or don't --
	  there's no "in progress", which is necessary for knowing how much of
	  the buffer you need to keep track of at any given time.
	- There's a big list of terminal sequences in the rxvt package located
	  in docs/xterm.seq.  Very helpful in figuring out what the shell is
	  doing.

	buffer.c, buffer.h, circular.h
	- There are buffers for output coming from the shell and for input
	  coming from the terminal.  The terminal buffer only uses the
	  PL_TERMINAL sequence group (which is the Ctrl-G stuff).  The rest
	  are for the shell buffer.

	cmdline.c, cmdline.h
	- Viewglob's representation of the shell's command line.  This should be
	  as close as possible to the true command line.  It's modified based on
	  different sequence matches (or lack there of).  Ideally all calls to
	  modify the internal command line should be isolated to sequences.c,
	  but right now they're all over the place.  Kind-of messy.

	sanitize.c, sanitize.h
	- When prompted by seer.c, creates a "sanitized" command line based on
	  the cmdline.c command line.  This removes dangerous constructs such
	  as history expansions and compound commands.

	children.c, children.h
	- Concerned with the forking of the shells and the display.

	hardened_io.c, hardened_io.h
	- Wrappers for the read(), write(), and select() systems calls to ensure
	  atomcity and to account for signal interruptions.

	viewglob-error.c, xmalloc.c, viewglob-error.h
	- Memory allocation convenience functions and error reporting.

	ptutil.*
	- Portability wrapper for pseudo terminal stuff.

	tc_setraw.*
	- Sets and restores raw terminal mode, which is required to effectively
	  read user input.

<WORK IN PROGRESS>

