The Jim Interpreter
A small-footprint implementation of the Tcl programming language.

--------------------------------------------------------------------------------
WHAT IS JIM?
--------------------------------------------------------------------------------

Jim is a small footprint implementation of the Tcl programming language
written from scratch. Currently it's a work in progress, but already
capable to run non-trivial scripts (see the benchmark.tcl file for
an example). There are many Tcl core commands not implemented, but the
language itself offers already interesting features like {expand} and
[dict], that are features that will appear on Tcl8.5, [lambda] with
garbage collection, and a general GC/references system to build linked
data structure with automatic memory management. Arrays in Jim are
not collection of variables, but instead syntax sugar for [dict]tionaries.

Other common features of the Tcl programming language are present, like
the "everything is a string" behaviour, implemented internally as
dual ported objects to ensure that the execution time does not reflect
the semantic of the language :)

--------------------------------------------------------------------------------
WHEN JIM CAN BE USEFUL?
--------------------------------------------------------------------------------

1) If you are writing an application, and want to make it scriptable, with
Jim you have a way to do it that does not require to link your application
with a big system. You can just put jim.c and jim.h files in your project
and use the Jim API to write the glue code that makes your application
scriptable in Jim, with the following advantages:

- Jim is not the next "little language", but it's a Tcl implementation.
  You can reuse your knowledge if you already Tcl skills, or enjoy
  the availability of documentation, books, web resources, ...
  (for example check my online Tcl book at http://www.invece.org/tclwise)

- Jim is simple, 10k lines of code. If you want to adapt it you can hack
  the source code to feet the needs of your application. It makes you
  able to have scripting for default, and avoid external dependences.

  Having scripting support *inside*, and in a way that a given version
  of your program always gets shipped a given version of Jim, you can
  write part of your application in Jim itself. Like it happens for
  Emacs/Elisp, or Gimp/Scheme, both this applications have the interpreter
  inside.

- Jim is Tcl, and Tcl looks like a configuration file if you want. So
  if you use Jim you have also a flexible syntax for your config file.
  This is a valid Tcl script:

     set MyFeature on
     ifssl {
       set SslPort 45000
       use compression
     }

  It looks like a configuration file, but if you implement the [ifssl]
  and [use] commands, it's a valid Tcl script.

- Tcl scales with the user. Not all know it, but Tcl is so powerful that
  you can reprogram the language in itself. Jim support this features
  of the Tcl programming language. You can write new control structures,
  use the flexible data types it offers (Lists are a central data structure,
  with Dictionaries that are also lists). Still Tcl is simpler for the
  casual programmer, especially if compared to other languages offering
  small footprint implementations (like Scheme and FORTH).

- Because of the Tcl semantic (pass by value, everything is a command
  since there are no reserved words), there is a nice API to glue
  your application with Jim. See under the 'docs' directory to find
  examples and documentation about it.

- Jim is supported. If you need commercial software, contact the author
  writing an email to 'antirez@gmail.com'.

2) The other "field" where Jim can be useful is obviously embedded systems.

3) We are working to make Jim as feature-complete as possible, thanks to
   dynamically loaded extensions it may stay as little as it is today
   but able to do interesting things for you. So it's not excluded that
   in the future Jim will be an option as general purpose language.
   But don't mind, for this there is already the mainstream Tcl
   implementation ;).

--------------------------------------------------------------------------------
HOW BIG IS IT?
--------------------------------------------------------------------------------

Jim compiled with -Os is 85k currently. Still it lacks core commands
that will make it a little bigger, but not too much... only what's
strictly required will end inside the core, the rest will be implemented
as extensions.

Note that the actual Jim core is much smaller, if you strip away commands.
If you can do without [expr] (that's big about code size), and some
other command you may probably end with a 40k executable.

--------------------------------------------------------------------------------
HOW FAST IS IT?
--------------------------------------------------------------------------------

Jim is in most code faster than Tcl7.6p2 (latest 7.x version),
and slower than Tcl 8.4.x. You can expect pretty decent performances
for such a little interpreter.

If you want a more precise measure, there is 'bench.tcl' inside this
distribution that will run both under Jim and Tcl, so just execute
it with both the interpreters and see what you get :)

--------------------------------------------------------------------------------
HOW TO COMPILE
--------------------------------------------------------------------------------

Jim was tested under Linux, FreeBSD, MacosX, Windows XP (mingw, MVC).

To compile jim itself try:

  make jim

On systems other than GNU/Linux, you may have to compile without "-ldl"
because it's not needed, but will cause a compilation error (no configure for
now... applications embedding Jim will probably have one already).

In order to avoid to link against 'dl' just use:

  make LIBS="" jim

For instructions about how to compile extensions just try 'make'
and see the available options. Check also the next section of this file.

--------------------------------------------------------------------------------
HOW TO COMPILE IN SYSTEMS WITH JUST ANSI-C SUPPORT
--------------------------------------------------------------------------------

Try:

  make LIBS="" DEFS="-DJIM_ANSIC" jim

This should compile Jim almost everywhere there is a decent ANSI-C compiler.

--------------------------------------------------------------------------------
EXTENSIONS
--------------------------------------------------------------------------------

POSIX
=====

This is the start of a library that should export to Jim useful bits of the
POSIX API. For now there are just a few utility functions, but it's
an example on how to write a simple library for Jim.

WIN32
=====

This is the start of a library that should export to Jim useful bits of the
WIN32 API. Currently there is just one function that is used to call windows
applications. For example run jim and try the extension with:

  package require win32
  win32.shellexecute open notepad

You should see a notepad application running.

ANSI-I/O, SQLITE
================

There is documentation under the "doc" directory about the "ANSI I/O"
and "SQLITE" extensions.

SDL
===

The SDL extension is currently undocumented (work in progress), but
there is enough to start to play. That's an example script:

    package require sdl

    set xres 800
    set yres 800
    set s [sdl.screen $xres $yres]

    set i 0
    while 1 {
        set x1 [rand $xres]
        set y1 [rand $yres]
        set x2 [rand $xres]
        set y2 [rand $yres]
        set rad [rand 40]
        set r [rand 256]
        set g [rand 256]
        set b [rand 256]
        $s fcircle $x1 $y1 $rad $r $g $b 200
        incr i
        if {$i > 2000} {$s flip}
        if {$i == 3000} exit
    }

--------------------------------------------------------------------------------
HOW TO EMBED JIM INTO APPLICATIONS / HOW TO WRITE EXTENSIONS FOR JIM
--------------------------------------------------------------------------------

See the documentation under the "doc" directory (work in progress).

--------------------------------------------------------------------------------
COPYRIGHT and LICENSE
--------------------------------------------------------------------------------

Copyright (C) 2005 Salvatore Sanfilippo
All Rights Reserved

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 A copy of the license is also included in the source distribution
 of Jim, as a TXT file name called LICENSE.

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.

--------------------------------------------------------------------------------
HISTORY
--------------------------------------------------------------------------------

"first Jim goal: to vent my need to hack on Tcl."

And actually this is exactly why I started Jim, in the first days
of Jenuary 2005. After a month of hacking Jim was able to run
simple scripts, now, after two months it started to be clear to
me that it was not just the next toy to throw away but something
that may evolve into a real interpreter. In the same time
Pat Thoyts and Clemens Hintze started to contribute code, so that
the development of new core commands was faster, and also more
people hacking on the same code had as result fixes in the API,
C macros, and so on.

Currently we are at the point that the core interpreter is almost finished
and it is entering the Beta stage. There is to add some other core command,
to do a code review to ensure quality of all the parts and to write
documentation.

We already started to work on extensions like OOP, event loop,
I/O, networking, regexp. Some extensions are already ready for
prime time, like the Sqlite extension and the ANSI I/O.

------------------------------------------------------------------------------
Thanks to...
------------------------------------------------------------------------------

- First of all, thanks to every guy that are listed in the AUTHORS file,
  that directly helped with code and ideas. Also check the ChangeLog
  file for additional credits about patches or bug reports.
- Elisa Manara that helped me to select this ill conceived name for
  an interpreter.
- Many people on the Tclers Chat that helped me to explore issues
  about the use and the implementation of the Tcl programming language.
- David Welton for the tech info sharing and our chats about
  programming languages design and the ability of software to "scale down".
- Martin S. Weber for the great help with Solaris issues, debugging of
  problems with [load] on this arch, 64bit tests.
- The authors of "valgrind", for this wonderful tool, that helped me a
  lot to fix bugs in minutes instead of hours.


----
Enjoy!
Salvatore Sanfilippo
10 Mar 2005