CLC-INTERCAL 1.-94.-2

		"human beings are given free will in order to choose between
		 insanity on the one hand and lunacy on the other"
								Aldous Huxley

-- - --------
-2 - Contents
-- - --------

   -2 - Contents
   -1 - Foreword
    0 - Introduction to CLC-INTERCAL pre-pre-escape 1.-94.-2
    1 - What has changed since CLC-INTERCAL 0.05
    2 - How to install this escape
    3 - How to modify the compiler(s)
    4 - Important notes about the new INTERNET library
    5 - Licence


-- - --------
-1 - Foreword
-- - --------

A few years ago, I had, for several reasons, decided to completely GIVE UP
working on INTERCAL or, if you prefer, ABSTAIN FROM developing CLC-INTERCAL
any farther.

Of course, the flesh is weak and here I am at it again. It just so happens
that I am using the "compiler compiler compiler compiler" for a serious
project, so I am going to develop it further.


- - ------------ -- ------------ -------------- --------
0 - Introduction to CLC-INTERCAL pre-pre-escape 1.-94.-2
- - ------------ -- ------------ -------------- --------

It has been decided during the development of CLC-INTERCAL 0.06 that there
would be no further releases of CLC-INTERCAL. However, the compiler has
been left unattended on an FTP server, and appears to have escaped. For this
reason, we refer to this as an "escape" rather than a "release".

Additionally, development of CLC-INTERCAL version 0 has effectively stopped
before the escape of 0.06; a new versioning scheme has been introduced for
CLC-INTERCAL version 1. The main points to note are:

  * The term "version" has been replaced by "perversion" for correctness
  * The perversion number consists of a floating-point number with
    independent signs for the integer and fractional part. Negative
    fractions indicate pre-escapes (so 1.-94 means "94 pre-escapes to
    go before 1.00". Or you can just add the numbers together and get
    0.06, which is entirely a coincidence since 0.06 is not being
    developed)
  * The fractional part of a perversion number can be integer or floating
    point, with a similar meaning for the parts. The current pre-escape is
    1.-94.-2 which means "2 pre-pre-escapes to go before pre-escape 1.-94".

The fact that the compiler has escaped does not allow you to use without
reference to its licence: see the end of this document or the file COPYING.

Since this is a pre-pre-escape, there are parts which are unimplemented
or partially implemented. The file "MISSING" describes what is missing.
There might also parts which are implemented but are intended to be left
implemented: these will be removed from the final escapes.


- - ---- --- ------- ----- ------------ ----
1 - What has changed since CLC-INTERCAL 0.05
- - ---- --- ------- ----- ------------ ----

Just about everything. See the file "Changes" for a complete list, or see
the following executive summary.

The code is a complete rewrite. The "CREATE" statement which was documented
but not implemented has now been implemented (in a different form) and not
documented. This means that the compiler only needs to know about one
statement, "CREATE", and everything else can be created on-the-fly. This is
why the compiler itself and the various compatibility modules now include
INTERCAL source code consisting almost exclusively of "CREATE" statements.

This made it a lot easier to extend the language by specifying new features
in INTERCAL instead of Perl. Most statements have been modified to allow
creation of quantum bits. For example, it is possible to create 16 quantum
bits in one operation by assigning to a register while not assigning to it.
It goes without saying that the practice is not recommended if you don't
actually possess a quantum computer.

A new statement, "NEXT FROM", combines all the advantages of "COME FROM" and
"NEXT". It has been implemented essentially to provide a system call
interface, where the operating system is supposed to have a "NEXT FROM"
lurking in its darkest corner. See the last entry in the file "Changes"
for a complete description of the system call interface. Since this is
INTERCAL, the syscall interface is entirely system independent. System
dependent system calls are not supported.

All old programs should work unchanged (modulo the unimplemented parts, but
this is due to change as the perversion number progresses towards 1.00).
Programs intended for different compilers can also be compiled by selecting
a different compiler object (for example, "ick.iacc" provides compatibility
with the C-INTERCAL compiler "ick", and "1972.iacc" with the original
Princeton compiler). All these compiler object must be first compiled using
"iacc.iacc", the INTERCAL Astonishing Compiler Compiler, which is also used to
compile itself before compiling other compilers. A pre-compiled version is
provided in this escape otherwise you'll never get started.

The command-line compiler "oo, ick" and the inline module "Language::INTERCAL"
are not currently provided. They have been replaced by the compiler "sick"
and the module "Language::INTERCAL::Sick" respectively, which have a rather
different usage. A compatibility "oo, ick" and "Language::INTERCAL" is
intended to appear in a future pre-escape, and certainly before the escape.

The former "on-line reference", has been included in the distribution in
directory doc/html; it has been adapted for CLC-INTERCAL 1.-94; however
some new features might be still undocumented or underdocumented. Some of
the HTML documents are included as templates: the actual documentation
will be produced in blib/htmldoc


- - --- -- ------- ---- ------
2 - How to install this escape
- - --- -- ------- ---- ------

To unpack the distribution you need the following:

    * A command interpreter compatible with the Bourne shell
    * the "dd" program
    * optionally, gzip and/or bzip2

If necessary, uncompress the distribution:

    gzip -d CLC-INTERCAL-1.-94.-2.ddsh.gz

or:

    bzip2 -d CLC-INTERCAL-1.-94.-2.ddsh.bz2

Unpack the distribution:

    sh CLC-INTERCAL-1.-94.-2.ddsh

Create the Makefile:

    cd CLC-INTERCAL-1.-94.-2
    perl Makefile.PL

Build the compilers:

    make

See if everything works:

    make test

And install:

    make install

It is possible that, by the time you read this, we have provided two
alternative versions of some modules: pure Perl and Perl-with-C. The latter
is likely to be better in some way (speed, size), otherwise we would not
provide it. If Makefile.PL finds that alternative versions are available,
it will ask which one you want to install. In general, the pure Perl versions
will work as long as your Perl installation works; the Perl-with-C should
work but might break because your C compiler is not the same as mine, or
simply because it's C and it's more self-obfuscating than INTERCAL. If it
does not work, install the pure Perl version. If that does not work either,
you have found an unimplemented feature. Congratulations.

The "make" and "make test" will take some time: "make" will run IACC (the
INTERCAL Astonishing Compiler Compiler) to build itself and all the other
compilers, and this is not quite a quick job. The "make test" will test
all parts of the compiler, including the Virual Machine, the Quantum
Emulator and the Just-Too-Late compiler. Have a coffee break, or read the
source code and try to figure out how it works. If you can figure out how
it works, please tell me, because I cannot.


- - --- -- ------ --- -----------
3 - How to modify the compiler(s)
- - --- -- ------ --- -----------

The compiler and the compiler compiler are currently underdocumented
(which means that there is no documentation whatsoever). If you feel
the urge to modify the compiler itself, ignore the Perl runtime library
and edit the file "sick.iacc", which would have been installed somewhere
system dependent. If you have write permission to this system dependent
location and your command interpreter is compatible with the Bourne Shell,
you can locate the file and edit it by simply typing (all in one line, we
show it in separate lines for readability):

    sh -c '${EDITOR-vi} `sick -vo/dev/null sick.iacc 2>&1 |
    head -1 | sed -e "s/\.\.\. \[.*$//"`'

If you would rather not type the above, or you have no write permission to
the appropriate place (or if you have an inferior command interpreter), try:

    sick -vo/dev/null sick.iacc

The complete path will appear in the first line of the output, so you can copy
or edit it. You do want to copy it in case you break it:

    sh -c 'cp `sick -vo/dev/null sick.iacc 2>&1 |\
    head -1 | sed -e "s/\.\.\. \[.*$//"` iacc.io.SAFE'

When you have edited the file, rebuild the compiler object with:

    sick sick.iacc

If you have edited a copy, type that from the directory where you left the
edited copy, or "sick" won't find it (but see the "-I" command line option)

A similar consideration applies to rebuilding IACC (the INTERCAL Astonishing
Compiler Compiler). However, in this case you need to make a copy of "iacc.io"
as well as "iacc.iacc":

    sh -c 'cp `sick -vo/dev/null iacc.iacc 2>&1 |\
    head -1 | sed -e "s/\.\.\. \[.*$//"` iacc.io.SAFE'
    sh -c 'cp `sick -vo/dev/null iacc.io 2>&1 |\
    head -1 | sed -e "s/\.\.\. \[.*$//"` iacc.io.SAFE'
    sh -c '${EDITOR-vi} `sick -vo/dev/null iacc.iacc 2>&1 |\
    head -1 | sed -e "s/\.\.\. \[.*$//"`'
    sick iacc.iacc

If you break "iacc.io" you won't be able to recompile "iacc" unless you
re-install CLC-INTERCAL or use the copy you just made.


- - --------- ----- ----- --- --- -------- -------
4 - Important notes about the new INTERNET library
- - --------- ----- ----- --- --- -------- -------

A new INTERNET library is now available as an extension to the "sick"
compiler (it may work with other compilers, but this is not very likely
for now). See directory doc/INTERNET for details.

When this extension is loaded, the program will automatically start a
theft server if one isn't found already running on the local computer.
As there isn't yet an official port assignment for this, the port is
stored in the file system.sickrc, and should be changed when an official
assignment is available. Look for the line:

    I CAN UNDERSTAND "..INTERNET.PORT" AS "64928"

and change the number as appropriate. You may also want to run your
INTERNET applications using a nonstandard port, but doing so will make
locally running programs incompatible with programs running elsewhere,
so stealing from remote systems will not succeed - unless of course one
has agreed on a port number with the remote system's admin.

Some of the forms of the CASE statement, and the STEAL/SMUGGLE without an
IP address, require knowledge of the IP address and netmask of local LANs.
In some cases, it may be possible to obtain these automatically, however this
is not possible in some systems. If the information is not available, no
broadcasts are possible. To work around this problem it is possible to specify
the list of interface in sickrc (user or system) with options like:

    I CAN UNDERSTAND "..INTERNET.DEVICE.eth0" AS "192.168.1.2" WITH 24
    I CAN UNDERSTAND "..INTERNET.DEVICE.eth1" AS "10.3.6.9" WITH 8

Note that the option specifies the IP address and netmask of each interface;
in this case, 192.168.1.2/24 and 10.3.6.9/8; the device name is ignored at
present, but it may be a good idea to leave it the same as the name known to
the kernel. Also note that you must install Net::Netmask to be able to use
the list of devices from sickrc.

An unusual feature of the INTERNET is that one can steal filehandles and they
will continue working. For example, if an INTERCAL program with the INTERNET
extension runs on computer A and has standard write redirected from a file,
then another program on computer B can steal that standard write filehandle
and will be able to write in from that file, even if the file is not on a
networked filesystem (because it's been stolen, however, the program which
opened the file can no longer use it - smuggling, on the other hand will allow
to share a file between computers). This feature has been used to create a
network-wide clipboard in which a server (a simple INTERCAL program) just
opens a file and then does nothing; clients then SMUGGLE the filehandle
and store the clipboard contents on it - automagically sharing it over the
network. Moreover, the server can be found using broadcasts, so there is
never any need for the user to know where it is running.


- - -------
5 - Licence
- - -------

Copyright (c) 2006-2008 Claudio Calvelli <intercal@sdf.lonestar.org>
(Please include the word INTERLEAVING in the subject when emailing that
address, or the email may be ignored)

In addition to the above, permission is hereby granted to use, misuse,
modify, distribute, break, fix again, etcetera CLC-INTERCAL-1.-94.-2
provided that the following conditions are met:

    1. Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
    3. Neither the name of the Author nor the names of its contributors
       may be used to endorse or promote products derived from this software
       without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    SUCH DAMAGE.