CLC-INTERCAL 1.-94.-7

		"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.-7
    1 - What has changed since CLC-INTERCAL 0.05
    2 - How to install this escape
    3 - How to modify the compiler(s)
    4 - How to compile and run the licence agreement
    5 - (Added Aug 2006): Alternative licence (BSD-like)


-- - --------
-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.-7
- - ------------ -- ------------ -------------- --------

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.-7 which means "7 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. To complicate matters, however, you have a choice
of two possible licences. Take your pick.

Licence 1 is a typically INTERCALish contraption. Rather than providing you
with a text file which you can look at and go "I cannot agree to THAT" or
"Yeah yeah, OK" as appropriate, the licence is provided as source code to
the CLC-INTERCAL compiler compiler compiler (or was that just the compiler
compiler? never mind). The idea is explained in full towards the end of this
README file, but you can always look at the file Common/Include/licence.iacc
to see what the program does. If reading IACC source is not your cup of
tea, you can just run it - it is, of course, executable.

Here is an executive summary of the licence agreement:

    * No charge can be made for distributing CLC-INTERCAL under any conditions.
      This condition does not apply to payment of copying/distribution expenses
      provided that no handling or other charge is added to such expenses.

    * The author cannot accept any liability whatsoever for any damage caused
      by the software, directly or indirectly. No warranty of any kind can be
      offered. Using the software in a way which causes any form of damage is
      expressely prohibited.

    * In addition, the author's details shall not be entered into any mailing
      list or public directory, without the author's written permission.

    * CLC-INTERCAL can be redistributed only under an identical licence
      agreement. Any modified or derived work must also be covered by the
      same identical agreement as the original work.

If these conditions seem a bit too restrictive, nobody is forcing you to use
CLC-INTERCAL. Also, you can always use Licence 2, described below.

Licence 2 is derived from the BSD licence. In other words, use, misuse
etcetera as you see fit, but remember that you deserve everything you get.

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.

Note that this escape differs little from 1.-94.-8. Mainly, some typos and
minor things have been fixed. The most important change is the addition of
Licence 2.


- - --- -- ------- ---- ------
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.-7.ddsh.gz

or:

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

Unpack the distribution:

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

Create the Makefile:

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

Build the compilers:

    make

Note: while compiling the licence agreement verifier (licence.iacc) you get
a large number of "Deep recursion" messages. This is normal and just indicates
that we are testing your Perl's ability to use a large stack. Or something.

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 - How to compile and run the licence agreement
- - --- -- ------- --- --- --- ------- ---------

The licence agreement for CLC-INTERCAL is distributed as a IACC (INTERCAL
Astonishing Compiler Compiler) source. It will be automatically compiled
into an INTERCAL object by the installation process; however, if it happens
to be necessary, you can always type:

    sick licence.iacc

Note: while compiling the licence agreement verifier (licence.iacc) you get
a large number of "Deep recursion" messages. This is normal and just indicates
that we are testing your Perl's ability to use a large stack. Or something.

Once you have compiled the licence agreement, you need to run it. Using your
favourite text editor, create a file (any filename will do: this example uses
the file name "DISAGREEMENT") containing your idea of a licence agreement.
Then run it:

    sick -plicence -lRun DISAGREEMENT

The CLC-INTERCAL system will print the single word "YES" if it accepts your
licence agreement. Any other output will indicate refusal. Please note that
you will get a splat 633 (Falling off the edge of the program) after the "YES":
this is normal and should be ignored.

An example licence agreement is provided in file "examples/software.licence"
which can be compiled with the above line, or, because of intrinsic magic,
with the abbreviated:

    sick -lRun examples/software.licence

A second example is provided to show the effect of compiling an invalid
licence agreement: see examples/invalid.licence or run:

    sick -lRun examples/invalid.licence



- -  ----- --- ----   ----------- -------  --------
5 - (Added Aug 2006): Alternative licence (BSD-like)
- -  ----- --- ----   ----------- -------  --------

Copyright (c) 2006 Claudio Calvelli <intercal@sdf.lonestar.org>

In addition to the above, permission is hereby granted to use, misuse,
modify, distribute, break, fix again, etcetera CLC-INTERCAL-1.-94.-7
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.

