javaAPI.txt --

SCCS: @(#) javaAPI.txt 1.5 97/10/21 18:26:15

The functionality of the Tcl interpreter is exported in the Java
package "tcl.lang". This document describes the public API's of the
tcl.lang package. The majority of these API's are simply ports of the
corresponding C API's for Tcl. Instead of going into great detail
about each command, we will refer you to the documentation for the C
version and note any major differences.

One major difference between the C and Java API is the syntax for
exception handling. Please see TclException below for details.

							Equivalent C
Java Classes and Methods				Functions
----------------------------------------------------------------------
class Interp
============
  
This class represents the Tcl interpreter. 

[Variables Manipulation]

The following methods manipulate the variables inside the
interpreter. All of the methods take a "flags" parameter to control
their execution. Please refer to the C API documentation for a
detailed discussion on these flags. In Java, constant values for these
flags can be found in the tcl.lang.TCL class (see TCL below).

  void setVar(String name, TclObject value, int flags)	Tcl_SetVar
      throws TclException
  void setVar(String part1, String part2,		Tcl_SetVar2
      TclObject value, int flags)
      throws TclException

	Create or modify a variable in the interpreter with the given
	value.

  TclObject getVar(String name, int flags)		Tcl_GetVar
      throws TclException
  TclObject getVar(String part1, String part2,		Tcl_GetVar2
      int flags)
      throws TclException

	Read the current value of a variable.

	Note: these two methods differ slightly from their C
	counterparts. If the variable doesn't exist, the default
	consequence is that a TclException will be thrown. However, If
	you include TCL.DONT_THROW_EXCEPTION in the flags parameter, 
	no exception is thrown, and null will is returned to indicate
	the error.
	
  void unsetVar(String name, int flags)			Tcl_UnsetVar
      throws TclException
  void unsetVar(String part1, String part2, int flags)	Tcl_UnsetVar2
      throws TclException

	Delete a variable.
	
  void traceVar(String name, VarTrace trace, int flags)	Tcl_TraceVar
      throws TclException
  void traceVar(String part1, String part2,		Tcl_TraceVar2
        VarTrace trace,	int flags) 
      throws TclException
  void untraceVar(String name, VarTrace trace,		Tcl_UntraceVar
        int flags)
      throws TclException
  void untraceVar(String part1, String part2,		Tcl_UntraceVar2
	VarTrace trace, int flags) 
      throws TclException

	Create or remove a variable trace on the variable. "trace"
	must be an instance of a class that implements the VarTrace
	interface.

[Commands]

The following methods are used to create, query, modify and delete Tcl
commands.

  void createCommand(String cmdName, Command cmd)	Tcl_CreateCommand

	Defines a new command in the interp and associates it with
	the object cmd such that whenever cmdName is invoked as a Tcl
	command (via a call to eval) the Tcl interpreter will call
	cmd.cmdProc to process the command.

	If an old Command object with cmdName already exists in the
	interpreter, the old Command object will be deleted. If the
	old Command object implements the CommandWithDispose
	interface, its disposeCmd() method will be called. See
	CommandWithDispose below.

  int deleteCommand(String cmdName)			Tcl_DeleteCommand

	Deletes the command with the given name from the
	interpreter. If the command exists, it is deleted and this
	method returns 0. If the command does not exist, this method
	returns -1.

	If the Command object implements the CommandWithDispose
	interface, its disposeCmd() method will be called after the
	command is deleted. See CommandWithDispose below.

  Command getCommand(String name)			Tcl_GetCommandInfo

	Returns the Command object that represents the command with
	the given name.

[Result]

The following methods read and modify the result object in the
interpreter.

  TclObject getResult()					Tcl_GetObjResult

	getResult returns the current result object of the
	interpreter.

  void setResult(TclObject r)				Tcl_SetObjResult

	setResult sets the interpreter's result object to be the given
	object.

  void setResult(String r)				Tcl_SetResult
  void setResult(int r)
  void setResult(double r)
  void setResult(boolean r)

	These methods are variations of Interp.setResult for
	conveniently setting the result to a given object type without
	explicitly creating the object.

  void resetResult()					Tcl_ResetResult

	Clears the result to an empty string.

  void setErrorCode(String code)			Tcl_SetErrorCode
  void setErrorCode(TclObject code)			Tcl_SetObjErrorCode

	Set the errorCode object in the interpreter. The errorCode
	object is mirrored in Tcl scripts via the "errorCode" global
	variable.

  void addErrorInfo(String message)			Tcl_AddErrorInfo

	Appends the given string to the errorInfo object in the
	interpreter. The errorInfo object is mirrored in Tcl scripts
	via the "errorInfo" global variable.

[Evaluating Scripts]

  void eval(String s)					Tcl_Eval
      throws TclException
  void eval(String s, int flags)			Tcl_GlobalEval
      throws TclException
  void eval(TclObject tobj, int flags)			Tcl_EvalObj
      throws TclException
  void evalFile(String fileName)			Tcl_EvalFile
      throws TclException

	These methods evaluate a Tcl script stored in a String, a
	TclObject or a file. The optional "flags" argument controls
	the stack level of the evaluation. Usually, the script is
	evaluated in the current level. When TCL.GLOBAL_ONLY is
	included in flags, the script is evaluated in the global
	level.

  boolean commandComplete(String string)		Tcl_CommandComplete

	Determines whether the string contains one or more complete
	commands (i.e. there are no unclosed quotes, braces, brackets,
	or variable references). If the command string is complete
	then it returns true; otherwise it returns false.

----------------------------------------------------------------------
class TclObject
===============

The Java API to the Tcl interpreter is object-based -- in most cases,
the values passed to and from the Tcl interpreter are instances of
TclObject. This includes variable values and command arguments.

A TclObject is dual-ported: it behaves like a String but also holds an
internal representation that can be manipulated more efficiently. For
example, a Tcl list is represented as a TclObject that holds the
list's string representation as well as a Vector to hold the
objects for each list element. Dual-ported objects avoid most runtime
type conversions. This improves the speed of many operations
since an appropriate representation is immediately available.

Currently the following internal representations are supported:
TclBoolean, TclDouble, TclList, TclIndex, TclInteger and
TclString. Most of these internal representations have a newInstance()
method, which can be used to create a new TclObject instance that
contains the specific internal representation.

You should always create TclObject instances with the newInstance()
methods; use the "new" operator to create TclObject instances only
when you are writing new internal representations.

  TclObject(InternalRep rep)				Tcl_NewObj

	Creates a new TclObject with the given InternalRep. This
	constructor should be used only by subclasses of InternalRep.

  void setInternalRep(InternalRep rep)			Tcl_ConvertToType
  InternalRep getInternalRep()				TclObj.typePtr

	Query and modify the InternalRep of this TclObject. These
	methods should be used only by subclasses of InternalRep.

  String toString()					Tcl_GetStringFromObj

	Obtains the String representation of the TclObject.

  void invalidateStringRep()				Tcl_InvalidateStringRep

	Marks the String representation of the TclObject as
	invalid. This method should be called only by subclasses of
	InternalRep prior to a call to setInternalRep().

  boolean isShared()					Tcl_IsShared
  TclObject takeExclusive()				??
  void preserve()					Tcl_IncrRefCount
  void release()					Tcl_DecrRefCount

	To improve memory efficiency, TclObject supports copy-on-write
	operations. When you need to save the value of a TclObject for
	later use, call the preserve() method; when you no longer
	needs its value, call the release() method. Internally, each
	call to preserve() will internally increment the "reference
	count" of the TclObject by one; conversely, each call to
	release() decrements the reference count by one.

	isShared() returns true if the TclObject is shared (its
	reference count is greater than one.)

	Some methods of the InternalRep classes, such as
	TclList.append() and TclInteger.set(), modify the contents of
	a TclObject. When you are about to call these methods to
	modify the value of a TclObject, you must call preserve() (if
	you haven't already done so) and then call
	takeExclusive(). takeExclusive() will make a copy of the
	TclObject if it is shared. The TclObject returned by the
	takeExclusive() will always have a reference count of 1.

----------------------------------------------------------------------
class InternalRep
=================

This class is base class of all the internal representation types in
Tcl. Any InternalRep subclass should implement the following three
methods.

  void dispose()				Tcl_ObjType.freeProc

	This method is called when an InternalRep is no longer used by
	Tcl. It should free all the resources used by this InternalRep
	instance.

  InternalRep duplicate()			Tcl_ObjType.dupIntRepProc

	This method is called when an exact copy of the InternalRep is
	needed during a copy-on-write operation.

  String toString()				Tcl_ObjType.updateStringProc

	This method is called when a string representation is needed
	for a TclObject.

----------------------------------------------------------------------
class TclBoolean (extends InternalRep)
================

This class is used to create and read boolean objects from Java code.

  static TclObject newInstance(boolean b)		Tcl_NewBooleanObj

	Creates a new TclObject instance that has a TclBoolean
	internal representation with the given boolean value.

  static boolean get(Interp interp, TclObject tobj)	Tcl_GetBooleanFromObj
      throws TclException

	This method attempts to return a boolean value from the
	tobj. If the tobj is not already an boolean object, it will
	attempt to convert it to one.

----------------------------------------------------------------------
class TclDouble (extends InternalRep)
===============

This class is used to create and read double precision floating point
objects from Java code.

  static TclObject newInstance(double d)		Tcl_NewDoubleObj

	Creates a new TclObject instance that has a TclDouble
	internal representation with the given double value.

  static double get(Interp interp, TclObject tobj)	Tcl_GetDoubleFromObj
      throws TclException

	This method attempts to return a double value from the
	tobj. If the tobj is not already an double object, it will
	attempt to convert it to one.

  static void set(TclObject tobj, double d)		Tcl_SetDoubleObj

	Sets tobj to have the double value given by d. When this
	method returns, the internal representation of tobj will be
	TclDouble.

----------------------------------------------------------------------
class TclIndex (extends InternalRep)
==============

  static int get(Interp interp, TclObject tobj,		Tcl_GetIndexFromObj
      String table[], String msg, int flags)
      throws TclException

	This class provides an efficient way for looking up keywords,
	switch names, option names, and similar things where the value
	of an object must be one of a predefined set of values.
	tobj is compared against each of the strings in table to
	find a match. A match occurs if tobj's string value is
	identical to one of the strings in table, or if it is a
	unique abbreviation for exactly one of the strings in table
	and the TCL.EXACT flag was not specified; in either case the
	index of the matching entry is returned.

	If there is no matching entry, a TclException is thrown and an
	error message is left in interp's result if interp isn't NULL.
	Msg is included in the error message to indicate what was
	being looked up. For example, if msg is option the error
	message will have a form like

		bad option "firt": must be first, second, or third.
 
	If this method completes successfully it modifies the internal
	representation of tobj to hold the address of the table and
	the index of the matching entry. If TclIndex.get() is invoked
	again with the same tobj and table arguments (e.g. during
	a re-invocation of a Tcl command), it returns the matching
	index immediately without having to redo the lookup operation.

----------------------------------------------------------------------
class TclInteger (extends InternalRep)
================

This class is used to create, read and modify integer objects from
Java code.

  static TclObject newInstance(int intValue)		Tcl_NewStringObj

	Creates a new TclObject instance that has a TclInteger
	internal representation with the given integer value.

  static int get(Interp interp, TclObject tobj)		Tcl_GetIntFromObj
      throws TclException

	This method attempts to return an integer value from the
	tobj. If the tobj is not already an integer object, it will
	attempt to convert it to one.

  static int getForIndex(Interp interp,			TclGetIntForIndex
      TclObject tobj, int endValue)
      throws TclException

	This method is intended to simplify operations that expects
	either an integer value or the string "end". If tobj contains
	the string "end", this method returns endValue. Otherwise, it
	performs the same operations as TclInteger.get.

  static void set(TclObject tobj, int intValue)		Tcl_SetIntObj

	Sets tobj to have the integer value given by intValue. When
	this method returns, the internal representation of tobj will
	be TclInteger.

----------------------------------------------------------------------
class TclList (extends InternalRep)
=============

This class is used to create, modify and read from Tcl list
objects. All of the methods defined below would attempt to change the
internal representation of their tobj parameter to TclList. If such a
conversion fails (e.g., the string value of tobj is not a proper Tcl
list), a TclException will be thrown and an appropriate error message
is left in the interp's result if interp is not null.

  static TclObject newInstance()			Tcl_NewListObj

	Creates an TclObject that represents an empty list.

  static void append(Interp interp, TclObject tobj,	Tcl_ListObjAppendList
	    TclObject elemObj)
      throws TclException

	Appends elemObj to the end of the list.

  static int getLength(Interp interp, TclObject tobj)	Tcl_ListObjLength
      throws TclException

	Returns the length of the list.

  static TclObject[] getElements(Interp interp,		Tcl_ListObjGetElements
      TclObject tobj)
      throws TclException

	Returns all the elements of the list. Note that the content of
	the array returned by getElements() may become invalid as soon
	as the content of the list is modified.

  static TclObject index(Interp interp, TclObject tobj,	Tcl_ListObjIndex
      int index)
      throws TclException

	Returns the element at the given index of the list. If index
	is out of range, null will be returned.

  static void replace(Interp interp, TclObject tobj,	Tcl_ListObjReplace
      int index, int count, TclObject elements[],
      int from, int to)
      throws TclException

	Replaces the elements from index to (index + count - 1) in the
	list by TclObjects from elements[from] through elements[to].

----------------------------------------------------------------------
class TclString (extends InternalRep)
===============

  static TclObject newInstance(String strValue)		Tcl_NewStringObj

	Creates a new Tcl string with the given value.

  static void append(TclObject tobj, String string)	Tcl_AppendToObj

	Append the given string to tobj. When this method returns,
	tobj's internal representation will be TclString.

----------------------------------------------------------------------
interface Command
=================

The Command interface is used to define new Tcl commands.

  void cmdProc(Interp interp, TclObject argv[])		Tcl_CommandProc
      throws TclException

	This method is invoked to process a Tcl command for the
	given interpreter. The argv array contains the arguments
	passed to the command: argv[0] is the name of the command and
	the rest of the array contains the rest of the arguments.

	If the command execution completes normally, this method
	should pass the result object back to the interpreter by
	calling interp.setResult() and then return normally. If an
	error occurs during the command execution, this method should
	throw a TclException with appropriate completion code and
	error messages (see TclException below.)

interface CommandWithDispose (extends Command)
============================

This interface is used to define more sophisticated commands that
require clean-up when the command is deleted from an interpreter.

  void disposeCmd()					Tcl_CmdDeleteProc

	When the command represented by this Command instance is
	deleted from an interpreter, this method is invoked to free any
	resources that were allocated when the command was
	created.

----------------------------------------------------------------------
class TclException
==================

TclException is used to signal exception conditions in the execution
of Tcl scripts. The Exception handling syntax in the C API can be
represented by the following canonical C code:

	int foo(Tcl_Interp interp, ...)
	{
	    if (ok) {
		Tcl_SetResult(interp, result);
		return TCL_OK;
	    } else {
		Tcl_SetResult(interp, "err message ...");
		return TCL_ERROR;
	    }
        }

The return value of the foo() procedure is the completion code. TCL_OK
indicates a normal completion status, and all other values indicate an
exception. The above code can be written in Java as:


	void foo(Interp interp, ...)
	{
	    if (ok) {
		interp.setResult(result);
	    } else {
		interp.setResult("err message ...");
		throw new TclException(TCL.ERROR);
	    }
        }

In the Java API, the completion code is not returned by the foo()
method.  Instead, the completion code is stored inside the
TclException. Hence, foo()'s return type is void. If the foo() method
completes normally, no TclException is thrown, and the completion code
is implied to be TCL.OK.

  int compCode						N.A.

	Stores the completion code

  TclException(int ccode)				N.A.

	Creates a TclException with the given completion code.

  TclException(Interp interp, String msg, int ccode)

	This constructor is used to conveniently create a TclException
	and indicate the completion code. If interp is non-null, its
	result object will be set to contain the given message. For
	example:

	    throw new TclException(interp, "err message ...", TCL.ERROR);

  TclException(Interp interp, String msg)

	This constructor is the same as above, except the completion
	code is set to TCL.ERROR by default.

----------------------------------------------------------------------
class TclNumArgsException (extends) TclException
=========================

  TclNumArgsException(Interp interp, int argc,		Tcl_WrongNumArgs
      TclObject argv[], String message)


	TclNumArgsException is a "convenient" subclass of TclException
	for command procedures to indicate that they have received the
	number of arguments. It generates a standard error message and
	stores it in the result object of interp.

	The message includes the argc initial elements of argv plus
	message. For example, if argv consists of the values foo and
	bar, objc is 1, and message is "fileName count" then interp's
	result object will be set to the following string:

		wrong #	args: should be "foo fileName count"

----------------------------------------------------------------------
class TclRuntimeError
=====================

  TclRuntimeError(String errMsg)			panic

	TclRuntimeError is used to report an unrecoverable error
	inside any Java code that implements the Tcl interpreter or
	extensions. When a TclRuntimeError is thrown, it stops Tcl
	execution immediately and prints out the error message.

----------------------------------------------------------------------
interface VarTrace
==================

  void traceProc(Interp interp, String part1,		Tcl_TraceProc
      String part2, int flags)

	The VarTrace interface is used to monitor and control access
	to a Tcl variable, so that the traceProc() is invoked whenever
	the variable is read or written or unset.

----------------------------------------------------------------------
class Extension
===============

This is the base class for building dynamically loadable Tcl
extensions.

 void init(Interp interp)		              <ext>_Init entry point
      throws TclException
 void safeInit(Interp safeInterp)		      <ext>_SafeInit entry pt.
      throws TclException

	The init() method is used to perform initialization specific
	to the given extension. Usually, this means creating new
	commands inside the interpreter.

	The safeInit() method is used to perform initializations when
	the package is loaded into a safe interpreter. It should only
	enable features that are deemed "safe" to be executed by
	untrusted Tcl scripts.

 static void loadOnDemand(Interp interp, String		N.A.
      cmdName, String clsName)

	The loadOnDemand method arranges a Command implementation to
	be loaded into the JVM the first time the command is executed;
	this can reduce the time it takes to initialize an Extension.

----------------------------------------------------------------------
class Util
==========

This class contains utility routines that do not naturally fit into
other classes in the tcl.lang package.

  static boolean stringMatch(String string,		Tcl_StringMatch
      String pattern)

	Returns whether the string matches with the given pattern
	according to Tcl's "glob" rules. See the manual page for the
	"string match" command for details.

---------------------------------------------------------------------------
class TCL
=========

This class contains all the public constants exported by the tcl.lang
package.

  GLOBAL_ONLY						TCL_GLOBAL_ONLY
  NAMESPACE_ONLY					TCL_NAMESPACE_ONLY
  APPEND_VALUE						TCL_APPEND_VALUE
  LIST_ELEMENT						TCL_LIST_ELEMENT
  TRACE_READS						TCL_TRACE_READS	
  TRACE_WRITES						TCL_TRACE_WRITES
  TRACE_UNSETS						TCL_TRACE_UNSETS
  TRACE_DESTROYED					TCL_TRACE_DESTROYED
  INTERP_DESTROYED					TCL_INTERP_DESTROYED
  LEAVE_ERR_MSG						TCL_LEAVE_ERR_MSG
  PARSE_PART1						TCL_PARSE_PART1

	These flags may be passed to the variable-related methods of
	the Interp class.

	GLOBAL_ONLY also controls the evaluation stack level of the
	Interp.eval() methods.

  DONT_THROW_EXCEPTION					N.A.

	This flag may be passed to Interp.getVar. If this flag is set,
	getVar will return null for undefined variables (instead of
	throwing a TclException.)

  OK							TCL_OK
  ERROR							TCL_ERROR
  RETURN						TCL_RETURN
  BREAK							TCL_BREAK
  CONTINUE						TCL_CONTINUE

	These flags are used to indicate the completion code when a
	TclException is thrown.

  EXACT							TCL_EXACT

	This flag may be passed to TclIndex.get() to force it to
	disallow abbreviated strings.

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