Jacl modernization

This was one of the GSoC 2009 Projects

The Jacl Modernization project efforts have been incorporated into the JTcl Interpreter.


Jacl Modernization

Jacl Modernization Project
Google Summer of Code 2009


Draft 2009/03/31

Jacl Modernization Release Notes - Weekly reports on project work and comments. Any suggestions should be placed there since this page is large enough.

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: [L1 ].

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" function 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