\input texinfo.tex  @c -*- texinfo -*-
@c %**start of header (This is for running Texinfo on a region.)
@setfilename gst.info
@settitle GNU Smalltalk User's Guide
@c @setchapternewpage odd
@c %**end of header (This is for running Texinfo on a region.)

@c If the file is present, it will define the CLASSREF variable and the
@c menu and nodes will be adjusted in the proper way. If it is not there
@c they will receive a warning (classes.txi not found), but the info
@c file will be as good.
@ifclear NOCLASSREF
@set ONLYDEFINECLASSREF
@include classes.txi
@clear ONLYDEFINECLASSREF
@end ifclear

@c ******************************************* Values and macros *********

@set VERSION 1.7.5
@set UPDATED 1 June 2000
@set UPDATE-MONTH June 2000

@macro bulletize{a}
@item
\a\
@end macro


@macro setifinfo{var, value}
@set \var\
@ifinfo
@set \var\ \value\
@end ifinfo
@end macro

@c Redefine @var to produce <xxx> in the Info file, and italics in TeX
@setifinfo {L_var, <}
@setifinfo {R_var, >}
@macro var{x}
@value{L_var}@i{@t{\x\}}@value{R_var}
@end macro

@comment Not appropriate for a printed manual...
@setifinfo{SMILE, ;-)}

@c ********************************************** Texinfo 4.0 macros *****

@c Emulate the `@ifnottex' command which is found in Texinfo 4.0
@iftex
@set IS_TEX
@end iftex

@c Used instead of @uref for Texinfo 3.1 compatibility
@macro hlink{url, link}
\link\ (\url\)
@end macro

@macro email{mail}
\mail\
@end macro

@c ifhtml means Texinfo 4.0, which has uref
@ifhtml
@unmacro hlink
@unmacro email

@macro hlink{url, link}
@uref{\url\, \link\}
@end macro

@macro email{mail}
@uref{mailto:\mail\, , \mail\}
@end macro

@macro url{url}
@uref{\url\}
@end macro
@end ifhtml

@c ***********************************************************************

@macro gst{}
@sc{gnu} Smalltalk
@end macro
@macro gnu{}
@sc{gnu}
@end macro

@ifinfo
@dircategory GNU Smalltalk
@direntry
     * GNU Smalltalk: (gst).                 The GNU Smalltalk environment.
@end direntry

This file documents @gst{} Version @value{VERSION}.
It was last updated on @value{UPDATED}.

Copyright @copyright{} 1988-92, 1994-95, 1999, 2000 Free Software Foundation, Inc.

This document is released under the terms of the @gnu{} Free Documentation
License as published by the Free Software Foundation; either version 1.1, or
(at your option) any later version.

You should have received a copy of the @gnu{} Free Documentation License along
with @gst{}; see the file @file{COPYING.DOC}.  If not, write to the Free
Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  

The `Acknowledgements' section qualifies as a Secondary Section, as defined
in the license.  There are no Cover Texts and no Invariant Sections; this
text, along with its equivalent in the printed manual, constitutes the
Title Page.
@end ifinfo

@setchapternewpage odd

@titlepage
@title @gst{} User's Guide
@subtitle Version @value{VERSION}
@subtitle @value{UPDATE-MONTH}

@author by Steven B. Byrne, Paolo Bonzini, Andy Valencia.

@comment  The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988-92, 1994-95, 1999, 2000 Free Software Foundation, Inc.

This document is released under the terms of the @gnu{} Free Documentation
License as published by the Free Software Foundation; either version 1.1, or
(at your option) any later version.

You should have received a copy of the @gnu{} Free Documentation License along
with @gst{}; see the file @file{COPYING.DOC}.  If not, write to the Free
Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  

The `Acknowledgements' section qualifies as a Secondary Section, as defined
in the license.  There are no Cover Texts and no Invariant Sections; this
text, along with its equivalent in the Info documentation, constitutes the
Title Page.
@end titlepage

@node Top, , , (DIR)
@top

@ifinfo
This document describes installing and operating the @gst{}
programming language.  If you're anxious to get started, and you know
something about the Smalltalk language, you can skip the introduction
and proceed directly to the Installation node (@pxref{Installation}).

Oh@dots{} of course @value{SMILE} @gst{} has bugs.  And of course I
like to hear from people who have something to say regarding it. So bug
reports, suggestions, help, advices, source code contributions are all
welcome.  All you have to do is send mail to @email{bonzini@@gnu.org}.
Answer is guaranteed, most of the times in a day or two; but before
sending e-mail, please look for bug fixes on
@hlink{ftp://alpha.gnu.org/smalltalk, the @gst{} alpha FTP site}
or one of its mirrors.
@end ifinfo

@include toc.txi

@node Overview, Installation, Top, Top
@unnumbered Introduction

@gst{} is an implementation that closely follows the Smalltalk-80
language as described in the book @cite{Smalltalk-80: the Language
and its Implementation} by Adele Goldberg and David Robson, which
will hereinafter be referred to as @cite{the Blue Book}.

The Smalltalk programming language is an object oriented programming
language.  This means, for one thing, that when programming you are
thinking of not only the data that an object contains, but also of the
operations available on that object.  The object's data representation
capabilities and the operations available on the object are
``inseparable''; the set of things that you can do with an object is defined
precisely by the set of operations, which Smalltalk calls @dfn{methods},
that are available for that object: each object belongs to a @dfn{class}
(a datatype and the set of functions that operate on it) or, better, it
is an @dfn{instance} of that class. You cannot even examine the
contents of an object from the outside---to an outsider, the object is a
black box that has some state and some operations available, but that's
all you know: when you want to perform an operation on an object, you
can only send it a @dfn{message}, and the object picks up the method
that corresponds to that message.

In the Smalltalk language, everything is an object.  This includes not
only numbers and all data structures, but even classes, methods,
pieces of code within a method (@dfn{blocks} or @dfn{closures}), stack
frames (@dfn{contexts}), etc.  Even @code{if} and @code{while} structures
are implemented as methods sent to particular objects.

Unlike other Smalltalks (including Smalltalk-80), @gst{} emphasizes
Smalltalk's rapid prototyping features rather than the graphical and
easy-to-use nature of the programming environment (did you know that the
first GUIs ever ran under Smalltalk?).  The availability of a large body of
system classes, once you master them, makes it pretty easy to write complex
programs which are usually a task for the so called @cite{scripting
languages}.  Therefore, even though we have a nice GUI environment including
a class browser (@pxref{Blox}), the goal of the @gst{} project is
currently to produce a complete system to be used to write your scripts in a
clear, aesthetically pleasing, and philosophically appealing programming
language.

@ifset CLASSREF
An example of what can be obtained with Smalltalk in this novel way can be
found in @ref{Class reference}.  That part of the manual is entirely generated
by a Smalltalk program, starting from the source code for the system classes as
distributed together with the system.
@end ifset

I'd like to end this introduction reporting an article I posted to Usenet
in September 1999.  It's about @gst{}'s `place in the world' and its
comparison with another open source Smalltalk, Squeak (a new version of
Smalltalk-80 written by lots of people including the great wise behind the
original Smalltalk implementation).

@quotation
@cartouche
@noindent
Re: @gst{} and Squeak (was Re: @gst{} 1.7 development)

I enjoy discussions about the relationship between @gst{} and
Squeak, because I also think about it sometimes.  And, believe
it or not, I cannot tell which system is more ``winning''.  Actually,
they're fundamentally different---the only thing they share is that
both are free.

Squeak is Smalltalk for the pure.  Smalltalk for @emph{die-hard}
object-oriented folks.  Don't flame me please, and interpret this
article with the necessary irony and benevolence.  Why do I say
this? Because only a die-hard object-oriented folk, IMO, would
write BitBlt and real-time FM synthesis stuff in Smalltalk---even
Adele Goldberg wrote her Smalltalk implementation in Smalltalk
mostly for clarity (at least she says so).

@gst{} is Smalltalk for @emph{hacking} object-oriented folks.  You
know them: they like the object-oriented paradigm because it's clearer
and powerful, and maybe they learnt something of design too@dots{} but
they nevertheless like to toy with C and think that only pointers make
them feel like they are ``really'' programming.  Why do I say this?
Because I am one of them, and proud of it.

Having said so, I must admit that I have Squeak on my hard disk.  And
I'd be happy if one of the `great wise' behind Squeak told me he
dignated himself to have a look at my humble creation.  Because both
do have good points.  Let's take a bird's fly on them@dots{} Squeak had
LargeIntegers ever since it was born, I added them three months ago
to a ten-year old GST.  Squeak has Namespaces and I already confessed
that I'm taking inspiration from them.  But GST has closures, it has
a better compiler, better C interoperability, and (I beg your pardon
Squeakers) an easy to use window framework.

I added closures to GST in three days of work without taking extra
caffeine; the Squeak Mailing List has been wondering for two years
about when they will be finally there.  Having to choose between
1000 downloads a day and Dan Ingalls adding closures to Squeak
after peeping at my source code, I'd surely pick the second!!!

Being too loquacious?  Probably, so I stop here.  The moral is, no
civil wars between Smalltalk dialects please; let's all write good
programs and let others write good programs.  It'll surely be a better
world for both.

Paolo Bonzini
@end cartouche
@end quotation

@node Installation, Using GNU Smalltalk, Overview, Top
@chapter Installation

@menu
* Compiling::           How to compile the @gst{} system.
* More legal stuff::    Legal consequences of including Smalltalk in your
                        programs.
* Extending::           How to add your own features to @gst{}.

@end menu

@node Compiling, More legal stuff, Installation, Installation
@section Compiling @gst{}

The first thing to do to compile @gst{} is to configure the
program, creating the makefiles and a @file{gstconf.h}, which contains
guesses at the system's peculiarities.  GST comes with a
@file{gstconf.h} file which is valid for Cygnus' Win32 port of GCC
and for Visual C++, an environment which makes harder to use the
wonderful Unix tools under Windows 95/98/NT. For other systems, you
can perform this configuration automatically by the @file{configure} shell
script; to run it, merely type:
@example
     ./configure
@end example

Options that you can pass to configure include @code{--without-dld}, which
precludes Smalltalk programs from dynamically linking libraries at run-time,
and @code{--with-readline}, which will look for the @gnu{} readline library
to allow for better command line editing.
@ignore
Of particular interest is the @code{--enable-jit} option: so particular that
the whole of @ref{Dynamic translator} is devoted to it@dots{}
@end ignore

After you've configured @gst{}, you can compile the system by typing:
@example
make
@end example

Smalltalk should compile and link with no errors.  If compiling goes
wrong you might want to check the commands used to launch the compiler.
For example, be sure to check if your compiler has extensions which,
if not enabled, don't make it ANSI compatible.  If this is the case,
type
@example
make distclean
CFLAGS=@r{@var{needed command-line flags}}
@end example

@noindent
and retry the configure/make process.  In very particular cases, the
configure script might miss the presence of a header file or a function
on your system.  You can patch the @file{config.cache} file created by
the configure process.  For example, if configure did not find your
@file{unistd.h} header file, change the line reading
@example
ac_cv_header_unistd_h=$@{ac_cv_header_unistd_h='no'@}
@end example
@noindent
to
@example
ac_cv_header_unistd_h=$@{ac_cv_header_unistd_h='yes'@}
@end example

@noindent
and, again, retry the configure/make process.

After you have successfully built the @gst{} interpreter, you
can test it by invoking it.  You should be able to invoke Smalltalk,
thus:
@example
gst -V
@end example

You should see the various classes being loaded one by one.  At the end
you should see a message of the form:
@display
Processing ValueAdaptors.st
"Major GC flip@dots{} done, used space = xy%"
Smalltalk Ready

st>
@end display

At this point, you have a working @gst{}.  @emph{Congratulations!!!}

If you want to use some of the wonderful @gst{} features,
you should use the @file{modules} script.  The @file{modules} script
takes one or more directory names and creates new versions of
cfuncs.c and Makefile which include that directory's contents.
This is a major change with respect to previous versions of GST,
which forced you to write special makefiles to include more
than one feature.  For example,
@example
./modules blox
make
mv gst blox-gst
./modules blox tcp
make
@end example

will create two executables: one, blox-gst, only has support for the Blox
GUI toolkit, and one, gst, has support for both the Blox GUI toolkit and
the TCP toolkit.

You will also want to create the image file in the proper place (the
image file contains a full snapshot of the status of the system).
You could switch to the directory that you want the Smalltalk binary
image to live in, and invoke Smalltalk.  To do so, just move or copy
the image file (@file{gst.im}) to its final home.


@node More legal stuff, Extending, Compiling, Installation
@section Including @gst{} in your programs (legal information)

Believe it or not, Smalltalk is (also) a very good scripting and macro
language.  For this reason, @gst{} is distributed as a library
that you can link your programs to.  It's very simple: just include
@file{gstpub.h}, link to @file{libgst.a}, and you're done.  For more
information on what to do in your program so that it communicates
well with Smalltalk, relate to @ref{C and Smalltalk}.

In this case, your program @strong{must} be free, licensed under a
license that is compatible with the @gnu{} General Public License,
under which the @gst{} Virtual Machine is licensed.  Program that are
designed to work together with the application we bundle with @gst{}
(currently the browser and the compiler) are also subject to the
General Public License, and must be made free.

On the other hand, the core @gst{} class libraries (standard classes,
Blox, @sc{tcp} abstraction, @sc{xml} parsing) are released under the
@gnu{} Lesser General Public License.  It is not necessary (although
we would appreciate it) that programs that only use these libraries
are made free.


@node Extending, , More legal stuff, Installation
@section Adding your own features to @gst{}.

Another nice thing you can do with @gst{} is sticking to the
bare bones environment and enhance it with your own goodies.  If they're
written in Smalltalk only, no problem: you could get them to work
as packages (@pxref{Packages}), together with the @gst{} packaging
system, but that is likely to be a five-minutes task.

You should, instead, do something much more interesting if you're goodie
has C functions and you want it to work together with the @file{modules}
shell script (@pxref{Compiling}).  This section explains what
to do, taking the TCP library as a guide.

First of all, create a @file{cfuncs.h} in your directory. The TCP library's
@file{cfuncs.h} is simply
@example
CALL(initTCP);
@end example

which means: to initialize the TCP layer, call the @code{extern} function
@code{initTCP}, which in turn shall contain the required calls to
@code{defineCFunc} (@pxref{C and Smalltalk}).  Most of the times,
@file{cfuncs.h} will contain just a call to the @code{CALL} macro.

Instead, you might want to use the @code{CFUNC} macro, which defines
C functions directly from @file{cfuncs.h}: in the automatically
generated @file{cfuncs.c}, it will be defined as
@example
#define CFUNC(smalltalk, c)     \
       @{ extern void c(); defineCFunc(smalltalk, c); @}
@end example

Using @code{CFUNC} has an advantage and a disadvantage: the advantage
is that you keep all the declarations in a single file, while @code{CALL}
divides them between @file{cfuncs.h} and where you put the called
function; the disadvantage is that you will not be able to declare your C
functions as @code{static}.  For this reason, all the packages supplied
with @gst{} stick on @code{CALL}.


@node Using GNU Smalltalk, Features, Installation, Top
@chapter Using @gst{}

@menu
* Invocation::          What you can specify on the command line.
* Operation::           A step-by-step description of the
                        startup process and a short description of
                        how to interact with @gst{}.
* Syntax::              A description of the input file syntax
* Test suite::          How to run the test suite system.

@end menu

@node Invocation, Operation, Using GNU Smalltalk, Using GNU Smalltalk
@section Command line arguments

@gst{} may be invoked via the following command:
@example
gst [ flags @dots{} ] [ file @dots{} ]
@end example

When you first invoke @gst{}, it will attempt to see if any of
the kernel method definition files are newer than the last saved binary
image in the current directory (if there is one).  If there is a newer
kernel method definition file, or if the binary image file (called
@file{gst.im}) does not exist, a new binary image will be built by
loading in all the kernel method definition files, performing a full
garbage collection in order to compact the space in use, and then saving
the resulting data in a position independent format.  Your first
invocation should look something like this:

@display
"Major GC flip@dots{} done, used space = 51%"
Smalltalk Ready

st>
@end display

If you specify @var{file}, that file will be read and executed and
Smalltalk will exit when end of file is reached.  If you specify more
than one file, each will be read and processed in turn.  If you don't
specify @var{file}, standard input is read, and if the standard input is a
terminal, a prompt is issued.  You may specify @samp{-} for the name of a
file to invoke an explicit read from standard input; furthermore,
specifying @samp{--} stops the interpretation of options so that every
argument that follows is considered a file name even if it begins with
a minus.

You can specify both short and long flags; for example, @samp{--version}
is exactly the same as @samp{-v}, but is easier to remember.  Short flags
may be specified one at a time, or in a group.  A short flag or a group
of short flags always starts off with a single dash to indicate that what
follows is a flag or set of flags instead of a file name; a long flag
starts off with two consecutive dashes, without spaces between them.

In the current implementation the flags can be intermixed with file
names, but their effect is as if they were all specified first.  The
various flags are interpreted as follows:

@table @b
@item @kbd{-a --smalltalk}
Used to make arguments available to Smalltalk code.  The C option
parser discards everything after the parameter including -a, while
Smalltalk code can get it sending the @code{arguments} message to the
@code{Smalltalk} object.

Examples:
@example
command line          what the C code gets    @code{Smalltalk arguments}
gst                   gst                     #()
gst -Via foo bar      gst -Vi                 #('foo' 'bar')
gst -Vai test         gst -Vi                 #('test')
gst -Vaq              gst -Vq                 #()
gst --verbose -aq -c  gst --verbose -q        #('-c')
@end example

That should be clear.@*@*

@item @kbd{-c --core-dump}
When this flag is set and a fatal signal occurs, a core dump is
produced after an error message is printed.  Normally, the backtrace
is produced and the system terminates without dumping core. @*@*

@item @kbd{-d --user-declaration-trace}
Declaration tracing prints the class name, the method name, and
the byte codes that the compiler is generating as it compiles
methods.  Only for files that are named explicitly on the command
line; kernel files that are loaded automatically as part of
rebuilding the image file do not have their declarations traced. @*@*

@item @kbd{-D --kernel-declaration-trace}
Like the -d flag, but also includes declarations processed for the
kernel files. @*@*

@item @kbd{-e --user-execution-trace}
Prints the byte codes being executed as the interpreter operates.
Only works for those executions that occur after the kernel files
have been loaded and the image file dumped.
@ignore
This option and the following one is disabled when the dynamic
translator (@pxref{Dynamic translator}) is enabled.
@end ignore
@*@*

@item @kbd{-E --kernel-declaration-trace}
Like the -e flag, but includes all byte codes executed, whether
they occur during the loading of the kernel method definition
files, or during the loading and execution of user files. @*@*

@item @kbd{-g --no-gc-messages}
Suppress garbage collection messages. @*@*

@item @kbd{-h -H -? --help}
Prints out a brief summary of the command line syntax of @gst{},
including the definitions of all of the option flags, and then
exits. @*@*

@item @kbd{-i --rebuild-image}
Ignore the saved image file; always load from the kernel method
definition files.  Setting this flag bypasses the normal checks
for kernel files newer than the image file, or the image file's
version stamp out of date with respect to the Smalltalk version.
After the kernel definitions have been loaded, a new image file
will be saved. @*@*

@item @kbd{-I @var{file} --image-file @var{file}}
Use the image file named @var{file} as the image file to load.
Completely bypasses checking the file dates on the kernel files
and standard image file. @*@*

@item @kbd{-l --log-changes}
Produce a log of the compiled Smalltalk code to st-changes.st,
in the current working directory. @*@*

@item @kbd{-L @var{file} --log-file @var{file}}
Produce a log of the compiled Smalltalk code to the file named
@var{file}. @*@*

@item @kbd{-q --quiet --silent}
Suppress the printing of execution information while @gst{}
runs.  Messages about the beginning of execution or how many byte
codes were executed are completely suppressed when this flag is
set. @*@*

@item @kbd{-Q --no-messages}
Suppress the printing of execution information and any other
informative message while @gst{} runs.  Useful, for example,
for stand-alone shell programs such as @acronym{CGI} scripts. @*@*

@item @kbd{-r --regression-test}
Disables certain informative I/O; this is used by the regression
testing system and is probably not of interest to the general user. @*@*

@item @kbd{-s --store-no-source}
Usually, Smalltalk stores the methods' source code as FileSegments for
files in the kernel directory, and as Strings for files outside it.
This behavior minimizes problems on recompile, because FileSegments
cannot be relied upon if the source file changes.  However, storing
source code for big libraries is not useful, since the file-in source
is unlikely to change.  There are two ways to override this behavior
and make Smalltalk store everything loaded in a particular session as
FileSegments: one is to specify a directory relative to the kernel
directory, such as @file{/usr/local/smalltalk/kernel/../blox/Blox.st};
the other is to specify this option on the command line. @*@*

@item @kbd{-S --snapshot}
Save a snapshot after loading files from the command line.  Of
course the snapshot is not saved if you include - (stdin) on the
command line and exit by typing Ctrl-C. @*@*

@item @kbd{-v --version}
Prints out the Smalltalk version number, then exits. @*@*

@item @kbd{-V --verbose}
Enables verbose mode.  When verbose mode is on, various diagnostic
messages are printed (currently, only the name of each file as it's loaded). @*@*

@item @kbd{-y --yacc-debug}
Turns on parser debugging.  Not typically used.
@end table

@node Operation, Syntax, Invocation, Using GNU Smalltalk
@section Startup sequence

When @gst{} is invoked, the first thing it does is choosing
two paths, respectively the ``image path'' and the ``kernel path''.
the image path is set to the value of the @code{SMALLTALK_IMAGE}
environment variable (if it is defined);  if @code{SMALLTALK_IMAGE}
is not defined, Smalltalk will try the path compiled in the binary
(usually, under Unix systems, @file{/usr/local/share/smalltalk} or
a similar data file path) and then the current directory.

The ``kernel path'' directory in which to look for each of the
kernel method definition files.  There are only two possibilities in
this case: the directory pointed to by @code{SMALLTALK_KERNEL} if it
is defined, and a subdirectory named @file{kernel} in the current
directory.  However, kernel files are not required to be in this
directory: Smalltalk also knows about a system default location for
kernel files, which is compiled in the binary (usually, under Unix
systems, @file{/usr/local/share/smalltalk/kernel} or a similar data
file path), and which is used for kernel files not found in the
directory chosen as above.

Then, if the @code{-i} flag is not used, Smalltalk tries to find a
saved binary image file in the image path.  If this is found, it is
checked to be compatible with the current version of Smalltalk and
with the current system; Smalltalk is able to load an image created
on a system with the same @code{sizeof(long)} but different endianness
(for example, a 68k image on an x86), but not an image created on a
system with different @code{sizeof(long)} like an Alpha image on an x86.
Finally, if the images are compatible, it compares the write dates
of all of the kernel method definition files against the write date of
the binary image file.

If the image is not found, is incompatible, or older than any of the
kernel files, a new image has to be created.  The set of files that
make up the kernel is loaded, one at a time.  The list can be found in
@file{lib/lib.c}, in the @code{standardFiles} variable.  If the image
lies in the current directory, or if at least a kernel file was found
outside of the system default path, a user-dependant @file{.stpre}@footnote{
The file is called @file{_stpre} under MS-DOS and @file{.gstpre} on
the Atari ST.  Under OSes that don't use home directories it is looked
for in the current directory.}

At this point, independent of whether the binary image file was loaded
or created, any blocks that were marked as init blocks
(@pxref{A few methods}) are invoked in the order of their declaration.
After the init blocks have been executed, the user initialization file
@file{.stinit} is loaded if found in the user's home directory@footnote{The
same considerations made above hold here too.  The file is called
@file{_stinit} under MS-DOS and @file{.gstinit} on the Atari ST, and
is looked for in the current directory under OSes that don't use home
directories.}.

Finally, if there were any files specified on the command line, they are
loaded, otherwise standard input is read and executed until an EOF is
detected.  You are then able to operate @gst{} by typing in expressions to
the @samp{st>} prompt, and/or reading in files that contain Smalltalk code.

At some time, you may wish to abort what @gst{} is doing and return to the
command prompt: you can use @kbd{C-c} to do this.


@node Syntax, Test suite, Operation, Using GNU Smalltalk
@section Syntax of @gst{}

The language that Smalltalk accepts is based on the @dfn{file out} syntax as shown
in the @dfn{Green Book}, also known as @cite{Smalltalk-80: Bits of History,
Words of Advice} by Glenn Krasner.  The entire grammar of @gst{} is
described in the @file{gst.y} file, but a brief description may be in order:
@example
<statements> !
@end example
@noindent
executes the given statements immediately.  For example,

@example
16rFFFF printNl !
@end example
@noindent
prints out the decimal value of hex @code{FFFF}, followed by a newline.

@example
Smalltalk quitPrimitive !
@end example
@noindent
exits from the system.  You can also type a @kbd{C-d} to exit from Smalltalk
if it's reading statements from standard input.

@example
! @var{class expression} methodsFor: @var{category name} !
@var{method definition 1} !
@var{method definition 2} !
@dots{}
@var{method definition n} ! !
@end example

This syntax is used to define new methods in a given class.  The
@var{class expression} is an expression that evaluates to a class object,
which is typically just the name of a class, although it can be the
name of a class followed by the word @code{class}, which causes the method
definitions that follow to apply to the named class itself, rather than
to its instances.  Two consecutive bangs terminate the set of method
definitions.  @var{category name} should be a string object that describes
what category to file the methods in.

@example
!Float methodsFor: 'pi calculations'!

radiusToArea
    ^self squared * Float pi !

radiusToCircumference
    ^self * 2 * Float pi ! !
@end example

It also bears mentioning that there are two assignment operators:
@code{_} and @code{:=}.  Both are usable interchangeably, provided that they are
surrounded by spaces.  The @gst{} kernel code uses the @code{:=} form
exclusively, but @code{_} is supported a) for compatibility with previous
versions of @gst{} b) because this is the correct mapping between
the assignment operator mentioned in the Blue Book and the current ASCII
definition.  In the ancient days (like the middle 70's), the ASCII
underscore character was also printed as a back-arrow, and many terminals
would display it that way, thus its current usage.  Anyway, using @code{_}
may lead to portability problems.

The return operator, which is represented in the Blue Book as an
up-arrow, is mapped to the ASCII caret symbol @code{^}.

A complete treatment of the syntax of the language is beyond the
scope of this document.  Please refer to the included tutorial or
to the Blue Book for details of the syntax and semantics of the 
Smalltalk language.  If that's the only Smalltalk-80 book available you
can look at the @cite{Purple Book} (@cite{Smalltalk-80, the language}),
which is basically a Blue Book without the part on the implementation.  The
latter part, in fact, is also available online (HTML) at
@url{http://users.ipa.net/~dwighth/smalltalk/bluebook/bluebook_imp_toc.html}:
this, plus the Purple Book (which is still in print) essentially equals a
Blue Book for those seeking further info.


@node Test suite, , Syntax, Using GNU Smalltalk
@section Running the test suite

@gst{} comes with a set of files that provides a simple
regression test suite.

To run the test suite, you should be connected to the top-level
Smalltalk directory.  Type
@example
make check
@end example

You should see the names of the test suite files as they are processed,
but that's it.  Any other output indicates some problem.  The only
system that I know of which currently fails the test suite is the NeXT,
and this is apparently due to their non-standard C runtime libraries.

The test suite is by no means exhaustive.  @xref{Future}.


@node Features, C and Smalltalk, Using GNU Smalltalk, Top
@chapter Features of @gst{}

In this section, the features which are specific to @gst{} are
described.  These features include support for calling C functions from
within Smalltalk, accessing environment variables, and controlling
various aspects of compilation and execution monitoring.

Note that, in general, @gst{} is much more powerful than the
original Smalltalk-80, as it contains a lot of methods that are common
in today's Smalltalk implementation and are present in the ANSI
Standard for Smalltalk, but were absent in the Blue Book.  Examples
include Collection's @code{allSatisfy:} and @code{anySatisfy:} methods
and many methods in SystemDictionary (the Smalltalk dictionary's class).

@menu
* A few methods::      Assistance for debugging, informational messages,
                       environment variables, creating images and more.
* Memory access::      The direct memory accessing classes and methods.
* Namespaces::         Avoiding clashes between class names.
* Disk file-IO::       Methods for reading and writing disk files.
* Object dumping::     Methods that read and write objects in binary format.
* FileIn::             Explicitly load Smalltalk files by using the
                       @code{fileIn:} message.
* Special objects::    Methods to assign particular properties to objects.
* Context unwinding::  A way to protect execution of blocks from exceptions.
* Packages::           An easy way to install Smalltalk code into an image.

@end menu


@node A few methods, Memory access, Features, Features
@section A few methods

@table @b
@item @code{SystemDictionary snapshot}
This saves the current state of the @gst{} system to a file
called @file{gst.im}.  When you later invoke @gst{}, this file
will be used for binary loading if none of the kernel files has a more
recent file modification date, if the @gst{} version number is
the same as the one that created the image file, and if the size of the
object table has not changed between the time that the image file was
dumped and the time that the image file is loaded.  Note that the
instance's class that you send this message to is
@code{SystemDictionary}; in practice, you send this message to the sole
instance of @code{SystemDictionary}, @code{Smalltalk}. @*@*

@item @code{SystemDictionary snapshot: aString}
This operates exactly like the @code{snapshot} message above, except
that the string argument you supply is used as the name of the file to
save the image to.  However, since you currently cannot specify any
other file name for the image file to load from other than
@file{gst.im}, this capability is of limited utility (you could save
several snapshots throughout a run, and move the one that you were happy
with to @file{gst.im}). @*@*

@item @code{SystemDictionary system: aString}
This message invokes system(3), passing the string @code{aString} to
it.  It returns an integer which is whatever system(3) returns. @*@*

@item @code{SystemDictionary getenv: aString}
This message does a getenv(3) on string @code{aString}, and returns the
result.  The result is either a string, or @code{nil} if there was no
environment variable with the name @code{aString}. @*@*

@item @code{SystemDictionary addInit: aBlock}
This message adds @code{aBlock} to the set of init blocks that the system
has.  Init blocks are invoked after loading binary image files or kernel
files, but before loading any command line files or reading from
standard input.  @code{aBlock} should be a block that takes no arguments.
@*@*

@item @code{SystemDictionary backtrace}
When you send this message to a system dictionary (i.e.
@code{Smalltalk}, the only system dictionary available), it produces a
backtrace of the methods that are the ancestors of the currently
executing method.  This backtrace is exactly like the one that is
printed when the interpreter encounters an error. @*@*

@item @code{SystemDictionary executionTrace: aBoolean}
This method controls whether byte codes are printed as the interpreter
processes them or not.  It has the exact same effect as the command
line switch @code{-e}, but allows for very fine grain control of the
tracing.  Use @code{true} to enable tracing, and @code{false} to
disable tracing. @*@*

@item @code{SystemDictionary verboseTrace: aBoolean}
This method is used in conjunction with
@code{SystemDictionary executionTrace:}.  When given the argument
@code{true}, and execution tracing is on, it causes the top element of
the Smalltalk stack to be printed before each byte code is executed.
@*@*

@item @code{SystemDictionary debug}
This primitive method calls a C routine which is called @code{debug}.
This can be useful in the following way: you want to get access to dbx
or gdb at a particular point in the execution of a Smalltalk method.  There
typically is no easy way to do this.  In the @gst{} system, the
C routine called @code{debug} exists solely so that you can put a
breakpoint in it from a debugger such as @file{dbx} or @file{gdb} (it is
an empty routine, and thus harmless).  You can also put a call to the C
@code{debug} routine in the C function that you want to debug.

So, if you put a breakpoint in the @code{debug} routine, and invoke
the @code{debug} method just before the code which you want to
debug, you gain control for detailed debugging. @*@*

@item @code{SystemDictionary monitor: aBoolean}
This primitive method allows the user to enable or disable the
generation of C profiling information during the operation of the
interpreter.  You must modify the @file{Makefile} to switch the
compilation to profiling mode and recompile the entire system for this
to take effect.

When you pass @code{true} to this method, you enable the collection of
profiling data during the operation of the interpreter to be later
analyzed by the @file{gprof} program.  Passing @code{false} disables
this collection.  You can use this facility to closely monitor the
operation of the interpreter over a given set of Smalltalk code to see
where it's spending its time. @*@*

@item @code{SystemDictionary gcMessage: aBoolean}
This message allows the user to control whether a message is printed each time
the garbage collector flips between old and new space.  The default state is
@code{true}, meaning that when the garbage collector performs a flip, a message will
be printed.  If you supply @code{false} as the argument of this message,
the message generation is disabled until you turn it back on. @*@*

@item @code{SystemDictionary quitPrimitive}
Invoking this method causes an immediate and unconditional exit from @gst{}.
@end table


@node Memory access, Namespaces, A few methods, Features
@section Memory accessing methods

@gst{} provides methods for directly accessing real memory.
You may access memory either as individual bytes, or as 32 bit words.
You may read the contents of memory, or write to it.  Due to the
limitations of Integers in @gst{}, you can only deal with word
memory as 31 bit quantities.

You may also determine the real memory address of an object or the
real memory address of the OOP table that points to a given object, by
using messages to the @code{Memory} class, described below.

There are two basic classes which provide methods to access memory:
@code{ByteMemory} and @code{WordMemory}.  The methods for
these classes are as follows:

@table @b
@item @code{ByteMemory class at: address}
Returns the byte at @code{address} as an @code{Integer}.  @code{address}
is also an @code{Integer}. @*@*

@item @code{ByteMemory class at: address put: value}
Sets the byte at @code{address} (an @code{Integer}) to be @code{value} (an
@code{Integer} in the range of 0 to 255). @*@*

@item @code{WordMemory class at: address}
Returns an @code{Integer} that represents the contents of
@code{address}, which should also be an @code{Integer}.  Depending on
the machine architecture, you'll probably want to ensure that
@code{address} is a multiple of @code{CLong sizeof}. @*@*

@item @code{WordMemory class at: address put: value}
Stores the @code{Integer} @code{value} into real memory at
@code{address}.  Same alignment cautions as above. @*@*

@item @code{WordMemory bigEndian}
Answers @code{true} on machine architectures where the most significant
byte of a 32 bit integer has the lowest address (e.g. 68000 and Sparc),
and false on architectures where the least significant byte occurs at
the lowest address (e.g. Intel and VAX). @*@*

@item @code{C*Size} and @code{C*Alignment}
The @code{CIntSize}, @code{CLongSize}, @code{CShortSize}, @code{CFloatSize},
@code{CDoubleSize}, @code{CPtrSize}, @code{CDoubleAlignment} globals
are provided by the VM as part of the Smalltalk dictionary, and are there for
compatibility with previous versions of GST.  However you should not use them
and, instead, send messages like @code{CInt sizeof} or @code{CDouble alignOf}. @*@*
@end table

To find out the real memory address of an object or its OOP table
entry, you may use one of the methods described below.

@table @b
@item @code{Memory class addressOfOOP: anObject}
Returns the address of the OOP for @code{anObject}.  The address is an
@code{Integer} and will not change over time (i.e. is immune from
garbage collector action). @*@*

@item @code{Memory class addressOf: anObject}
Returns the address of the actual object that @code{anObject}
references.  Note that this address is only valid until the next GC
flip; thus it's pretty risky to count on the address returned by this
method for very long.  @*@*

@item @code{Object asOop}
Returns the index of the OOP for anObject.  This index is immume
from garbage collection and is the same value used by default as
an hash value for anObject (it is returned by Object's implementation
of @code{hash} and @code{identityHash}. @*@*

@item @code{Integer asObject}
Converts the given OOP @emph{index} (not address) back to an object.
Fails if no object is associated to the given index. @*@*

@item @code{Integer asObjectNoFail}
Converts the given OOP @emph{index} (not address) back to an object.
Returns nil if no object is associated to the given index.
@end table

Other methods in ByteArray and Memory allow to read various C types
(@code{doubleAt:}, @code{ucharAt:}, etc.).  For examples of using
@code{asOop} and @code{asObject}, look at the Blox source code in
@file{blox/BloxBasic.st}.

@node Namespaces, Disk file-IO, Memory access, Features
@section Namespaces

@i{[This section (and the implementation of namespaces in @gst{})
is based on the paper @cite{Structured Symbolic Name Spaces in
Smalltalk}, by Augustin Mrazik.]}

@subsection Introduction

The standard Smalltalk-80 programming environment supports symbolic
identification of objects in one global namespace---in the @code{Smalltalk}
system dictionary. This means that each global variable in the system
has its unique name which is used for symbolic identification of the
particular object in the source code (e.g. in expressions or
methods).  Most important global variables are classes defining the
behavior of objects.

In a development dealing with modelling of real systems, polymorphic
symbolic identification is often needed.  This means that it should be
possible to use the same name for different classes or other global
variables.  Let us mention class Module as an example which would mean
totaly different things for a programmer, for a computer technician
and for a civil engineer or an architect.

This issue becomes inevitable if we start to work in a Smalltalk
environment supporting persistence.  Polymorphism of classes becomes
necessary in the moment we start to think about storing classes in
the database since after restoring them into the running Smalltalk
image a mismatch with the current symbolic identification of the
present classes could occur.  For example you might have the class
Module already in your image with the meaning of a program module
(e.g. in a CASE system) and you might attempt to load the class
Module representing a part of the computer hardware from the database
for hardware configuration system.  The last class could get bound
to the #Module symbol in the Smalltalk system dictionary and the
other class could remain in the system as unbound class with full
functionality, however, it could not be accessed anymore at the
symbolical level in the source code.

Objects which have to be identified in the source code of methods
or message sends by their names are included in Smalltalk which is
a sole instance of SystemDictionary.  Such objects may be identified
simply by stating their name as primary in a Smalltalk statement.  The
code is compiled in the Smalitalk environment and if such a primary is
found it is bound to the corresponding object as receiver of the rest
of the message send.  In this way Smalltalk as instance of
SystemDictionary represents the sole symbolic name space in the
Smalltalk system.  In the following text the symbolic name space will
be called simply environment to make the text more clear.

@subsection Concepts

To support polymorphic symbolical identification several environments
will be needed.  The same name may be located concurrently in several
environments and point to diverse objects.

However, symbolic navigation between these environments is needed.  Before
approaching the problem of the syntax to be implemented and of its very
implementation, we have to point out which structural relations are going
to be established between environments.

Since the environment has first to be symbolically identified to gain
access to its global variables, it has to be a global variable in
another environment. Obviously, @code{Smalltalk} will be the first
environment from which the navigation begins. From @code{Smalltalk} some of
the existing environments may be seen. From these environments other
sub-environments may be seen, etc. This means that environments represent
nodes in a graph where symbolic identifications from one environment to
another one represent branches.

However, the symbolic identification should be unambiguous although it
will be polymorphic. This is why we should avoid cycles in the environment
graph. Cycles in the graph could cause also other problems in the
implementation, e.g. unability to use recursive algorithms. This is why
in general the environments build a directed acyclic graph@footnote{An
inheritance tree in the current @gst{} implementation of namespaces;
a class can fake multiple inheritance by specifying a namespace (environment,
if you prefer) as one of its pool dictionaries.}.

Let us call the partial ordering relation which occurs between the two
environments to be inheritance. Sub-environments inherits from their
super-environments.

Not only that ``inheritance'' is the standard term for the partial ordering
relation in the lattice theory but the feature of inheritance in the
meaning of object-orientation is associated with this relation. This means
that all associations of the super-environment are valid also in its
sub-environments unless they are locally redefined in the sub-environment.

A super-environment includes all its sub-enviroments as associations under
their names.  The sub-environment includes its super-environment under the
symbol @code{#Super}.  Most environments inherit from Smalltalk, the standard
root environment, but they are not required to do so; this is similar to how
most classes derive from Object, yet one can derive a class directly from
nil.  Since they all inherit from Smalltalk all global variables defined in
it, it is not necessary to define a special global variable pointing to root
in each environment.

The inheritance links to the super-environments are used in the lookup for a
potentially inherited global variable.  This includes lookups by a compiler
searching for a variable and lookups via methods such as @code{#at:} and
@code{#includesKey:}.

@subsection Syntax

Global objects of an environment (local or inherited) may be referenced by their
symbol used in the source code, e.g.
@example
            John goHome
@end example

@noindent
if the @code{#John -> aMan} association exists in the particular environment or
one of its super-environments, all along the way to the root environment.

If an object has to be referenced from another environment (i.e. which is not
on the inheritance link) it has to be referenced either relatively to the
position of the current environment (using the Super symbol), or absolutely
(using the ``full pathname'' of the object, navigating from Smalltalk through
the tree of sub-environments).

For the identification of global objects in another environment a ``pathname''
of symbols is used. The symbols are separated by blanks, i.e. the ``look'' to
be implemented is that of
@example
Smalltalk Tasks MyTask
@end example

@noindent
and of
@example
Super Super Peter.
@end example

Its similarity to a sequence of message sends is not casual, and suggests the
following syntax for write access:@footnote{Absent from the original paper.}
@example
Smalltalk Tasks MyTask: anotherTask
@end example

This resembles the way accessors are used for other objects.  As it is custom
in Smalltalk, however, we are reminded by uppercase letters that we are
accessing global objects.

@subsection Implementation

A superclass of @code{SystemDictionary} called @code{RootNamespace} has to be
defined and many of the features of Smalltalk-80 SystemDictionaries will
be hosted by that class. @code{Namespace} and @code{SystemDictionary} will in
turn become subclasses of @code{RootNamespace}.  One could wonder why is
RootNamespace superior to Namespace in the hierarchy: the answer is that
it is more convenient because root namespaces are more similar to
Dictionaries, not having to handle the burden of lookup into
super-environments.

To handle inheritance, the following methods have to be defined or redefined in
Namespace (@emph{not} in RootNamespace):

@table @asis
@item Accessors like @code{#at:ifAbsent:} and @code{#includesKey:}
Inheritance has to be implemented.

@item Enumerators like @code{#do:} and @code{#keys}
This should return @strong{all} the objects in the namespace, including
those which are inherited.
@end table

For programs to be able to process correctly the ``pathnames'' and the
accessors, this feature must be implemented directly in RootNamespace;
it is easily handled through the standard @code{doesNotUnderstand:}
message for trapping message sends that the virtual machine could not
resolve.  @code{RootNamespace} will also implement a new set of methods
that allow one to navigate through the namespace hierarchy; these parallel
those found in @code{Behavior} for the class hierarchy.

The most important task of the Namespace class is to provide organization
for the most important global objects in the Smalltalk system---for the
classes.  This importance becomes even more crucial in the structured
environments which is first of all a framework for class polymorphism.

In Smalltalk the classes have the instance variable @code{name} which holds the
name of the class. Each defined class is included in Smalltalk under this name.
In a framework with several environments the class should know the environment
in which it has been created and compiled.  This is a new variable of Class
which has to be defined and properly set in relevant methods. In the mother
environment the class should be included under its name.

Of course, any class (just like any other object) may be included concurrently
in several environments, even under different symbols in the same or in
diverse environments.  We can consider this 'alias names' of the particular
class or global variable.  However, classes may be referenced under the other
names or in other environments as their mother environment e.g. for the
purpose of intance creation or messages to he class (class methods), but
they cannot be compiled in other environment. If a class compiles its methods
it always compiles them in its mother environment even if this compilation is
requested from another environment.  If the syntax is not correct in the mother
environment, a compilation error simply occurs.

An important issue is also the name of the class answered by the class for the
purpose of its identification in diverse tools (e.g. in a browser). This has
to be change to reflect the environment in which it is shown, i.e. the
method @samp{nameIn: environment} has to be implemented and used on proper places.

These methods are not all which have to redefined in the Smalltalk system to
achieve full functionality of structured environments.  In particular, changes
have to be made to the behavior classes, to the user interface, to the
compiler, to a few classes supporting persistance.  An interesting point that
could not be noticed is that the environment is easier to use if evaluations
(@dfn{doits}) are parsed as if UndefinedObject's mother environment was
@emph{the current namespace}.

@subsection Using namespaces

Using namespaces if often merely a matter of rewriting the loading script this
way:
@example
    Smalltalk addSubspace: #NewNS!
    Namespace current: NewNS!
    @dots{}
    Namespace current: Smalltalk!
@end example

Also remember that pool dictionaries are actually ``pool namespaces'', in the
sense that including a namespace in the pool dictionaries list will
automatically include its superspaces too. Declaring a namespace as a 
pool dictionaries is similar in this way to C++'s @code{using namespace}
declaration.

Finally, be careful when working with fundamental system classes.  Although you
can use code like
@example
    Smalltalk Set variableSubclass: #Set
        @dots{}
        category: 'My application-Extensions'

@end example

@noindent
or the equivalent syntax @code{Set extend}, this approach won't work
when applied to core classes.  For example, you might be successful with
a Set or WriteStream object, but subclassing SmallInteger this way can bite
you in strange ways: integer literals will still belong to the Smalltalk
dictionary's version of the class (this holds for Arrays, Strings, etc.
too), primitive operations will still answer standard Smalltalk Integers,
and so on.  Or, variableWordSubclasses will recognize 32-bit
@code{Smalltalk LargeInteger} objects, but not LargeIntegers belonging
to your own namespace.

Unfortunately this problem is not easy to solve since Smalltalk has to cache
the OOPs of determinate class objects for speed---it would not be feasible
to lookup the environment to which sender of a message belongs every time
the @code{+} message was sent to an Integer.

So, @gst{} namespaces cannot yet solve 100% of the problem of clashes
between extensions to a class---for that you'll still have to rely on
prefixes to method names.  But they @emph{do} solve the problem of clashes
between class names and pool dictionary names, so you might want to give
them a try.  An example of using namespaces is given by the
@file{examples/Publish.st} file in the @gst{} source code directory.


@node Disk file-IO, Object dumping, Namespaces, Features
@section Disk file-IO primitive messages

Three classes (@code{FileStream}, @code{File}, @code{Directory}) allow you
to create files and access the file system in a fully object-oriented way.
@code{FileStream} objects also allow you to write raw binary data in a
portable endian-neutral format.

For more information on these classes, look in the class reference.

In addition, the three files, @code{stdin}, @code{stdout}, and @code{stderr}
are declared as global instances of @code{FileStream} that are bound to the
proper values as passed to the C virtual machine.  They can be accessed as
either @code{stdout} and @code{FileStream stdout}---the former is easier to
type, but the latter can be clearer.

Finally, @code{Object} defines four other methods: @code{print} and
@code{printNl}, @code{store} and @code{storeNl}.  These do a @code{printOn:} or
@code{storeOn:} to the ``Transcript'' object; this object, which is the sole
instance of class @code{TextCollector}, normally delegates write
operations to @code{stdout}.  If you load the Blox GUI, instead, the Transcript
Window will be attached to the Transcript object (@pxref{Blox}).


@node Object dumping, FileIn, Disk file-IO, Features
@section The @gst{} ObjectDumper

Another @gst{}-specific class, the @code{ObjectDumper} class, allows
you to dump objects in a portable, endian-neutral, binary format. Note that
you can use the @code{ObjectDumper} on ByteArrays too, thanks to another
@gst{}-specific class, @code{ByteStream}, which allows you to treat
ByteArrays the same way you would treat disk files.

For more information on the usage of the @code{ObjectDumper}, look in the
class reference.


@node FileIn, Special objects, Object dumping, Features
@section Explicitly loading files

The @code{fileIn:} message sent to the FileStream class, with a file
name as a string argument, will cause that file to be loaded into
Smalltalk.

For example,
@example
FileStream fileIn: 'foo.st' !
@end example
@noindent

will cause @file{foo.st} to be loaded into @gst{}.

@node Special objects, Context unwinding, FileIn, Features
@section Weak, finalizable, read-only objects

A few methods in Object support the creation of particular objects.
This include:

@itemize @bullet
@item
finalizable objects

@item
weak objects (i.e. objects whose contents are not considered,
during garbage collection, when scanning the heap for live objects).

@item
read-only objects (like literals found in methods)
@end itemize

They are:
@table @b
@item @code{makeWeak}
Marks the object so that it is considered weak in subsequent GC passes.
The garbage collector will consider dead an object which has references
only inside weak objects, and will replace references to such an
``almost-dead'' object with nils.@*@*

@item @code{addToBeFinalized}
Marks the object so that, as soon as it becomes unreferenced, its
@code{finalize} method is called.  Before @code{finalize} is called,
the VM implicitly removes the objects from the list of finalizable
ones.  If necessary, the @code{finalize} method can mark again
the object as finalizable, but by default finalization will only occur
once.
Note that a finalizable object is kept in memory even when it has no
references, because tricky finalizers might ``resuscitate'' the object;
automatic marking of the object as not to be finalized has the nice side
effect that the VM can simply delay the releasing of the memory associated
to the object, instead of being forced to waste memory even after
finalization happens. @*@*

@item @code{removeToBeFinalized}
Removes the to-be-finalized mark from the object.
As I noted above, the finalize code for the object does not have to
do this explicitly. @*@*

@item @code{finalize}
This method is called by the VM when there are no more references to
the object (or, of course, if it only has references inside weak objects). @*@*

@item @code{isReadOnly}
This method answers whether the VM will refuse to make changes to the
objects when methods like @code{become:}, @code{basicAt:put:},
and possibly @code{at:put:} too (depending on the implementation of the
method).
Note that @gst{} won't try to intercept assignments to fixed
instance variables, nor assignments via @code{instVarAt:put:}. Many
objects (Characters, @code{nil}, @code{true}, @code{false}, method
literals) are read-only by default. @*@*

@item @code{makeReadOnly: aBoolean}
Changes the read-only or read-write status of the receiver to that
indicated by @code{aBoolean}. @*@*
@end table

Note that, although it can be desirable to have read-only or finalizable
objects when writing particular applications, weak objects are normally
used only indirectly---instead of using the @code{#makeWeak} primitive,
one usually stores value in the so called @cite{weak collections}.  These
are easier to use because they provide additional functionality (for
example, @code{WeakArray} is able to determine whether an item has been
garbage collected, and @code{WeakSet} implements hash table functionality);
they are:

@itemize @bullet
@bulletize WeakArray
@bulletize WeakSet
@bulletize WeakKeyLookupTable
@bulletize WeakValueLookupTable
@bulletize WeakIdentitySet
@bulletize WeakKeyIdentityDictionary
@bulletize WeakValueIdentityDictionary
@end itemize

@node Context unwinding, Packages, Special objects, Features
@section The context unwinding system

When the C code files in something, the doits in the file-in are
evaluated in a different execution environment so that the file-in
is protected from errors signalled in the doit; the same also
happens, for example, when you do a C callin to Smalltalk.

Now, suppose that you want to evaluate something using Behavior's
@code{evaluate:} method.  Instead of using complex exception handling
code, the unwinding system can be used to obtain that behavior with code
as simple as this:
@example
    [ lastResult := evalFor perform: selector ] valueWithUnwind.
@end example

In fact, using @code{valueWithUnwind} arranges things so that an exception
will resume execution after the block, instead of stopping it.

This system is quite low-level, so it should not be used in most cases:
as a rule of thumb, use it only when the corresponding C code uses the
@code{prepareExecutionEnvironment}, @code{stopExecuting} and
@code{finishExecutionEnvironment} functions.  The places where I'm using
it obey this rule.  They include the exception handling system, the ST parser,
@code{Behavior>>#evalString:to:} and @code{Behavior>>#evalString:to:ifError:}.

The @code{valueWithUnwind} method is defined in @file{BlkClosure.st}, but it
mostly relies on code in the @file{ContextPart.st} file.  Here are the
methods involved in the unwinding mechanism: you can find descriptions in
the Smalltalk source code.  Note that all these methods are internal, this
reference is provided just for sake of completeness.

@itemize @bullet
@bulletize ContextPart class>>#unwind
@bulletize ContextPart class>>#unwind:
@bulletize ContextPart class>>#unwindPoints
@bulletize ContextPart>>#mark
@bulletize ContextPart>>#unmark
@bulletize ContextPart>>#returnTo:
@end itemize

@node Packages, , Context unwinding, Features
@section Packages

Thanks to Andreas Klimas' insight, @gst{} now includes a
powerful packaging system which allows one to file in components
(@i{goodies} in Smalltalk's very folkloristic terminology)
without caring of whether they need other goodies to be loaded.

The packaging system is implemented by a Smalltalk class,
@code{PackageLoader}, which looks for information about packages in
the file named (guess what) @file{packages}, in the current image
directory. There are two ways to load something using the packaging
system. The first way is to use the PackageLoader's
@code{fileInPackage:} and @code{fileInPackages:} methods.
For example:
@example
    PackageLoader fileInPackages: #('BloxTestSuite' 'Browser').
    PackageLoader fileInPackage: 'Compiler'.
@end example

The second way is to use the @file{Load.st} file which lies in the GST image
directory.  For example, start @gst{} with this command line:
@example
    gst -qK Load.st -a BloxTestSuite Browser Blox Compiler@footnote{
When using an alternate image path, don't use the -K option and pass
the full path to the @file{Load.st} script.}
@end example

and GST will automatically file in:

@itemize @bullet
@bulletize Blox, loaded first because Browser and BloxTestSuite need it
@bulletize Tokenizer, not specified on the command line, but needed by Parser
@bulletize Parser, also not specified, but needed by Browser and Compiler
@bulletize BloxTestSuite
@bulletize Browser
@bulletize Compiler (Blox is skipped because it has already been loaded)
@end itemize

Then it will save the Smalltalk image, and finally exit!

To provide support for this system, you have to give away with your
GST goodies a small file (say you call it @file{mypkg}) which looks like this:
@example
# This is the comment for the package file for
# the absolutely WONDERFUL package MyPackage

MyPackage
    MyPrereq1 MyPrereq2 C:MyCallout1 C:MyCallout2
    MyFilein1.st MyFilein2.st
    ../yourDirectoryName      # absolute or relative to kernel path
@end example

then people who install your package will only have to do
@example
    ./inst-pkg mypkg
@end example

which is a small shell script which will execute these two commands
@example
    cat packages mypkg > packages
    gst -qK Load.st -a MyPackage
@end example

    Simple, isn't it? Here is a list of the packages supplied with
@gst{} @value{VERSION}:

@itemize @bullet
@bulletize Blox (@pxref{Blox})
@bulletize BloxTestSuite (also @pxref{Blox})
@bulletize Browser (also @pxref{Blox})
@bulletize CInt
@bulletize Compiler (@pxref{Compiler})
@bulletize DLD (@pxref{Dynamic loading})
@bulletize GDBM
@bulletize Parser (also @pxref{Compiler})
@bulletize TCP (@pxref{TCP})
@bulletize Tokenizer
@bulletize WebServer (also @pxref{TCP})
@bulletize XML (@pxref{XML})
@end itemize

For examples of package declarations, have a look at the @file{packages} file
as distributed.

@node Blox, Compiler, Packages, Packages
@subsection Blox

Blox is a GUI building block tool kit.  It is an abstraction on top of the a
platform's native GUI toolkit that is common across all platforms.  Writing to
the Blox interface means your GUI based application will be portable to any
platform where Blox is supported.

Blox is based on Tcl/Tk, which constitutes the required portability layer:
instead of having to rewrite widgets and support for each platform, Blox
simply hands valid Tcl code to a standard Tcl 8.0 environment; the
abstraction from the operating system being used is then provided by Tk, which
does quite a good job of providing a user interface which is both portable and
has a native look and feel.

Alternative versions of Blox, for example based on Gtk+ and GNOME, will be
considered as soon as they can offer the same degree of portability.

Together with the toolkit, the @file{blox} directory contains a browsing
system that will allow the programmer to view the source code for existing
classes, to modify existing classes and methods, to get detailed
information about the classes and methods, and to evaluate code within
the browser.  In addition, some simple debugging tools are provided.  An
Inspector window allows the programmer to graphically inspect and modify
the representation of an object and, based on Steve Byrne's original
Blox-based browser, a walkback inspector was designed which will display
a backtrace when the program encounters an error.  Finally, the Transcript
global object is redirected to print to the transcript window instead of
printing to stdout.

This browser evolved from a Motif-based version developed around 1993
written by Brad Diller (@email{bdiller@@docent.com}). Because of legal
concerns about possible copyright infringement because his initial
implementation used parts of ParcPlace's Model-View-Controller (MVC)
message interface, he and Richard Stallman devised a new window
update scheme which is more flexible and powerful than MVC's
dependency mechanism, and allowed him to purge all the MVC elements
from the implementation.

Four years later I---Paolo Bonzini---further improved the code to employ
a better class design (for example, Brad used Dictionaries for classes
still to be fleshed out) and be aesthetically more appealing (taking
advantage of the new parser and Blox text widget, I added syntax
highlighting to the code browsers).

To start the browser you can simply type:

@display
	gst -qK blox/Run.st
@end display

This will load any requested packages, then, if all goes well, a
worksheet window with a menu named @cite{Smalltalk} will appear in the
top-left corner of the screen. You might want to file-in
@file{blox/Run.st} from your @file{.stinit} file.


@node Compiler, Dynamic loading, Blox, Packages
@subsection The Smalltalk-in-Smalltalk compiler


The Smalltalk-in-Smalltalk compiler is a nice compiler for Smalltalk code
which is written in Smalltalk itself.  Ideally, the C compiler would only
serve to bootstrap the system, then a fully working Smalltalk compiler
would start compiling methods.

The current status of the Smalltalk-in-Smalltalk compiler can be summarized
thus: it does work, but it does not work well.  This for many reasons: first
of all it is slow (10-15 times slower than the C compiler), and it does not
produce very optimized code.  Anyway it has very few bugs (it does have some),
it is a good example of programming the @gst{} system, and its source
code (found in the @file{compiler} directory) provides good insights into the
Smalltalk virtual machine: so, after all, it is not that bad. If want to give
it a try, just file in the Compiler package.

The compiler is built on a recursive descent parser which creates parse nodes
in the form of instances of subclasses of @code{STParseNode}. Then the parser
instantiates a compiler object which creates the actual method; more
information on the inner workings of the compiler can be found in the comment
for the @code{STCompiler} class.

The parser's extreme flexibility can be exploited in two ways. First, actions
are not hard-coded in the parser itself: the parser creates a parse tree,
then hands it to methods in @code{STParser} that can be overridden in
different @code{STParser} subclasses; an implementation of the ``visitor''
pattern is provided to help in dealing with parse nodes.  Second, just like
all recursive descent parsers, it is pretty easy to figure out which part
of the stream a method takes care of parsing, and you can override the
parsing methods in a subclass to do ``something interesting'' even while
a parse tree is created.

Both of these approaches to extending the @code{STParser} class are
demonstrated: the former by the compiler itself (class
@code{STFileInParser}), and the latter by the syntax highlighting engine
included with the browser (classes @code{STPluggableParser} and
@code{BCode}).


@node Dynamic loading, TCP, Compiler, Packages
@subsection Dynamic loading through the DLD package

DLD is the Dynamic LoaDer package.  This is a peculiar package in that it is
always loaded if your system supports it; currently supported architectures
include @code{dlopen} (used in Linux, BSD, Solaris and many more systems),
Win32, HPUX, @gnu{} DLD (Linux ELF), AIX and @gnu{} libtool (which includes a
portable @code{dlopen} for a lot of systems).

The DLD package enhances the C callout mechanism to automatically look for
unresolved functions in a series of program-specified libraries.  To add a
library to the list, evaluate code like the following:
@example
     DLD addLibrary: '/usr/lib/libc.a'
@end example

You will then be able to use @code{#defineCFunc:@dots{}} (@pxref{C callout})
to define all the functions in the C run-time library.  Note that this is a
potential security problem (especially if your program is SUID root under
Unix), so you might want to disable DLD when using @gst{} as an
extension language.  To disable DLD, configure @gst{} passing the
@code{--without-dld} switch.

Note that a DLD class will be present even if DLD is disabled (either
because your system is not supported, or by the @code{--without-dld}
configure switch) but any attempt to perform dynamic linking will result
in an error.

@node TCP, XML, Dynamic loading, Packages
@subsection TCP/UDP layer

@gst{} includes an almost complete abstraction of the @sc{tcp}, @sc{udp}
and @sc{ip} protocols@footnote{It only lacks support for out-of-band
data.}.  Although based on the standard @sc{bsd} sockets, this library
provides facilities such as buffering and time-out checking which a C
programmer usually has to implement manually.

The distribution includes a few tests (mostly loopback tests that
demonstrate both client and server connection), which are class methods
in @code{Socket}.  This code should guide you in the process of
creating and using both server and client sockets; after creation,
sockets behave practically the same as standard Smalltalk streams, so
you should not have particular problems.

In addition, package @code{WebServer} implements a servlet-based web
serving framework engine, including support for file servers as well
as Wiki-style servers@footnote{A Wiki is a kind of collaborative web
site, which allows one to edit the contents of a page.}; each server
is a subclass of @code{Servlet}, and different servers can live
together under different paths.  See the class side examples protocol
of WebServer to get it up and running quick.

The server is based on the @acronym{GPL}'ed WikiWorks project. For up to
date/more info go see @url{http://wiki.cs.uiuc.edu/VisualWorks/WikiWorks>}.
Many thanks go to the various people who had worked on the version on which
the server is based:

@display
Joseph Bacanskas @email{joeb@@mutual.navigant.com}
Travis Griggs @email{tgriggs@@keyww.com}
Ralph Johnson @email{johnson@@cs.uiuc.edu}
Eliot Miranda @email{eliot@@objectshare.com}
Ken Treis @email{ktreis@@keyww.com}
John Brant @email{brant@@cs.uiuc.edu}
Joe Whitesell @email{whitesell@@physsoft.com}
@end display

Apart from porting to @gst{}, a number of changes were made to the code,
including refactoring of classes, better aesthetics, authentication support,
and @acronym{HTTP} 1.1 compliance.

@node XML, , TCP, Packages
@subsection An XML parser and object model for @gst{}

The InDelv Open Source library for Smalltalk includes a World Wide Web
Consurtion @acronym{DOM} compliant object model, a Smalltalk based
@acronym{XML} parser and several related utilities.  A @gst{} port of
the library is provided in the @file{xml} subdirectory of the source tree.

Note that the @gst{} port of the library is under the @gnu{} Library
General Public License, while the other ports are under the Mozilla
Public License.  InDelv Inc. has permitted these distribution terms,
because a program under the @acronym{MPL} cannot be linked to a program
under the General Public License such as the @gst{} browser.

The library includes a non-validating @acronym{XML} parser written in
Smalltalk.  The parser is called XWalker and is stored in the
@file{XWalker.st} filein.  XWalker was developed starting from the
@acronym{SGML} parser engine included with the publicly available
SmallWalker class library.  SmallWalker was originally developed by:

@display
Kazuki YASUMATSU
@email{Kazuki.Yasumatsu@@fujixerox.co.jp}
@url{http://ring.aist.go.jp/openlab/kyasu/}
@end display

Note that there are no current plans to upgrade XWalker to a
validating parser.  The parser interface that XWalker implements is
a Smalltalk interpretation of the Java based @acronym{SAX} interface.

Once the source code is installed, the classes can be accessed by methods
defined in the @acronym{W3 DOM} Level 1 specification.  A copy of the DOM
specification has been included with this release, or it can be viewed
directly at @url{http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html}
on the Internet.  A collection of utilities are also included which are not
part of @acronym{W3 DOM} Level 1.  These include:

@table @code
@item @code{IdXMLReader}
used to parse XML input into DOM objects

@item @code{IdXMLWriter}
used to encode DOM objects as XML output

@item @code{IdDocumentAssembler}
used to build DOM documents hierarchically

@item @code{IdNodeVisitorBase}
implements the Visitor pattern for all nodes (see subclasses
for examples)

@item @code{IdFilterIterator}
@itemx @code{IdNodeSequenceIterator}
see IdSearchFilter for an example

@item @code{IdRangeImpl}
@itemx @code{IdRangeEndPoint}
implement most of the DOM level 2 Range API

@item @code{IdKernelUtilities}
@itemx @code{IdPlatformUtilities}
@itemx @code{FunctionsDOM}
general purpose utility classes
@end table

All classes include class comments which in turn include
relevant excerpts from the DOM spec; examples are provided by
@code{IdXWalkerParseAppExample} and in the class methods of
@code{IdXMLReader} and @code{IdXMLWriter}.

This release is almost fully compliant with the @acronym{W3 DOM}
Level 1 Core API (the Fundamental Interfaces).  There are four
exceptions:

@itemize @bullet
@item
the Document createEntityReference() method - since the
EntityReference interface is not fundamental and is not
yet implemented, this method returns nil

@item
the Attr specified attribute always returns false

@item
the Text splitText() method returns nil

@item
node lists (including NamedNodeList and NodeListImpl) are
not ``live'' in the way defined by @acronym{DOM} - i.e.  if
the node hierarchy changes after the node list is created,
the node list will @strong{not} be updated automatically
@end itemize

Note that the @acronym{DOM} requirement for live node lists is intended
primarily for scripting access to displayed @acronym{HTML} documents.  Since
access to displayed documents using @acronym{DOM} is not, and likely will
not be, supported in in pure @acronym{XSL} browsers, the notion of liveness
has been dropped to provide a much more efficient implementation.

The issue is as follows: it is not clear how relevant @acronym{DOM} style
access will be for displayed @acronym{XSL} output, because @acronym{XSL}
does not process a single document hierarchy in the same way that
@acronym{HTML} does.  @acronym{XSL} dynamically transforms a source
@acronym{DOM} document into a new @acronym{DOM} @cite{result tree}
for display, which may in turn have a radically different structure
than the source document.   As a result, you can not provide access
to @strong{the} displayed document since one does not explicitly exist.

Note that @acronym{DOM} Level 1 pre-dates much of the development of
@acronym{XSL} and was primarily designed for @acronym{HTML} browsers.
@acronym{XSL} is now addressing many of the features also provided
by @acronym{DOM} Level 2 such as events and user interaction.  When
@acronym{XSL} is complete, hopefully the W3 will address this issue
in further detail.  At that time, support for @acronym{DOM} liveness
may change accordingly.

The @acronym{DOM} Level 1 CDATASection and ProcessingInstruction
extended interfaces have also been implemented.  Furthermore, some
of the @acronym{DOM} Level 2 specifications have been partially implemented
including filters, iterators and ranges.  However, no attempt has
been made to exactly implement the @acronym{DOM} Level 2 interfaces.  At
this stage consider support for @acronym{DOM} Level 2 experimental and
subject to change in future releases.

@node C and Smalltalk, Tutorial, Features, Top
@chapter Interoperability between C and @gst{}

@menu
* C callout::               Calls from Smalltalk to C
* C data types::            Manipulating C data from Smalltalk.
* Smalltalk types::         Manipulating Smalltalk data from C
* Smalltalk callin::        Calls from C to Smalltalk.
* Object representation::   Manipulating your own Smalltalk objects.
* Incubator::               Protecting newly created objects from garbage
                            collections
* Other C functions::       Handling and creating OOPs.
* Using Smalltalk::         The Smalltalk environment as an extension library

@end menu

@gst{} provides powerful ways to incorporate its engine and virtual
machine through a C and Smalltalk interoperability layer which allows Smalltalk
to call C subroutines and C to call back Smalltalk methods.

@node C callout, C data types, C and Smalltalk, C and Smalltalk
@section Using the C callout mechanism

To use the C callout mechanism, you first need to inform Smalltalk about the C
functions that you wish to call.  You currently need to do this in two places:
1) you need to establish the mapping between your C function's address and the
name that you wish to refer to it by, and 2) define that function along with
how the argument objects should be mapped to C data types to the Smalltalk
interpreter.  As an example, let us use the pre-defined (to @gst{})
functions of @code{system} and @code{getenv}.

First, the mapping between these functions and string names for the functions
needs to be established in @file{cint.c}.  In the function
@code{initCFuncs}, the following code appears:
@example
extern int system();
extern char *getenv();

defineCFunc("system", system);
defineCFunc("getenv", getenv);
@end example

Any functions that you will call from Smalltalk must be similarly defined.

Second, we need to define a method that will invoke these C functions and
describe its arguments to the Smalltalk runtime system.  Such a method
is automatically generated by calling a method which is available to every
class, @code{defineCFunc:withSelectorArgs:returning:args:}.  The method that
was used in previous versions of @gst{},
@code{defineCFunc:withSelectorArgs:forClass:returning:args:}, is still
present for backward compatibility, but its use is deprecated and should
be avoided.

Here are the definitions for the two functions @code{system} and
@code{getenv} (taken from @file{CFuncs.st})
@example
SystemDictionary defineCFunc: 'system'
    withSelectorArgs: 'system: aString'
    returning: #int
    args: #(string)!

SystemDictionary defineCFunc: 'getenv'
    withSelectorArgs: 'getenv: aString'
    returning: #string
    args: #(string)!
@end example

The various keyword arguments are described below.

The arguments are as follows:

@table @b
@item @code{SystemDictionary}
This specifies where the new method should be stored.  In our case, the
method will be installed in the SystemDictionary, so that we would
invoke it thus:
@example
   Smalltalk system: 'lpr README' !
@end example

Again, there is no special significance to which class receives the
method; it could have just as well been Float, but it might look kind
of strange to see:
@example
   1701.0 system: 'mail sbb@@gnu.org' !
@end example

@item @code{defineCFunc: 'system'}
This says that we are defining the C function @code{system}.  This name
must be @strong{exactly} the same as the string passed to
@code{defineCFunc}. @*@*

@item @code{withSelectorArgs: 'system: aString'}
This defines how this method will be invoked from Smalltalk.  The name
of the method does not have to match the name of the C function; we
could have just as easily defined the selector to be @code{'rambo: fooFoo'};
it's just good practice to define the method with a similar name and
the argument names to reflect the data types that should be passed.

@item @code{returning: #int}
This defines the C data type that will be returned.  It is converted to
the corresponding Smalltalk data type.  The set of legal return types
is:
@example
   char        Single C character value
   string      A C char * value, converted to a Smalltalk string
   stringOut   A C char * value, converted to a Smalltalk string
               and then freed.
   symbol      A C char * value, converted to a Smalltalk symbol
   int         A C int value
   long        A C long value
   double      A C double value, converted to an instance of Float
   void        No returned value
   cObject     An anonymous C pointer value; useful to pass back to
               some C function later
   smalltalk   An anonymous (to C) Smalltalk data value; should have
               been passed to C at some point in the past or created
               by the program by calling other public @gst{}
               functions (@pxref{Smalltalk types}).
   <ctype>     You can pass an instance of CType or one of its
               subclasses (@pxref{C data types})
@end example

@item @code{args: #(string)}
This is an array of symbols that describes the types of the arguments
in order.  For example, to specify a to call open(2), the arguments
might look something like:
@example
   args: #(string int)
@end example

    The following argument types are supported; see above for details.

@example
   unknown     Smalltalk will make the best conversion that it can
               for this object; see the mapping table below
   boolean     passed as "char", which is promoted to "int"
   char        passed as "char", which is promoted to "int"
   string      passed as "char *"
   stringOut   passed as "char *", the contents are expected to be
               overwritten with a new C string, and the object that
               was passed becomes the new string on return
   symbol      passed as "char *"
   byteArray   passed as "char *", even though may contain NUL's
   int         passed as "int"
   long        passed as "long"
   double      passed as "double"
   variadic    an Array is expected, each of the elements of the
               array will be converted
   cObject     C object value passed as "long" or "void *"
   smalltalk   Pass the object pointer to C.  The C routine should
               treat the value as a pointer to anonymous storage.
               This pointer can be returned to Smalltalk at some
               later point in time.
   self        Pass the receiver, converting it to C like an 'unknown'
               parameter.  Parameters passed as self don't map to
               the message's arguments, instead they map to the
               message's receiver.
@end example
@end table


Table of parameter conversions:

@example
Declared param type     Object type             C parameter type used

smalltalk               anything                OOP
long                    Integer                 long
unknown/self            Integer                 long
int                     Integer                 int
char                    Integer                 int
int                     Boolean (True, False)   int
boolean                 Boolean (True, False)   int
char                    Boolean (True, False)   int
unknown/self            Boolean (True, False)   int
long                    Boolean (True, False)   long
char                    Character               int (C promotion rule)
unknown/self            Character               int
string                  String                  char *
stringOut               String                  char *
unknown/self            String                  char *
symbol                  Symbol                  char *
string                  Symbol                  char *
unknown/self            Symbol                  char *
byteArray               ByteArray               char *
unknown/self            ByteArray               char *
double                  Float                   double (C promotion)
unknown/self            Float                   double
cObject                 CObject                 void *
unknown/self            CObject                 void *
unknown/self            anything else           OOP
variadic                Array                   each element is passed
                                                according to "unknown"
@end example

@node C data types, Smalltalk types, C callout, C and Smalltalk
@section The C data type manipulation system

CType is a class used to represent C data types themselves (no storage,
just the type). There are subclasses called things like @code{C@var{mumble}CType}.
The instances can answer their size and alignment.  Their @code{valueType}
is the underlying type of data.  It's either an integer, which is interpreted
by the interpreter as the scalar type, or the underlying element type, which
is another @code{CType} subclass instance.

To make life easier, there are global variables which hold onto instances of
@code{CScalarCType}: they are called @code{C@var{mumble}Type} (like @code{CIntType},
not like @code{CIntCType}), and can be used wherever a C datatype is used.  If
you had an array of strings, the elements would be CStringType's (a specific
instance of CScalarCType).

@code{CObject} is the base class of the instances of C data.  It has a
subclass called @code{CScalar}, which has subclasses called
@code{C@var{mumble}}.  These subclasses can answer size and alignment information.

Instances of @code{CObject} holds a pointer to a C type variable.  The
variable have been allocated from Smalltalk by doing @code{@var{type} new},
where @code{@var{type}} is a @code{CType} subclass instance, or it may have been
returned through the C callout mechanism as a return value.  Thinking about
this facet of the implementation (that @code{CObject} point to C objects) tends
to confuse me when I'm thinking about having CObjects which are, say, of type
@code{long*}@dots{} so I try to think of CObject as just representing a C data
object and not thinking about the implementation.  To talk about the
@emph{type} @code{long*}, you'd create an instance of CPtrCType (because all
@code{CType} instances represent C types, not C objects), via
@example
CPtrCType elementType: CLongType.  "use the existing CLongCType instance"
@end example

To allocate one of these C objects, you'd do:
@example
longPtr := (CPtrCType elementType: CLongType) new.
@end example

Now you have a C variable of type ``long *'' accessible from longPtr.

Scalars fetch their value when sent the @code{value} message, and change
their value when sent the @code{value:} message.

CStrings can be indexed using @code{at:} with a zero based index, which
returns a Smalltalk @code{Character} instance corresponding to the indexed
element of the string.  To change the value at a given index, use
@code{at:put:}.

To produce a pointer to a character, use @code{addressAt:}.  To dereference
the string, like @code{*(char *)foo}, use @code{deref}: this returns an object
of type @code{CChar}, not a @code{Character} instance).  To replace the first
character in the string, use @code{deref:} and pass in a @code{CChar}
instance.  These operations aren't real useful for @code{CStrings}, but
they are present for completeness and for symmetry with pointers: after
all, you can say @code{*string} in C and get the first character of the string,
just like you can say @code{*string = 'f'}.

Also for symmetry (but this is useful in fact) @code{+} @code{anInteger} returns
a @code{CString} object pointing to @code{integer} bytes from the start of the string.
@code{-} acts like @code{+} if it is given an integer as its parameter.  If a
pointer is given, it returns the difference between the two pointers.

@code{incr}, @code{decr}, @code{incrBy:}, @code{decrBy:} adjust the
string either forward or backward, by either 1 or @code{n} characters.  Only the
pointer to the string is changed; the actual characters in the string
remain untouched.

@code{replaceWith:} @code{aString} replaces the string the instance points to
with the new string.  Actually, it copies the bytes from the Smalltalk String
instance aString into the C string object, and null terminates.  Be sure that
the C string has enough room!  You can also use a Smalltalk ByteArray as the
data source.

Instances of @code{CArray} represent an array of some C data.  The underlying
element type is provided by a @code{CType} subclass instance which is associated
with the @code{CPtr} instance.  They have @code{at:} and @code{at:put:} operations
just like Strings. @code{at:} returns a Smalltalk datatype for the given element
of the array (if the element type is a scalar, otherwise it returns a @code{CObject}
subclass instance whose type is that of the element type); @code{at:put:} works
similarly.  @code{addressAt:} returns a CObject subclass instance no matter what,
which you then can send @code{value} or or @code{value:} to get or set
its value.  CArray's also support @code{deref}, @code{deref:}, @code{+} and
@code{-} with equivalent semantics to CString.

CPtrs are similar to CArrays (as you might expect given the similarity between
pointers and arrays in C) and even more similar to CStrings (as you might
again expect since strings are pointers in C).  In fact both CPtrs and
CArrays are subclasses of a common subclass, CAggregate.  Just like
CArrays, the underlying element type is provided by a @code{CType} subclass
instance which is associated with the @code{CPtr} instance.

CPtr's also have @code{value} and @code{value:} which get or change the
underlying value that's pointed to. Like CStrings, they have #incr, #decr,
#incrBy: and #decrBy:.  They also have #+ and #- which do what you'd expect.

Finally, there is @code{CStruct}, an abstract subclass of @code{CObject} (it
makes sense, because its subclasses provide a way to access actual C data
objects).

They provide direct access to C data structures including
@itemize @bullet
@bulletize @code{long} (unsigned too)
@bulletize @code{short} (unsigned too)
@bulletize @code{char} (unsigned too) & byte type
@bulletize @code{double} (and @code{float})
@bulletize @code{string} (NUL terminated char *, with special accessors)
@bulletize arrays of any type
@bulletize pointers to any type
@bulletize other structs containing any fixed size types
@end itemize

Here is an example struct decl in C:
@example
struct audio_prinfo @{
    unsigned    channels;
    unsigned    precision;
    unsigned    encoding;
    unsigned    gain;
    unsigned    port;
    unsigned    _xxx[4];
    unsigned    samples;
    unsigned    eof;
    unsigned char       pause;
    unsigned char       error;
    unsigned char       waiting;
    unsigned char       _ccc[3];
    unsigned char       open;
    unsigned char       active;
@};

struct audio_info @{
    audio_prinfo_t      play;
    audio_prinfo_t      record;
    unsigned    monitor_gain;
    unsigned    _yyy[4];
@};
@end example

And here is a Smalltalk equivalent decision:
@example
CStruct newStruct: #AudioPrinfo
        declaration: #( (sampleRate uLong)
                        (channels uLong)
                        (precision uLong)
                        (encoding uLong)
                        (gain uLong)
                        (port uLong)
                        (xxx (array uLong 4))
                        (samples uLong)
                        (eof uLong)
                        (pause uChar)
                        (error uChar)
                        (waiting uChar)
                        (ccc (array uChar 3))
                        (open uChar)
                        (active uChar))
!

CStruct newStruct: #AudioInfo
        declaration: #( (play AudioPrinfo)
                        (record AudioPrinfo)
                        (monitorGain uLong)
                        (yyy (array uLong 4)))
!
@end example

This creates two new subclasses of @code{CStruct} called @code{AudioPrinfo}
and @code{AudioInfo}, with the given fields.  You can make C functions
return CObjects pointing to these instances by passing @code{AudioPrinfo type}
as the parameter to the @code{returning:} keyword.

AudioPrinfo has methods defined on it like:
@example
    #sampleRate
    #sampleRate:
    #channels
    #channels:
@end example

etc.  These access the various data members.  The array element accessors (xxx,
ccc) just return a pointer to the array itself.

For simple scalar types, just list the type name after the variable.
Here's the set of scalars names, as defined in @file{CStruct.st}:
@example
   #long                   CLong
   #uLong                  CULong
   #ulong                  CULong
   #byte                   CByte
   #char                   CChar
   #uChar                  CUChar
   #uchar                  CUChar
   #short                  CShort
   #uShort                 CUShort
   #ushort                 CUShort
   #int                    CInt
   #uInt                   CUInt
   #uint                   CUInt
   #float                  CFloat
   #double                 CDouble
   #string                 CString
   #smalltalk              CSmalltalk
@end example

To have a pointer to a type, use something like:
@example
        (example (ptr long))
@end example

To have an array pointer of size @code{@var{size}}, use:
@example
        (example (array string @var{size}))
@end example

Note that this maps to @code{char *example[@var{size}]} in C.

The objects returned by using the fields are CObjects; there is no implicit
value fetching currently.  For example, suppose you somehow got ahold of an
instance of class AudioPrinfo as described above (the instance is a CObject
subclass and points to a real C structure somewhere).  Let's say you stored
this object in variable @code{audioInfo}.  To get the current gain value, do
@example
    audioInfo gain value
@end example

to change the gain value in the structure, do
@example
    audioInfo gain value: 255
@end example

The structure member message just answers a @code{CObject instance},
so you can hang onto it to directly refer to that structure member,
or you can use the @code{value} or @code{value:} methods to access or change
the value of the member.

Note that this is the same kind of access you get if you use the
@code{addressAt:} method on CStrings or CArrays or CPtrs: they
return a CObject which points to a C object of the right type and you
need to use @code{value} and @code{value:} to access and modify the
actual C variable.



@node Smalltalk types, Smalltalk callin, C data types, C and Smalltalk
@section Manipulating Smalltalk data from C

@gst{} internally maps every object except Integers to a data
structure named an @i{OOP} (which is not an acronym for anything, as
far as I know).  An OOP is a pointer to an internal data structure;
this data structure basically adds a level of indirection in the
representation of objects, since it contains
@itemize @bullet
@item
a pointer to the actual object data

@item
a bunch of flags, most of which interest the garbage collection process
@end itemize

This additional level of indirection makes garbage collection very
efficient, since the collector is free to move an object in memory
without updating every reference to that object in the heap, thereby
keeping the heap fully compact and allowing very fast allocation of
new objects.  However, it makes C code that wants to deal with objects
even more messy than it would be without; if you want some examples,
look at the hairy code in @gst{} that deals with processes.

To shield you as much as possible from the complications of doing
object-oriented programming in a non-object-oriented environment like
C, @gst{} provides friendly functions to map between common Smalltalk
objects and C types.  This way you can simply declare OOP variables and
then use these functions to treat their contents like C data.

These functions are declared in @file{gstpub.h} and can be divided in two
groups, those that map @b{from Smalltalk objects to C data types} and those
that map @b{from C data types to Smalltalk objects}.

Here are those in the former group (Smalltalk to C); you can see that
they all begin with @code{OOPTo}:

@table @b
@item @code{extern long OOPToInt(OOP)}
This function assumes that the passed OOP is an Integer and returns the
C @code{signed long} for that integer. @*@*

@item @code{extern double OOPToFloat(OOP)}
This function assumes that the passed OOP is an Float and returns the
C @code{double} for that integer. @*@*

@item @code{extern int OOPToBool(OOP)}
This function returns a C integer which is true (i.e. @code{!= 0}) if
the given OOP is the @code{true} object, false (i.e. @code{== 0}) otherwise.
@*@*

@item @code{extern char OOPToChar(OOP)}
This function assumes that the passed OOP is a Character and returns the
C @code{char} for that integer. @*@*

@item @code{extern char *OOPToString(OOP)}
This function assumes that the passed OOP is a String or ByteArray and
returns a C null-terminated @code{char *} with the same contents.  It is
the caller's responsibility to free the pointer and to handle possible
@samp{NUL} characters inside the Smalltalk object. @*@*

@item @code{extern voidPtr OOPToCObject(OOP)}
This functions assumes that the passed OOP is a kind of CObject and
returns a C @code{voidPtr} to the C data pointed to by the object. The
caller should not free the pointer, nor assume anything about its
size and contents, unless it @b{exactly} knows what it's doing.  A
@code{voidPtr} is a @code{void *} if supported, or otherwise a @code{char *}.
@*@*

@item @code{extern long OOPToC(OOP)}
This functions assumes that the passed OOP is a String, a ByteArray, a
CObject, or a built-in object (nil, true, false, character, integer).
If the OOP is nil, it answers 0; else the mapping for each object is
exactly the same as for the above functions.  Note that, even though the
function is declared as returning a @code{long}, you might need to cast
it to either a @code{char *} or @code{voidPtr}.
@*@*

@end table

While special care is needed to use the functions above (you will probably
want to know at least the type of the Smalltalk object you're converting),
the functions below, which convert C data to Smalltalk objects, are easier
to use and also register objects for you so that they are not swept by a
garbage collection. These functions all @i{end} with @code{ToOOP}, except
@code{cObjectToTypedOOP}:

@table @b
@item @code{OOP intToOOP(long)}
This object returns a Smalltalk Integer which contains the same value as
the passed C @code{long}.  Note that Smalltalk Integers are always signed and
have a bit less of precision with respect to C longs.  On 32 bit machines,
their precision is 30 bits (if unsigned) or 31 bits (if signed); on 64 bit
machines, their precision is 62 bits (if unsigned) or 63 bits (if signed).
@*@*

@item @code{OOP floatToOOP(double)}
This object returns a Smalltalk Float which contains the same value as
the passed @code{double}.  Unlike Integers, Floats have exactly the same
precision as C doubles. @*@*

@item @code{OOP boolToOOP(int)}
This object returns a Smalltalk Boolean which contains the same boolean value
as the passed C @code{int}.  That is, the returned OOP is the sole instance of
either @code{False} or @code{True}, depending on where the parameter is
zero or not. @*@*

@item @code{OOP charToOOP(char)}
This object returns a Smalltalk Character which represents the same char
as the passed C @code{char}. @*@*

@item @code{OOP classNameToOOP(char *)}
This method returns the Smalltalk class (i.e. an instance of a subclass of
Class) whose name is the given parameter.  This method is slow; you can
safely cache its result. @*@*

@item @code{OOP stringToOOP(char *)}
This method returns a String which maps to the given null-terminated
C string, or the builtin object @code{nil} if the parameter points to
address 0 (zero). @*@*

@item @code{OOP symbolToOOP(char *)}
This method returns a String which maps to the given null-terminated
C string, or the builtin object @code{nil} if the parameter points to
address 0 (zero).  Note that symbols cannot be garbage collected (they
are always in the root set), so they're not registered: calling
@code{unregisterOOP} with a symbol as a parameter has no effect. @*@*

@item @code{OOP cObjectToOOP(voidPtr)}
This method returns a CObject which maps to the given C pointer, or the
builtin object @code{nil} if the parameter points to address 0 (zero).
The returned value has no precise CType assigned. To assign one, use
@code{cObjectToTypedOOP}. @*@*

@item @code{OOP cObjectToTypedOOP(voidPtr, OOP)},
This method returns a CObject which maps to the given C pointer, or the
builtin object @code{nil} if the parameter points to address 0 (zero).
The returned value has the second parameter as its type; to get possible
types you can use @code{typeNameToOOP}. @*@*

@item @code{OOP typeNameToOOP(char *)}
All this method actually does is evaluating its parameter as Smalltalk
code; so you can, for example, use it in any of these ways:
@example
    cIntType = typeNameToOOP("CIntType");
    myOwnCStructType = typeNameToOOP("MyOwnCStruct type");
@end example

This method is primarily used by msgSendf (@pxref{Smalltalk callin}), but
it can be useful if you use lower level call-in methods. This method is
slow too; you can safely cache its result. @*@*
@end table

As said above, the C to Smalltalk layer automatically puts the objects it
creates in a special registry (different from the incubator) which prevents
objects from being collected as garbage.  Here are the functions you may
want to use to have more control on this registry:

@table @b
@item @code{void registerOOP(OOP)}
Puts the given OOP in the registry.  If you register an object multiple times,
you will need to unregister it the same number of times.  You may want to
register objects returned by Smalltalk call-ins. @*@*

@item @code{void unregisterOOP(OOP)}
Remove an occurrence of the given OOP from the registry. @*@*
@end table

Usually, you should use the registry to protect the main object, and the
incubator to protect objects which are part of the object before they become
parts of the root set; this because the incubator is designed to unregister
multiple objects at a time, while the registry works better for objects
that should be kept registered for a relatively long time, and whose
lives in the registry typically overlap.


@node Smalltalk callin, Other C functions, Smalltalk types, C and Smalltalk
@section Calls from C to Smalltalk


@gst{} provides seven different function calls that allow you to call
Smalltalk methods in a different execution context than the current one. The
priority in which the method will execute will be the same as the one of
Smalltalk process which is currently active.

Four of these functions are more low level and are more suited when the
Smalltalk program itself gave a receiver, a selector and maybe some
parameters; the others, instead, are more versatile.  One of them
(@code{msgSendf}) automatically handles most conversions between C data
types and Smalltalk objects, while the others takes care of compiling full
snippets of Smalltalk code.

All these functions handle properly the case of specifying, say, 5 arguments
for a 3-argument selector---see the description of the single functions
for more information).


@table @b
@item @code{OOP msgSend (OOP receiver, OOP selector, @dots{})}
This function sends the given selector (should be a Symbol, otherwise nilOOP
is returned) to the given receiver.  The message arguments should also be
OOPs (otherwise, an access violation exception is pretty likely) and are
passed in a NULL-terminated list after the selector.  The value returned
from the method is passed back as an OOP to the C program as the result
of @code{msgSend}, or nilOOP if the number of arguments is wrong.  Example
(same as @code{1 + 2}):

@example
    OOP shouldBeThreeOOP = msgSend(
        intToOOP(1),
        symbolToOOP("+"),
        intToOOP(2),
        nil);
@end example

@item @code{OOP strMsgSend (OOP receiver, char *selector, @dots{})}
This function is the same as above, but the selector is passed as a
C string and is automatically converted to a Smalltalk symbol.

Theoretically, this function is a bit slower than @code{msgSend} if
your program has some way to cache the selector and avoiding a call to
@code{symbolToOOP} on every call-in.  However, this is not so apparent
in ``real'' code because the time spent in the Smalltalk interpreter
will usually be much higher than the time spent converting the selector
to a Symbol object.  Example:

@example
    OOP shouldBeThreeOOP = strMsgSend(
        intToOOP(1),
        "+",
        intToOOP(2),
        nil);
@end example

@item @code{OOP vmsgSend (OOP receiver, OOP selector, OOP *args)}
This function is the same as msgSend, but accepts a pointer to the
NULL-terminated list of arguments, instead of being a variable-arguments
functions.  Example:

@example
    OOP arguments[2], shouldBeThreeOOP;
    arguments[0] = intToOOP(2);
    arguments[1] = nil;
    /* @dots{} some more code here @dots{} */

    shouldBeThreeOOP = vmsgSend(
        intToOOP(1),
        symbolToOOP("+"),
        arguments);
@end example

@item @code{OOP nvmsgSend (OOP receiver, OOP selector, OOP *args, int nargs)}
This function is the same as msgSend, but accepts an additional parameter
containing the number of arguments to be passed to the Smalltalk method,
instead of relying on the NULL-termination of args.  Example:

@example
    OOP argument, shouldBeThreeOOP;
    argument = intToOOP(2);
    /* @dots{} some more code here @dots{} */

    shouldBeThreeOOP = nvmsgSend(
        intToOOP(1),
        symbolToOOP("+"),
        &argument,
        1);
@end example
@end table

The two functions that directly accept Smalltalk code are named
@code{evalCode} and @code{evalExpr}, and they're basically the same.
They both accept a single parameter, a pointer to the code to be
submitted to the parser.  The main difference is that @code{evalCode}
discards the result, while @code{evalExpr} returns it to the caller
as an OOP.

@code{msgSendf}, instead, has a radically different syntax. Let's
first look at some examples.

@example
    /* 1 + 2 */
    int shouldBeThree;
    msgSend(&shouldBeThree, "%i %i + %i", 1, 2)

    /* aCollection includes: 'abc' */
    OOP aCollection;
    int aBoolean;
    msgSend(&aBoolean, "%b %o includes: %s", aCollection, "abc")

    /* 'This is a test' printNl -- in two different ways */
    msgSendf(nil, "%v %s printNl", "This is a test");
    msgSendf(nil, "%s %s printNl", "This is a test");

    /* 'This is a test', ' ok?' */
    char *str;
    msgSendf(&str, "%s %s , %s", "This is a test", " ok?");
@end example

As you can see, the parameters to msgSendf are, in order:

@itemize @bullet
@item
A pointer to the variable which will contain the record. If this
pointer is nil, it is discarded. @*@*

@item
A description of the method's interface in this format
(the object types, after percent signs, will be explained later in
this section)

@example
%result_type %receiver_type selector %param1_type %param2_type
@end example

@item
A C variable or Smalltalk object (depending on the type specifier) for the
receiver

@item
If needed, The C variables and/or Smalltalk object (depending on the type
specifiers) for the arguments.
@end itemize

Note that the receiver and parameters are NOT registered in the object
registry (@pxref{Smalltalk types}).  @dfn{receiver_type} and
@dfn{paramX_type} can be any of these characters, with these meanings:

@example
      Specifier        C data type        equivalent Smalltalk class
          i                long           Integer (see intToOOP)
          f               double          Float (see floatToOOP)
          b                int            True or False (see boolToOOP)
          c                char           Character (see charToOOP)
          C               voidPtr         CObject (see cObjToOOP)
          s               char *          String (see stringToOOP)
          S               char *          Symbol (see symbolToOOP)
          o                OOP            any
          t            char *, voidPtr    CObject (see below)
          T              OOP, voidPtr     CObject (see below)
@end example

@noindent
@samp{%t} and @samp{%T} are particular in the sense that you need to
pass @i{two} additional arguments to @code{msgSendf}, not one.  The first
will be a description of the type of the CObject to be created, the
second instead will be the CObject's address.  If you specify @samp{%t},
the first of the two arguments will be converted to a Smalltalk
@code{CType} via @code{typeNameToOOP} (@pxref{Smalltalk types}); instead,
if you specify @samp{%T}, you will have to directly pass an OOP for the
new CObject's type.

The type specifiers you can pass for @dfn{result_type} are a bit different:

@example
            Result
Specifier   if nil    C data type      expected result
   i         0L          long          nil or an Integer
   f         0.0        double         nil or an Float
   b          0          int           nil or a Boolean
   c        '\0'         char          nil or a Character
   C        NULL        voidPtr        nil or a CObject
   s        NULL        char *         nil, a String, or a Symbol
   ?         0      char *, voidPtr    See oopToC
   o       nilOOP        OOP           any (result is not converted)
   v                      /            any (result is discarded)
@end example

Note that, if resultPtr is nil, the @dfn{result_type} is always treated
as @samp{%v}.  If an error occurs, the value in the `result if nil' column
is returned.

@node Other C functions, Object representation, Smalltalk callin, C and Smalltalk
@section Other functions in @file{libgst.a}

In addition to the functions above, @file{gstpub.h} exports many other
functions and macros that aid in developing @gst{} extensions in
C.  This node documents these functions.

You should always assume that they are implemented as macros, and thus only
pass arguments @emph{without side effects}.

@table @b
@item @code{void asyncSignal(OOP)}
This functions accepts an OOP for a @code{Semaphore} object and signals that
object so that one of the processes waiting on that semaphore is waken up.
Since a Smalltalk call-in is not an atomic operation, the correct way to
signal a semaphore is not to send the @code{signal} method to the object but,
rather, to use:

@example
    asyncSignal(semaphoreOOP)
@end example

The signal request will be processed as soon as the next bytecode is executed.
@*@*

@item @code{OOP objectAlloc(OOP)}
@itemx @code{OOP objectAlloc(OOP, int)}
The @code{objectAlloc} function allocates an OOP for a newly created instance
of the class whose OOP is passed as the first parameter; if that parameter is
not a class the results are undefined (for now, read as ``the program will
most likely core dump'', but that could change in a future version).

The second parameter is used only if the class is an indexable one, otherwise
it is discarded; the same warning above holds if you don't pass the second
argument but the class is indexable.  Simple uses of @code{objectAlloc}
include:

@example
     OOP myClassOOP;
     OOP myNewObject;
     myNewObjectData obj;
     @dots{}
     myNewObject = objectAlloc(myClassOOP);
     incAddOOP(myNewObject);
     obj = (myNewObjectData) oopToObj(myNewObject);
     obj->arguments = objectAlloc(classNameToOOP("Array"), 10);
     incAddOOP(obj->arguments);
     @dots{}
@end example

@item @code{mst_Object oopToObj(OOP)}
Dereference a pointer to an OOP into a pointer to the actual object
data (@pxref{Object representation}).  The result of @code{oopToObj}
is not valid anymore if a garbage-collection happens; for this reason,
you should assume that a pointer to object data is not valid after
doing a call-in, calling @code{objectAlloc}, and caling any of the
``C to Smalltalk'' functions (@pxref{Smalltalk types}). @*@*

@item @code{mst_Boolean oopIsReadOnly(OOP)}
Answer whether or not the given OOP is read-only
(@pxref{Special objects}).  Note that being read-only only
limits access to indexed instance variables from Smalltalk code.  Fixed
instance variables, usage of @code{instVarAt:put:} and C accesses cannot
be write-protected. @*@*

@item @code{makeOOPReadOnly(OOP, mst_Boolean)}
Set whether or not the given OOP is read-only. @*@*

@item @code{markOOPToFinalize(OOP, mst_Boolean)}
Set whether or not the given OOP is a `finalizable' oop.
(@pxref{Special objects}). @*@*

@item @code{makeOOPWeak(OOP, mst_Boolean)}
Set whether or not the given OOP is a `weak' oop (@pxref{Special objects}).
@*@*

@item @code{OOP oopClass(OOP)}
Return the OOP for the class of the given object.  For example,
@code{oopClass(stringToOOP("Wonderful @gst{}"))} is the @code{String}
class, as returned by @code{classNameToOOP("String")}. @*@*

@item @code{mst_Boolean isClass(OOP, OOP)}
Return whether the class of the OOP passed as the first parameter is the
OOP passed as the second parameter.

@item @code{mst_Boolean isInt(OOP)}
Return a Boolean indicating whether or not the OOP is an Integer object;
the value of Integer objects is encoded directly in the OOP, not separately
in a @code{mst_Object} structure.  It is not safe to use @code{oopToObj}
and @code{oopClass} if @code{isInt} returns false. @*@*

@item @code{mst_Boolean isOOP(OOP)}
Return a Boolean indicating whether or not the OOP is a `real' object
(and not an Integer).  It is safe to use @code{oopToObj} and @code{oopClass}
only if @code{isOOP} returns true. @*@*

@item @code{mst_Boolean isNil(OOP)}
Return a Boolean indicating whether or not the OOP points to @code{nil},
the undefined object. @*@*

@item @code{mst_Boolean arrayOOPAt(mst_Object, int)}
Access the character given in the second parameter of the given Array
object.  Note that this is necessary because of the way @code{mst_Object}
is defined, which prevents @code{indexedOOP} from working. @*@*

@item @code{mst_Boolean stringOOPAt(mst_Object, int)}
Access the character given in the second parameter of the given String
or ByteArray object.  Note that this is necessary because of the way
@code{mst_Object} is defined, which prevents @code{indexedByte} from
working. @*@*

@item @code{mst_Boolean indexedWord(@var{some-object-type}, int)}
Access the given indexed instance variable in a @code{variableWordSubclass}.
The first parameter must be a structure declared as described in
@ref{Object representation}). @*@*

@item @code{mst_Boolean indexedByte(@var{some-object-type}, int)}
Access the given indexed instance variable in a @code{variableByteSubclass}.
The first parameter must be a structure declared as described in
@ref{Object representation}). @*@*

@item @code{mst_Boolean indexedOOP(@var{some-object-type}, int)}
Access the given indexed instance variable in a @code{variableSubclass}.
The first parameter must be a structure declared as described in
@ref{Object representation}). @*@*

@end table


@node Object representation, Incubator, Other C functions, C and Smalltalk
@section Manipulating instances of your own Smalltalk classes from C

Although @gst{}'s library exposes functions to deal with instances
of the most common base class, it's likely that, sooner or later, you'll
want your C code to directly deal with instances of classes defined by
your program.  There are three steps in doing so:

@itemize @bullet
@bulletize Defining the Smalltalk class
@bulletize Defining a C @code{struct} that maps the representation of the class
@bulletize Actually using the C struct
@end itemize

In this chapter you will be taken through these steps considering the
hypotetical task of defining a Smalltalk interface to an SQL server.

The first part is also the simplest, since defining the Smalltalk class
can be done in a single way which is also easy and very practical; just
evaluate the standard Smalltalk code that does that:

@example
    Object subclass: #SQLAction
	   instanceVariableNames: 'database request'
	   classVariableNames: ''
	   poolDictionaries: ''
	   category: 'SQL-C interface'

    SQLAction subclass: #SQLRequest
	   instanceVariableNames: 'returnedRows'
	   classVariableNames: ''
	   poolDictionaries: ''
	   category: 'SQL-C interface'
@end example

To define the C @code{struct} for a class derived from Object, @gst{}'s
@code{gstpub.h} include file defines an @code{OBJ_HEADER} macro which defines
the fields that constitute the header of every object.  Defining a @code{struct}
for SQLAction results then in the following code:

@example
    struct st_SQLAction @{
        OBJ_HEADER;
        OOP database;
        OOP request;
    @}
@end example

The representation of SQLRequest in memory is this:

@example
    .------------------------------.
    |     common object header     |	2 longs
    |------------------------------|
    | SQLAction instance variables |
    |           database           |	2 longs
    |           request            |
    |------------------------------|
    | SQLRequest instance variable |
    |         returnedRows         |    1 long
    '------------------------------'
@end example

A first way to define the struct would then be:
@example
    typedef struct st_SQLAction @{
        OBJ_HEADER;
        OOP database;
        OOP request;
        OOP returnedRows;
    @} *SQLAction;
@end example

but this results in a lot of duplicated code.  Think of what would
happen if you had other subclasses of @code{SQLAction} such as
@code{SQLObjectCreation}, @code{SQLUpdateQuery}, and so on! The solution,
which is also the one used in @gst{}'s source code is to define a
macro for each superclass, in this way:

@example
    /* SQLAction
        |-- SQLRequest
        |     `-- SQLUpdateQuery
        `-- SQLObjectCreation       */

    #define ST_SQLACTION_HEADER		\
        OBJ_HEADER;			\
        OOP database;			\
        OOP request			/* no semicolon */

    #define ST_SQLREQUEST_HEADER	\
        ST_SQLACTION_HEADER;		\
        OOP returnedRows		/* no semicolon */

    typedef struct st_SQLAction @{
        ST_SQLACTION_HEADER;
    @} *SQLAction;

    typedef struct st_SQLRequest @{
        ST_SQLREQUEST_HEADER;
    @} *SQLRequest;

    typedef struct st_SQLObjectCreation @{
        ST_SQLACTION_HEADER;
        OOP newDBObject;
    @} *SQLObjectCreation;

    typedef struct st_SQLUpdateQuery @{
        ST_SQLREQUEST_HEADER;
        OOP numUpdatedRows;
    @} *SQLUpdateQuery;
@end example

Note that the macro you declare is used instead of @code{OBJ_HEADER} in the
declaration of both the superclass and the subclasses.

Although this example does not show that, please note that you should not
declare anything if the class has indexed instance variables.

The first step in actually using your structs is obtaining a pointer to
an OOP which is an instance of your class.  Ways to do so include doing
a call-in, receiving the object from a call-out (using @code{#smalltalk},
@code{#unknown} or @code{#self} as the type specifier).

Let's assume that the @code{oop} variable contains such an object.
Then, you have to dereference the OOP (which, as you might recall from
@ref{Smalltalk types}, point to the actual object only indirectly) and
get a pointer to the actual data.  You do that with the @code{oopToObj}
macro (note the type casting):

@example
    SQLAction action = (SQLAction) oopToObj(oop);
@end example

Now you can use the fields in the object like in this pseudo-code:

@example
    /* These are retrieved via classNameToOOP and then cached in global
       variables */
    OOP sqlUpdateQueryClass, sqlActionClass, sqlObjectCreationClass;
    @dots{}
    invokeSQLQuery(
        oopToCObject(action->database),
        oopToString(action->request);
        sqlQueryCompletedCallback,	/* Callback function */
        oop);				/* Passed to the callback */

    @dots{}
    /* Imagine that invokeSQLQuery runs asynchronously and calls this
       when the job is done. */
    void
    sqlQueryCompletedCallback(result, database, request, clientData)
    QueryResult *result;
    DB *database;
    char *request;
    OOP clientData;
    @{
        SQLUpdateQuery query;
        OOP rows;
        OOP cObject;

        /* Free the memory allocated by oopToString */
        free(request);
        
        if (isClass(oop, sqlActionClass))
            return;
        
        if (isClass(oop, sqlObjectCreationClass)) @{
            SQLObjectCreation oc;
            oc = (SQLObjectCreation) oopToObj(clientData);
            cObject = cObjectToOOP(result->dbObject)
            oc->newDBObject = cObject;
        @} else @{
            /* SQLRequest or SQLUpdateQuery */
            cObject = cObjectToOOP(result->rows);
            query = (SQLUpdateQuery) oopToObj(clientData);
            query->returnedRows = cObject;
            if (isClass(oop, sqlUpdateQueryClass)) @{
                query->numReturnedRows = intToOOP(result->count);   <<<
            @}
        @}
        unregisterOOP(cObject);		/* no need to force it alive */
    @}

@end example

Note that the result of @code{oopToObj} is not valid anymore if a
garbage-collection happens; for this reason, you should assume that
a pointer to object data is not valid after doing a call-in, calling
@code{objectAlloc}, and using any of the ``C to Smalltalk'' functions
except @code{intToOOP} (@pxref{Smalltalk types}).  That's why I passed
the OOP to the callback, not the object pointer itself.

Note that in the line marked @samp{<<<} I did not have to reload the
@code{query} variable because I used @code{intToOOP}.  If I used any other
function, I would have had to create all the required objects (using,
if needed, the incubator described in @ref{Incubator}), dereference the
pointer, and store the data in the object.

Also, you should remember to unregister every object created with the
``C to Smalltalk'' fnctions (again, with the exception of @code{intToOOP}).

If your class has indexed instance variables, you can use the
@code{indexedWord}, @code{indexedOOP} and @code{indexedByte} macros
declared in @code{gstpub.h}, which return an lvalue for the given indexed
instance variable---for more information, @pxref{Other C functions}.


@node Incubator, Using Smalltalk, Object representation, C and Smalltalk
@section Incubator support

The incubator concept provides a mechanism to protect newly created
objects from being accidentally garbage collected before they can be
attached to some object which is reachable from the root set.

If you are creating some set of objects which will not be immediately (that means,
before the next object is allocated from the Smalltalk memory system) be
attached to an object which is still ``live'' (reachable from the root set
of objects), you'll need to use this interface.

The interface provides the following operations:

@table @b
@item @code{void incAddOOP(OOP anOOP)}
Adds a new object to the protected set. @*@*

@item @code{IncPtr incSavePointer()}
Retrieves the current incubator pointer.  Think of the incubator as a
stack, and this operation returns the current stack pointer for later
use (restoration) with the incRestorePointer function. @*@*

@item @code{void incRestorePointer(IncPtr ptr)}
Sets (restores) the incubator pointer to the given pointer value. @*@*
@end table

Typically, when you are within a function which allocates more than one
object at a time, either directly or indirectly, you'd want to use the
incubator mechanism.  First you'd save a copy of the current pointer
in a local variable.  Then, for each object you allocate (except the last,
if you want to be optimal), after you create the object you add it to
the incubator's list.  When you return, you need to restore the
incubator's pointer to the value you got with incSavePointer using
the incRestorePointer function.

Here's an example from cint.c:

The old code was (the comments are added for this example):

@example
  desc = (CFuncDescriptor)newInstanceWith(cFuncDescriptorClass, numArgs);
  desc->cFunction = cObjectNew(funcAddr);    // 1
  desc->cFunctionName = stringNew(funcName); // 2
  desc->numFixedArgs = fromInt(numArgs);
  desc->returnType = classifyTypeSymbol(returnTypeOOP, true);
  for (i = 1; i <= numArgs; i++) @{
    desc->argTypes[i - 1] = classifyTypeSymbol(arrayAt(argsOOP, i), false);
  @}

  return (allocOOP(desc));
@end example

@code{desc} is originally allocated via @code{newInstanceWith} and
@code{allocOOP}, two private routines which are encapsulated by the
public routine @code{objectAlloc}.  At ``1'', more storage is allocated,
and the garbage collector has the potential to run and free (since no
live object is referring to it) desc's storage.  At ``2'' another object
is allocated, and again the potential for losing both desc and
desc->cFunction is there if the GC runs (this actually happened!).

To fix this code to use the incubator, modify it like this:

@example
  OOP     descOOP;
  IncPtr  ptr;

  incPtr = incSavePointer();
  desc = (CFuncDescriptor)newInstanceWith(cFuncDescriptorClass, numArgs);
  descOOP = allocOOP(desc);
  incAddOOP(descOOP);

  desc->cFunction = cObjectNew(funcAddr);
  incAddOOP(desc->cFunction);

  desc->cFunctionName = stringNew(funcName);
  /* since none of the rest of the function (or the functions it calls)
   * allocates any storage, we don't have to add desc->cFunctionName
   * to the incubator's set of objects, although we could if we wanted
   * to be completely safe against changes to the implementations of
   * the functions called from this function.
   */

  desc->numFixedArgs = fromInt(numArgs);
  desc->returnType = classifyTypeSymbol(returnTypeOOP, true);
  for (i = 1; i <= numArgs; i++) @{
    desc->argTypes[i - 1] = classifyTypeSymbol(arrayAt(argsOOP, i), false);
  @}

  incRestorePointer(ptr);
  return (descOOP);
@end example

Note that it is permissible for a couple of functions to cooperate with
their use of the incubator.  For example, say function A allocates
some objects, then calls function B which allocates some more objects,
and then control returns to A where it does some more execution with the
allocated objects.  If B is only called by A, B can leave the management
of the incubator pointer up to A, and just register the objects it
allocates with the incubator.  When A does a incRestorePointer, it
automatically clears out the objects that B has registered from the
incubator's set of objects as well; the incubator doesn't know about
functions A & B, so as far as it is concerned, all of the registered
objects were registered from the same function.



@node Using Smalltalk, , Incubator, C and Smalltalk
@section Using the Smalltalk environment as an extension library

If you are reading this chapter because you are going to write
extensions to @gst{}, this section won't probably interest
you.  But if you intend to use @gst{} as a scripting language
or an extension language for your future marvellous software projects,
you might be interest.

How to initialize @gst{} is most briefly and easily explained by
looking at @gst{}'s own source code.  For this reason, here are
two snippets from @file{main.c} and @file{lib/lib.c}.

@example

/* From main.c */
int main(argc, argv)
int     argc;
char    **argv;
@{
  smalltalkArgs(argc, argv);
  initSmalltalk();
  topLevelLoop();

  exit(0);
@}

/* From cint.c */
void initUserCFuncs()
@{
@}

void initCFuncs()
@{
  /* Access to command line args */
  defineCFunc("getArgc", getArgc);
  defineCFunc("getArgv", getArgv);

  /* Test functions */
  defineCFunc("testCallin", testCallin);
  defineCFunc("testCString", testCString);
  defineCFunc("testCStringArray", testCStringArray);

  /* @dots{} */

  /* Initialize any user C function definitions. initUserCFuncs,
     defined in cfuncs.c, is overridden by explicit definition
     before linking with the Smalltalk library. */
  initUserCFuncs();
@}

/* From the automatically generated cfuncs.c, after preprocessing */
void
initUserCFuncs()
@{
  initBlox();
  initTCP();
@}

@end example

Your initialization code will be almost the same as that in @gst{}'s
@code{main()}, with the exception of the call to @code{topLevelLoop}.
All you'll have to do is to pass some arguments to the @gst{} library
via @code{smalltalkArgs}, and then call @code{initSmalltalk}.

Note that @code{initSmalltalk} will likely take some time (from a second
to 30-40 seconds), because it has to check if the image file must be
be rebuilt and, if so, it reloads and recompiles the 27000 lines of
Smalltalk code in a basic image.  To avoid this check, pass a
@samp{-I} flag:

@example
char myArgv[][] = @{ "-I", "myprog.im", nil @};
int myArgc;
/* @dots{} */
myArgc = sizeof(myArgv) / sizeof (char *) - 1;
smalltalkArgs(myArgc, myArgv);
@end example


If you're using @gst{} as an extension library, you might
also want to disable the Smalltalk dictionary's @code{quitPrimitive}
and @code{quitPrimitive:} method.  I advice you not to change the
Smalltalk kernel code.  Instead, in the script that loads your
extension classes add these two lines:

@example
Smalltalk class compile: 'quitPrimitive        self shouldNotImplement'!
Smalltalk class compile: 'quitPrimitive: n     self shouldNotImplement'!
@end example

which will effectively disable the two offending methods.  Other
possibilities include using @code{atexit} (from the C library) to
exit your program in a less traumatic way, or redefining these two
methods to exit through a call out to a C routine in your program.

Another important thing is the @code{initUserCFuncs}, which as you can
see for the source code above is an hook from which anybody can declare
his/her own C call-outs.  The default implementation of
@code{initUserCFuncs}, as the library exports it, does nothing, but you
can redefine it to place your calls to @code{defineCFunc} there.

Also, note that it is not a problem if you develop the class libraries
for your programs within @gst{}'s environment @b{without}
@code{defineCFunc}-ing your own C call-outs, since @gst{}
recalculates the addresses of the C call-outs every time it is started.


@ifset CLASSREF
@node Tutorial, Class reference, C and Smalltalk, Top
@include tutorial.txi

@node Class reference, Future, Tutorial, Top
@chapter Class reference
@include classes.txi

@node Future, Acknowledgements, Class reference, Top
@end ifset

@ifclear CLASSREF
@node Tutorial, Future, C and Smalltalk, Top
@include tutorial.txi

@node Future, Acknowledgements, Tutorial, Top
@end ifclear
@chapter Future directions for @gst{}

Presented below is the set of tasks that I feel need to be performed
to make @gst{} a more fully functional, viable system.  They are
presented in no particular order; other tasks are listed in the
@file{docs/todo} file.  I would @emph{very much} welcome any
volunteers who would like to help with the implementation of one or
more of these tasks.  Please write to me, Paolo Bonzini, at
@email{bonzini@@gnu.org} if you are interested in adding your efforts
to the @gst{} project.

Tasks:
@itemize @bullet
@item
Port to other computers/operating systems.  The code thus far has
shown itself to be relatively portable to various machines and
Unix derivatives.  The architecture must support 32 or 64 bit
pointers the same size as a long integers.  Actually, even though
code to support 64 bit architectures is there, it is broken right now.

@item
Comment the C code more thoroughly.  The C source code could
definitely stand better commenting.

@item
Modify the Delay class primitive so that it does not fork a
new process each time it is called; this involves using a pipe.
I want to do it somewhen, but if you do it before me, please
tell me.

@item
Add more test cases to the test suite.  It is getting larger, but
one good way to help, and learn some Smalltalk in the process, is
still to add files and tests to the test suite directory.  Ideally,
the test suite would be used as the ``go/nogo'' gauge for whether a
particular port or improvement to @gst{} is really working properly.

@item
Improve the byte-code interpreter's efficiency.  This could bring
major performance boosts, but it is hard to figure out where to put
your hands on.  Anyway, if you find a way to add even just 5 percent
of performance, that is important too and I'll be happy to hear from
you.  The area that needs more work (I think it is possible to gain
another 15-20% here!) is message sends and handling of contexts.

@end itemize

Also, following is a brief description of the differences and
between @gst{} and ``Blue Book'' Smalltalk (Smalltalk-80).

@itemize @bullet
@item
For speed, the `return builtin object (self true, false, nil)'
bytecodes behave like the `return to the caller' bytecode,
not like the `return from method' bytecode as in the Book; also,
the latter bytecode must be issued from inside a block, while
and returns outside blocks use the former bytecode.

@item
Blocks are compiled and implemented in a completely different and
more modern way (see @file{lib/comp.c} for more information).

@item
Compiled methods are not split in a variable subclass and a
variable byte subclass part---instead they are variable byte
subclasses with fixed instance variables.  Also, they have a
different header format.  If you use the standard accessors
defined in the @code{CompiledMethod} class instead of directly
poking at the instance variables, this should be transparent.
@end itemize


@node Acknowledgements, , Future, Top
@chapter Acknowledgements

@heading The tutorial
Thanks to Steve Byrne for writing @gst{} in the
first place. Great thanks to Mark Bush and Bob Roos for
their meticulous jobs of proofreading this document, and the
generous amounts of input they provided on refinements to
the contents and structure. Thanks also to Andrew Berg for
his comments on the early chapters of the document.

This document is provided as-is, without warranty,
but I will happily accept reports of any errors. If time
permits, I will perhaps even release a corrected revision of
the document.

I release this document into the public domain, and
simply request that you acknowledge me as the original
author in any use or derivative work you make of this document.

@example
                         Andy Valencia
                         325 Union Ave #359
                         Campbell, CA 95008
                         @email{jtk@@netcom.com}@footnote{Not checked.}
                         November 27, 1992
@end example


@heading The program
I would like to publically thank the following people, who have
helped out in one way or another with the 1.1.5 release of @gst{}:
Fritz Nordby, Michael Mellinger, Doug McCallum,
Karl Berry, Dave Bodenstab, Brad Diller, Mark Wadsworth, Bill Trost,
William Cook, Trip Becket, Alan Knight, Alistair Grant, Michael
Richardson, Andrew Gelsey, Kevin Hester, David MacKenzie, Doug Peters,
Michael Bushnell, Florin Spanachi, David England, Charles Johnson,
David B.@: Serafini, R James Noble, David Duke, Mark S.@: Johnson, Gary
Campbell, Peter Dobcsany, Kent Williams, Wilson Ho, Karl Kleinpaste,
Len Tower, Paul Regenhardt, Joe Pallas, Peter Kropf, Mark Bush, Per
Bothner, Kevin Rigotti, Lance Norskog, Pascal Meheut, Richard Goerwitz,
Horst Duchene, Olivier Blanc, Jeff Baird, P.@: Lecoanet.

Brad Diller wishes to offer his great appreciation and thanks to Steve
Byrne, Peter Deutsch, Eben Moglen and Richard Stallman for their
supernumerary efforts in finally making the release of his browser a
reality.

Other contributors for more recent versions include: Pahi Andras,
Mikael Aronsson, Nicolas Burrus, Ulf Dambacher, Peter Da Silva,
Federico Di Gregorio, Mark Elbrecht, Stephen Houben, Dwight Hughes,
Thorsten Klein, Peter William Lount, Hiroshi Nanosecond,
Christopher Painter-Wakefield, Hideoki Saito, Marko Schuetz,
Alexander Shinn, Montgomery A.@: Tidwell, Zoltan Varga.

And I also thank the two people who followed me patiently through the
revival of @gst{}, following me as I worked out the alphas that
eventually led to version 1.6: David V.@: Duccini, who helped a lot
with his enthusiasm in the earliest phases of testing, as I grew
more comfortable with Steve's code, and Andreas Klimas, who made
available to me his Smalltalk knowledge but, above all, his C and
Unix expertise.

And of course, last but definitely not the least, Steve Byrne, for his
feedback in discussing issues related to @gst{}'s implementation,
for having put me in contact with all the people asking him about
@gst{}, and for sharing with me the source code for his own
improvements to version 1.1.5 of @gst{}.  Steve, I sincerely hope
you like what I do to your program.


@iftex
@contents
@end iftex

@c should put in index support somewhen...

@bye

Local Variables:
compile-command: "makeinfo -fc 72 gst.txi"
fill-column: 72
End:
