**Jacl Modernization**
Jacl Modernization Project <
>
Google Summer of Code 2009
----
Draft 2009/03/31 <
>
<
>
***Description***
This project intends to modernize the Jacl interpreter's support of core Tcl
commands. We set a goal of implementing Tcl 8.4 level commands. 8.4 is
targeted as the last Tcl version before major changes to the Tcl parser, which
supports the "list expansion" syntax in version 8.5 (.e.g., "{*}"). The
TJC compiler also does not currently support list expansion syntax.<
>
<
>
Should time permit, selective features of Tcl 8.5 may be implemented as
well. Tcl 8.5 commands to be considered include "apply", "chan", "dict",
"lassign", "lrepeat", "lreverse", as well as number of new subcommands affecting
many existing commands. See: [http://wiki.tcl.tk/10630].<
>
<
>
Jacl will remain Java JDK version 1.4 API compliant.<
>
<
>
***Definitions***
* "Tcl" - refers to the C-based Tcl interpreter, version 8.4.19
* "Jacl" - refers to Jacl 1.4.1, or the latest from revision control.
* "JVM" - refers to the Java Virtual Machine, JDK API version 1.4
***Analysis***
We examine each Tcl command using man pages and source code, and compare the
existing Jacl source code implementation of that command. Only Tcl core
commands are compared; standard library procs (e.g., "auto_execok",
"auto_import", etc.) are not considered. Some of these standard library
procs are implementation dependent, others may be used directly from Tcl 8.4 <
>
<
>
For each command, each option invocation is listed. Jacl support will either
be noted as "Supported" or "**Unsupported**". Also, for commands that have
switches, options, format specifiers, etc., we examine those for conformity.
Where these match Tcl, we note those as "Supported", otherwise if not
implemented or differing in funcionality, we note as "**Unsupported**".<
>
***Testing***
The Tcl test suite should be considered the standard by which Jacl should
comply. Notable exception include those commands that expect to interact
with operating system API's, such as "exec". JVM limitations may prevent
full Tcl compliance for some commands. <
>
***Implementation Priority***
Tasks to modernize Jacl range from easy to difficult. Firstly, easy tasks, such
as adding options to existing commands to help familiarize with the Jacl
code base before tackling more difficult tasks.<
>
<
>
File event processing is likely to require substantial changes
to Jacl file handling and event structures.<
>
***Analysis Results***
****after****
after ms
Supported
after ms ?script script script ...?
Supported
after cancel id
Supported
after cancel script script ...
Supported
after idle script ?script script ...?
Supported
after info ?id?
Supported
****append****
append varName ?value value value ...?
Supported
****array****
array anymore arrayName searchId
Supported
array donesearch arrayName searchId
Supported
array exists arrayName
Supported
array get arrayName ?pattern?
Supported
array names arrayName ?mode? ?pattern?
Supported
array nextelement arrayName searchId
Supported
array set arrayName list
Supported
array size arrayName
Supported
array startsearch arrayName
Supported
array statistics array‐name
**Unsupported**
Notes:
Implementation details between C and Java are likely the root
of this option. Jacl implementation shoud accept this option,
but not necessarily return useful information.
array unset arrayName ?pattern?
Supported
****binary****
binary format formatString ?arg arg ...?
Supported
binary scan string formatString ?varName varName ...?
Supported
Format characters: a A b B h H c s S i I w W f d x X @
Supported
****break****
break
Supported
****case****
case string ?in? patList body ?patList body ...?
Supported
case string ?in? {patList body ?patList body ...?}
Supported
****catch****
catch script ?varName?
Supported
****cd****
cd ?dirname?
Supported
****clock****
clock clicks ?-milliseconds?
Supported
clock format clockValue ?-format string? ?-gmt boolean?
Supported
clock scan dateString ?-base clockVal? ?-gmt boolean?
Supported
clock second
Supported
Format specifiers: %% %a %A %b %B %c %C %d %D %e %H %I %j %k %l %m %M
%n %p %r %R %s %S %t %T %u %U %V %w %W %x %X %y %Y %Z %Q
Supported
%g %G %h
**Unsupported**
****close****
close channelId
Supported
****concat****
concat ?arg arg ...?
Supported
****continue****
continue
Supported
****encoding****
encoding convertfrom ?encoding? data
Supported
encoding convertto ?encoding? string
Supported
encoding names
Supported
encoding system ?encoding?
Supported
****eof****
eof channelId
Supported
****error****
error message ?info? ?code?
Supported
****eval****
eval arg ?arg ...?
Supported
****exec****
exec ?switches? arg ?arg ...?
Supported
Switches: -- -keepnewline
Supported
special args: &
Supported
| |& < fileName <@ fileId << value > fileName
2> fileName >& fileName >> fileName 2>> fileName
>>& fileName >@ fileId 2>@ fileId >&@ fileId
**Unsupported**
Note: JVM process control is limited compared to Tcl, so
some special arguments may not be able to be implemented.
Threads may be useful to read a process output in order to
pipe (write) into another process.
See also "open" command.
****exit****
exit ?returnCode?
Supported
****expr****
expr arg ?arg arg ...?
Supported
Operators: ( ) * / % + - << >> < > <= >= == != & ^ | && || ? :
eq ne - + ! ~
Supported
Functions: abs asin atan2 cos cosh exp fmod int log pow round sinh sqrt
tan acos atan double floor ceil log10 rand hypot srand tanh sin
Supported
wide
**Unsupported**
Note:
Tcl supports "wide" 64 bit integer internally. "expr" stores
values as 32 bit integers if the results of an expression is
an integer and fits in 32 bits, otherwise a 64 bit value is
returned. The "wide" funtion forces a return value into a
64 bit value. Significant internal changes may be required
to fully support 64 bit integers.
****fblocked****
fblocked channelId
Supported
****fconfigure****
fconfigure channelId
Supported
fconfigure channelId name
Supported
fconfigure channelId name value ?name value ...?
Supported
Options:
-blocking boolean
-buffering type (full | line | none)
-buffersize size
-encoding encoding
-eofchar char
-eofchar {inchar outchar}
-translation mode (auto | binary | cr | crlf | lf)
-translation {inmode outmode}
Supported
****fcopy****
fcopy inchan outchan ?-size size? ?-command callback?
**Unsupported**
Notes:
The asynchronous version of this command (-command) will
require much of the same internal work as fileevent.
See also: fileevent
****file****
file option name ?arg arg ...?
Supported
Options: copy, delete, dirname, exists, extension, isdirectory,
isfile, join, mtime, mkdir, nativename, owned, pathtype,
readable, rename, rootname, size, split, stat, tail, type,
volumes, writable
Supported
atime, attributes, link, lstat, readlink, system
**Unsupported**
Notes:
JVM does not support these optons
channals, executable, normalize, separator
**Unsupported**
Notes:
These options are likely supportable, but currently
unimplemented in Jacl.
****fileevent****
fileevent channelId readable ?script?
fileevent channelId writable ?script?
**Unsupported**
Notes: Will likely require use of Java NIO, or a thread-based
solution.
****flush****
flush channelId
Supported
****for****
for start test next body
Supported
****foreach****
foreach varname list body
Supported
foreach varlist1 list1 ?varlist2 list2 ...? body
Supported
****format****
format formatString ?arg arg ...?
Supported
Format strings: d u i o x X c s f e E g G %
Supported
****gets****
gets channelId ?varName?
Supported
****glob****
glob ?switches? pattern ?pattern ...?
Supported
Switches: -nocomplain --
Supported
-directory -join -path -tails -types
**Unsupported**
Notes: See Tcl man page for option usage
****global****
global varname ?varname ...?
Supported
****history****
history ?option? ?arg arg ...?
Supported
Options: add, change, clear, event, info, keep, nextid, or redo
Supported
****if****
if expr1 ?then? body1 elseif expr2 ?then? body2 elseif .. ?else? ?bodyN?
Supported
****incr****
incr varName ?increment?
Supported
****info****
info option ?arg arg ...?
Supported
Options: args, body, cmdcount, commands, complete, default, exists,
globals, hostname, level, library, loaded, locals,
nameofexecutable, patchlevel, procs, script,
sharedlibextension, tclversion, or vars
Supported
functions
**Unsupported**
Notes: "info tclversion" and "info patchlevel" should report "8.4" and "8.4.0",
respectively.
****interp****
interp alias srcPath srcToken
Supported
interp alias srcPath srcToken {}
Supported
interp alias srcPath srcCmd targetPath targetCmd ?arg arg ...?
Supported
interp aliases ?path?
Supported
interp create ?-safe? ?--? ?path?
Supported
interp delete ?path ...?
Supported
interp eval path arg ?arg ...?
Supported
interp exists path
Supported
interp expose path hiddenName ?exposedCmdName?
Supported
interp hide path exposedCmdName ?hiddenCmdName?
Supported
interp hidden path
Supported
interp invokehidden path ?-global? hiddenCmdName ?arg ...?
Supported
interp issafe ?path?
Supported
interp marktrusted path
Supported
interp recursionlimit path ?newlimit?
**Unsupported**
interp share srcPath channelId destPath
Supported
interp slaves ?path?
Supported
interp target path alias
Supported
interp transfer srcPath channelId destPath
Supported
Slave commands:
aliases alias eval expose hide hidden invokehidden
issafe marktrusted
Supported
recursionlimit
**Unsupported**
****join****
join list ?joinString?
Supported
****lappend****
lappend varName ?value value value ...?
Supported
****lindex****
lindex list ?index...?
Supported
****linsert****
linsert list index element ?element element ...?
Supported
****list****
list ?arg arg ...?
Supported
****llength****
llength list
Supported
****load****
load filename
load fileName packageName
load fileName packageName interp
**Unsupported**
Note: This command is designed to load C coded extensions into
Tcl. Jacl instead uses specialized commands to load Java extensions,
"jaclloadjava", "jaclloaditcl", etc.
****lrange****
lrange list first last
Supported
****lreplace****
lreplace list first last ?element element ...?
Supported
****lsearch****
lsearch ?options? list pattern
Supported
Options: -ascii, -decreasing, -dictionary, -exact, -increasing,
-integer, -glob, -real, -switch, -regexp, -sorted
Supported
-all, -inline, -not, -start,
**Unsupported**
****lset****
lset varName ?index...? newValue
**Unsupported**
****lsort****
lsort ?options? list
Supported
Options: -ascii, -command, -decreasing, -dictionary, -increasing,
-index, -integer, -real
Supported
-unique, -index end-$i
**Unsupported**
Note: Jacl honors "-index end", but does not honor a position
relative to end, such as "-index end-1".
****namespace****
namespace ?option? ?arg ...?
Supported
Options: children, code, current, delete, eval, export, forget,
import, inscope, origin, parent, qualifiers, tail, which
Supported
exists
**Unsupported**
****open****
open fileName
Supported
open fileName access
Supported
open fileName access permissions
Supported
access options: r r+ w w+ a a+ RDONLY WRONLY RDWR APPEND CREAT
EXCL TRUNC
Supportred
NOCTTY NONBLOCK
**Unsupported**
Command pipelines
**Unsupported**
Note: Pipelines, at least simple ones, should be possible.
Threads may be useful to read output of one process and
write into another.
See also: exec, fileevent
Serial port device
**Unsupported**
****package****
package forget ?package package ...?
Supported
package ifneeded package version ?script?
Supported
package names
Supported
package present ?-exact? package ?version?
Supported
package provide package ?version?
Supported
package require ?-exact? package ?version?
Supported
package unknown ?command?
Supported
package vcompare version1 version2
Supported
package versions package
Supported
package vsatisfies version1 version2
Supported
****pid****
pid ?fileId?
**Unsupported**
See also: exec, open
****proc****
proc name args body
Supported
****puts****
puts ?-nonewline? ?channelId? string
Supported
****pwd****
pwd
Supported
****read****
read ?-nonewline? channelId
Supported
read channelId numChars
Supported
****regexp****
regexp ?switches? exp string ?matchVar? ?subMatchVar subMatchVar ...?
Supported
Switches: -indices, -nocase, --
Supported
-about, -expanded, -line, -linestop, -lineanchor, -all,
-inline, -start
**Unsupported**
RE syntax: significant changes
Notes: Jacl implements "basic" RE syntax, via the package
sunlabs.brazil.util.regexp.Regexp. This should be replaced with
Java 1.4 java.util.regex.* which supports most "advanced"
RE syntax (i.e., POSIX syntax) with a few exceptions.
Some Tcl RE syntax could be supported via substituion, e.g.
character classes such as "[[:alpha:]]" could potentially be
replaced with the Java regexp syntax "\p{Alpha}"
RE engine changes also affect other commands that can
accept a '-regexp re' argument (regsub, lsearch, switch, etc.)
****regsub****
regsub ?switches? exp string subSpec ?varName?
Supported
Switches: -all, -nocase, --
Supported
-expanded, -line, -linestop, -lineanchor, -start
**Unsupported**
See also: regexp
****rename****
rename oldName newName
Supported
****return****
return ?-code code? ?-errorinfo info? ?-errorcode code? ?string?
Supported
****scan****
scan string format ?varName varName ...?
Supported
format characters: * d o x c s e f g [chars] [^chars] width
Supported
u i
**Unsupported**
Notes: If wide integers are supported (64 bit), then the
modifiers "l" and "L" should be supported.
****seek****
seek channelId offset ?origin?
Supported
origin options: start, current, end
Supported
****set****
set varName ?value?
Supported
****socket****
socket ?options? host port
Supported
socket -server command ?options? port
Supported
options: -myaddr, -myport,
-async
**Unsupported**
Notes: Lack of fileevent support limits functionality
of the socket command to
****source****
source fileName
Supported
source -rsrc resourceName ?fileName?
source -rsrcid resourceId ?fileName?
**Unsupported** Mac specific
Notes: Jacl source can also source files from a CLASSPATH
resource.
****split****
split string ?splitChars?
Supported
****string****
string bytelength string
Supported
string compare ?-nocase? ?-length int? string1 string2
Supported
string equal ?-nocase? ?-length int? string1 string2
Supported
string first string1 string2 ?startIndex?
Supported
string index string charIndex
Supported
string is class ?-strict? ?-failindex varname? string
Supported
string last string1 string2 ?lastIndex?
Supported
string length string
Supported
string map ?-nocase? mapping string
Supported
string match ?-nocase? pattern string
Supported
string range string first last
Supported
string repeat string count
Supported
string replace string first last ?newstring?
Supported
string tolower string ?first? ?last?
Supported
string totitle string ?first? ?last?
Supported
string toupper string ?first? ?last?
Supported
string trim string ?chars?
Supported
string trimleft string ?chars?
Supported
string trimright string ?chars?
Supported
string wordend string charIndex
Supported
string wordstart string charIndex
Supported
string is classes: alnum, alpha, ascii, control, boolean, digit,
double, false, graph, integer, lower, print, punct, space,
true, upper, wordchar, xdigit
Supported
****subst****
subst ?-nobackslashes? ?-nocommands? ?-novariables? string
Supported
****switch****
switch ?options? string pattern body ?pattern body ...?
Supported
switch ?options? string {pattern body ?pattern body ...?}
Supported
options: -exact, -glob, -regexp, --
Supported
Notes: see regexp
****tell****
tell channelId
Supported
****time****
time script ?count?
Supported
****trace****
trace add command name ops command
**Unsupported**
trace add execution name ops command
**Unsupported**
trace add variable name ops command
**Unsupported**
trace remove type name opList command
**Unsupported**
trace info type name
**Unsupported**
trace variable name ops command
Supported
trace vdelete name ops command
Supported
trace vinfo name
Supported
trace ops: r w u
Supported
a
**Unsupported**
Notes: Jacl supports an older form of trace, which is
considered deprecated in Tcl. Jacl trace currently only
supports variable tracing, not command tracing.
****unset****
unset ?options? name ?name name ...?
Supported
option: -nocomplain --
**Unsupported**
Notes: -nocomplain cause the unset commang to ignore any
errors, such as unsetting an non-existent variable.
****update****
update ?idletasks?
Supported
****uplevel****
uplevel ?level? arg ?arg ...?
Supported
****upvar****
upvar ?level? otherVar myVar ?otherVar myVar ...?
Supported
****variable****
variable ?name value...? name ?value?
Supported
****vwait****
vwait varName
Supported
****while****
while test body
Supported
----
!!!!!!
%| enter categories here |%
!!!!!!