Really Useful CD 1/ReallyUsefulCD1.iso/extras/utilities/icon/readmearc

Text File | 1990-08-07 | 10.5 KB | 283 lines

                   Icon version 8 for the Archimedes
                   ---------------------------------

There is very little here to say regarding this implementation of Icon
for the Archimedes. It conforms fully to the standard Icon version 8
documentation, ie. "The Icon Programming Language (2nd edition)" by R.E.
and M.T. Griswold.

This version of Icon supports

    * Large Integers
    * Co-expressions
    * Keyboard functions (getch, getche, kbhit)
    * The system() function

(which are the most often omitted features). Note that the
implementation of co-expressions is slightly "untidy" at present, in
that whenever a co-expression is created, a stack is allocated (16K).
This stack is NEVER FREED (due to problems interfacing the Icon model
of C stack handling and the Arm procedure call standard). I hope to fix
this, in the long term, but for now be aware that programs using lots
of co-expressions will probably grow short of memory.

For the Archimedes, &features includes "Acorn Archimedes".


Environment variables
---------------------

Icon uses a number of environment variables to set run-time values such
as stack sizes or whether tracing is switched on. These are usually
given names such as

    MSTKSIZE        Main stack size
    TRACE            Tracing on?

Following the usual Archimedes conventions, these variables have all
been renamed, by prefixing the name with "Icon$". So, the above
variables are called

    Icon$MStkSize        Main stack size
    Icon$Trace        Tracing on?

and similarly for all "start-up" environment variables.


File names
----------

As usual, the convention of using file name "extensions" causes
difficulties. Icon uses four file extensions, namely

    .icn            Icon source code
    .u1            Intermediate code (procedures)
    .u2            Intermediate code (globals)
    .ux            Linker diagnostics (-L flag)

Under RISC OS, the usual transformation is performed, ie. rather than
looking for "file.icn", Icont looks for "Icn.file" - ie, file "file" in
directory "Icn".

Similarly to Acorn C, Icont expects the U1 and U2 directories to be set
up in advance (and the Ux directory if -L is used). Also, note that an
"extension" of .icn can be omitted from the file name in Icont, so that
to compile and link "Icn.Hello", all you need is

    Icont hello

The convention of using an "extension of .u to mean .u1 and .u2 is
retained. So, to link U1.hello, U2.hello, U1.options and U2.options,
giving an output file called HelloW, all that is needed is

    Icont -o HelloW U.hello U.options

Note that, UNLIKE Acorn C, filenames cannot be written in the
"extension" form, so that

    Icont -o HelloW hello.u options.u

is WRONG.

Also, note that if compiling stdin (via Icont -, or simply Icont with no
parameters) the output files are U1.Stdin, U2.Stdin and Stdin (the
I-code executable).


Standard search path
--------------------

When looking for files named in "link" statements, Icon looks in places
specified in the IPATH environment variable (called Icon$Ipath on the
Archimedes). The default for this variable, when not set, is

    "Icon: Lib:Icon."

Icon therefore first looks along the RISC OS path specified by the OS
variable Icon$Path, and if the file is not found, it then looks for a
directory "Icon" on Lib$Path.

To alter the search path, two methods can be used. First, the value of
Icon$Ipath can be altered. In this case, the Icon form of path,
consisting of a space-separated list of directory prefixes, is used. An
alternative method is to leave the default IPATH, but set up a suitable
Icon$Path variable.

The second method is recommended, as it conforms better to the standard
conventions under RISC OS. (A third possibility, to install a directory
Icon somewhere on Lib$Path, is possible. This is a good idea for people
like me, who keep all their language run-time stuff somewhere on
Lib$Path).


File types
----------

Icont will timestamp the executable I-code file, giving it file type
"Icon" if such a file type exists. Ie, if <File$Type_xxx> is "Icon", for
any xxx, then the I-code file is given file type xxx. This allows users
to set up in their !Boot file

    Set File$Type_xxx    Icon
    Set Alias$@RunType_xxx    Iconx %0 %*1

to make icon I-code files directly executable. (The %*1 allows for
parameters being passed to the Icon program).


Pipes
-----

Archimedes Icon DOES support the opening of files as pipes (the "p"
mode). This is done using temporary files. The input or output of the
command is stored in a temporary file in one of the following places
(tried in this order)

    <Tmp$Dir>    if this OS variable is set, and the directory exists
    &.Tmp        if the directory exists
    @        ie, the current directory

The temporary filenames will not clash with existing files (hopefully!),
and the temporary files will be deleted when they are finished with.

The IO redirection is done using the C convention ("command <in >out")
for all but built-in commands (there is a hard-coded list of these). The
built-in commands use OS redirection ("command { < in > out }") and the
output file is post-processed to convert line separators "\r\n" into
just "\n", which is what Icon expects.

If you want to run a program which is NOT a built-in, but which does not
support the C convention (eg, pascal or fortran programs), simply add a
'%' to the front of the command (ie "%command arg arg..."). OS
redirection will then be used, and the '%' removed. If you want to run a
command starting with a '%', and STILL use C redirection, "*%command"
should work (OS_CLI ignores leading asterisks).

Also, if you have the PD program "m4", which preprocesses files (giving
C-like #define and #include facilities, plus much more, but with a
different syntax), then you can use the "-m" flag to Icont, to
preprocess your Icon code using m4.


System Dependent Functions
--------------------------

Archimedes Icon includes a number of low-level RISC OS interface
functions, in a similar manner to MS-DOS ports of Icon. The relevant
functions are

1. Swi(swi,r)

   Swi(swi,r) is a general interface to the OS SWI functions. The inputs
   are a SWI number (or name), and a list of registers [r0, ..., r9].
   The "swi" parameter is treated as a SWI number if it is an integer,
   and a SWI name if it is a string. An invalid name results in run-time
   error 205 (value out of range), and any type other than integer or
   string results in run-time error 123 (invalid type).

   The register list, r, can contain between 0 and 10 values (an omitted
   parameter is treated as []), each being assigned to a register
   (r0, ..., r9). If a value is an integer, it is assigned direct. If it
   is a string, its address is assigned (strings are null-terminated).
   Any other type gives run-time error 123 (invalid type).

   If the SWI call fails (ie, an OS error occurs), Swi(swi,r) fails (in
   the Icon sense). Otherwise, the return value is a 10-element list,
   holding the integer values of r0, ..., r9. To get at strings which
   are returned as pointers, see Peek() below.

   Note that Swi() can be a great way of corrupting Icon's internal data
   structures, if used carelessly. In particular, passing the address of
   an Icon string to a SWI which expects to be able to overwrite the
   string can be fatal. For the brave, note that the Icon string can be
   assumed to be as many bytes long as its length (*str). The length on
   return will be unchanged - Icon strings CAN contain nulls, so if the
   OS inserts a null-terminated string into an Icon string, you must
   arrange to extract the appropriate substring manually (eg, using
   tab(upto('\0')), or something similar).

   To get a safe buffer, use GetSpace(), below.

2. GetSpace(i)

   GetSpace(i) returns an integer, which is the address of a block of
   storage, i bytes long. The storage is claimed using malloc(), and is
   completely outside the control of Icon. The only way to read from or
   write to this area, is using Peek() and Poke(), below.

   GetSpace() fails (in the Icon sense) if the memory is unavailable
   (ie, malloc() returns NULL). This also happens if i is 0.

3. FreeSpace(a)

   FreeSpace(a) frees the block of storage at address a (which must be
   an integer), using free(). This should be used to free storage
   allocated using GetSpace(). No check is made to make sure that a is
   the address of an area claimed by GetSpace(). If it is not, you will
   almost surely crash Icon.

4. Peek(a,i)

   Peek(a,i) returns an Icon string, consisting of the i bytes at
   address a. Peek() does not move any data about. It simply builds an
   Icon string qualifier, pointing to the data. Hence string returned by
   Peek() is not modifiable.

5. Poke(a,s)

   Poke(a,s) copies the Icon string s to address a. The string is copied
   directly, byte by byte, with no conversion. No terminating null byte
   is added. This is the only way of assigning data into a block of
   storage allocated using GetSpace().

To go with these functions, &features includes "Archimedes extensions".


Port information
----------------

This port was produced by

Paul Moore

10, Mulberry Rise,
Firdale Park,
Northwich,
Cheshire
CW8 4UQ

E-Mail: [e-mail]
    [e-mail]

I am interested in hearing about any bugs in the port, or any
suggestions for improvements (although I will not put in any Archimedes
specific alterations to the Icon language itself - I intend to register
this port with the Icon project, so that any upgrades will be
automatically available).

This distribution may not include full source (depending upon where you
got it from). If not, I can supply source. Please contact me (including
a couple of FORMATTED disks), and I'll send a copy. Note: the sources
are held as Spark archives, so you'll need to have Spark or the PD
un-archiver SparkPlug to get at them.

I also have the rest of the Icon distribution (the Icon program library,
Idol - an object-oriented front end for Icon, and a few other bits).
Again, contact me, including disks, if you want them.

IF YOU ARE REQUESTING ANY OF THE ABOVE, please let me know if you have
the latest version of Spark (2.00). I hold my backup copies of all of
these things as Spark archives using the latest compression format
(16-bit compress). This saves me a lot of disk space. However, it does
mean that I have to do a fair bit of work to prepare disks for earlier
versions of Spark (or for SparkPlug, which does not support 16-bit
compress at present). I would recommend people getting the Full version
of Spark anyway - it only costs 5 or 6 pounds, and the disk includes a
number of other PD goodies, as well. Avaliable from David Pilling (see
his ads in Risc User or Archive). End of adverts.


Have fun with Icon - it's an unusual, but nice, language.

Paul Moore