This directory contains a Tcl/Tk front-end to Thor.

Starting Up
===========

Starting up a browser with its own private front-end
	browse -f browse.tcl

Starting up a browser and connecting it to an existing front-end
	browse -f browse.tcl -fe [hostname]:port

Debug mode (display interactions with the front-end)
	browse -f browse.tcl -debug

User Interface
==============

Left mouse-button in object header
	Toggle object between a small view and an expanded view

Left mouse-button in a method name
	Invoke the method

Dragging with middle mouse button (or left mouse button in object background)
	Move the object

Dragging in window background
	Select objects contained in dragged rectangle

Right mouse-button in an object
	Remove the object

Backspace Key
	Remove selected object(s)


Technical Notes
===============

thor.tcl implements the interactions with the FE over the ASCII interface.
The importante procedures exported by thor.tcl are

thor <object> <method> <args...>	Invoke method/iterator
thor-wellknown <name>			Fetch wellknown object
thor-string <string-object-handle>	Fetch actual string for a string object
thor-handle <string>			Returns true iff argument is a handle
thor-commit				Commit the current transaction
thor-methods <class-handle>		Return list of method objects for class

thor-speedups.tcl provides fast access to some immutable thor data.



--------------------------------------------------------------------------
Tcl Veneer Internals
--------------------------------------------------------------------------

Overview
========

Thor objects will be visible as commands in the Tcl veneer.  For example,
a directory object may be used as follows:

	$d insert "hello" "there"

Handles corresponding to objects can be released from the FE table
if necessary by "rename"-ing the handle command out of existence.

Basic Types
===========

Theta basic types will map to the following Tcl types:

Theta type	Tcl type
------------------------
int		string representation of the int
char		one character string
bool		"1" or "0"
null		"nil"
string		string  (what about strings with embedded nulls?)

Methods
=======

Methods will be invoked by specifying the method name as the
first argument to the Tcl command that represents the Thor object.
Some special methods will also be available to get at metaclass
information.
	$h type			;# Returns the type handle

Type Objects
============

Type objects have the following methods.  (The first method "type"
is inherited from the super-type "any".)

	$t type			;# Returns the type of this type?
	$t equal $s		;# Returns true iff the same type
	$t supertypes		;# Yield all supertypes
	$t subtype $s		;# Returns true iff t is a subtype of s
	$t methods		;# Yield all methods
	$t name			;# Return type name?
	$t unparse		;# Return unparsing of type
	$t kind			;# ???

Anys
====

Value types can be converted to "any" handles using the special
routines described below.  "Any" handles can be forced to basic types
as described below.  Forcing to handle types will not be necessary
because the Tcl veneer does not perform static type-checking.

Anys also have the "type" method that can be used to get the actual
type of the object.  For example, the following piece of code will
either convert an any into a basic value, or signal "no such method":
	thor convert handle [$x type] $x

Exceptions
==========

Show up as Tcl exceptions.  The name of the exception and any arguments
are concatenated together as a list, and the list is thrown as an
exception.

Iterators
=========

When the FE supports them, they could show up as follows:
	$dir bindings key value {
	    puts stdout "$key -> $value"
	}
Until then, maybe the yielded values just get converted into a list:
	foreach x [$dir bindings] {
	    puts stdout "[lindex $x 0] -> [lindex $x 1]"
	}

Stand-alone routines
====================

How does "thor <routine name> args" work for calling standalone routines?

Special Operations
==================

A special "thor" command can be used for special operations:

thor init
thor exit
thor root
thor commit
thor abort
thor same_object $a $b
thor convert any (int|char|string|bool|null|real) <value>
thor convert (int|char|string|bool|null|real) any <handle>

Implementation Concerns
=======================

There will be no stub-generation required for Tcl.  Instead, the Tcl
veneer will have hard-coded knowledge about metaclass operations.
The information gathered using these operations will be used to
implement method calls into the veneer.  In particular, the stub
generator will need to know the method indices for the "getClass"
method, and all of the "type" methods, and "methods" methods.

A method call will proceed as follows:
* Lookup the type of the receiver using the getClass method index
* Invoke the "methods" iterator (on receiver and up the supertype
  hierarchy) to find available methods.
* Find the index of the first method that matches the invoked method.
* For all expected arguments, do type checking (and perhaps any
  necessary conversion of basic values to anys.)
* Perform the invocation.

Obviously we can cache the results of type and method index lookups.
I.e., keep a cache that maps handles to types, and another cache
that maps type,method-name pairs to method information.  We also
have to recognize iterators and perform special processing.

Sample Programs
===============

Print the contents of the root directory:

	thor init
	set root [thor root]
	$root bindings key value {
	    foreach t $types {
		# Try to unparse the value, if that fails, use type name.
		if [catch {set v [$value unparse]}] {
		    set v "<[[$value type] name]>"
		}
		puts stdout "$key -> $v"
	    }
	}
	thor commit
	thor exit

Start a OO7 traversal:

	thor init
	set root [thor root]
	if [catch {set oo7 [$root lookup oo7]}] {
	    puts stderr "could not find OO7 database"
	    exit 0
	}
	$oo7 traverse [thor traversal_create 100]
	thor commit

