
             QUOTATIONS in ORIGINAL SYNTAX for OCAML
============================================================================

This directory contains a quotation expander for Ocaml abstract
syntax trees in ORIGINAL SYNTAX

The quotation expander q_MLast.cmo in the Ocaml distribution
requires you to use the revised syntax. It looks like this:

  <:expr< do { flag.val := not flag.val; record.field := 2 } >>

With the module qo_MLast.cmo provided here you can relax and
write the more familiar

  <:expr< flag := not !flag; record.field <- 2 >>


In addition to the quotation expander this directory contains:

- an Ocaml ast pretty printer written with original quotations (i.e.
  the quotation system in qo_MLast provided here)
- the same written with revised quotations (i.e. the quotation
  system in q_MLast in the ocaml distribution)
- an Camlp4 parsing module for Ocaml written with original quotations
- the qocheck test frame



               WARNING! THIS IS WORK IN PROGRESS. 

      The package currently supports the core language, modules,
             module types, classes and class types. 

      HOWEVER, POLYMORPHIC VARIANTS, OPTIONAL OR LABELLED ARGUMENTS 
                      ARE NOT SUPPORTED (YET).


==========================
WEB SOURCES / DOWNLOAD
==========================

Visit http://wwwtcs.inf.tu-dresden.de/~tews/ocamlp4 for online
resources and the latest version.


==========================
PREREQUISITES
==========================

- ocaml version 3.08

- for the test frame qocheck: an ocaml source tree
  (if you only want to use the quotation expander qo_MLast then
  qocheck and the source tree are not necessary)

  The test frame qocheck depends on several modules of the Ocaml
  distribution. Unfortunately not all these modules are installed
  by default. Therefore, in order to compile the test frame, you
  need an ocaml source tree, which you HAVE NOT CLEANED YET.


==========================
INSTALLATION
==========================

1. ./configure

   If you have an ocaml source tree available specify it with
   --ocamlsrc <dir> to enable the test frame qocheck. 
   There are some other configure options, see configure -help.

2. make world

   Compiles everything.

3. make install

   Installs the quotation expander qo_MLast.cmo in the library
   directory. 

   Additionally you can do

   make install-pp            to install the pretty printers
   make install-qocheck       to install the test frame

4. Test (if you are suspicious)

4.1 Test the pretty printers (works without an ocaml source tree)

   make normal
   make diff

   Applies both pretty printers to test_input.ml and checks the
   output. There should be no differences.


4.2 Test the ocaml grammar (requires an ocaml source tree)

   make docheck

   parses test_input.ml with the ocaml grammar from the ocaml
   distribution and with grammar contained in here. The resulting
   abstract syntax trees are compared. There should be no
   differences. 


4.3. Stress test: You can run the previous test on a set of files.

   make test

   Applies qocheck to all files in test/mlfiles and sorts the
   file names into test/status.* according to the exit status of
   qocheck. The final lines should be 

      5 test/status.0            (meaning 5 files pass the test)
      1 test/status.20           (the original parser fails on 1 file)
      2 test/status.120		 (the revised parser fails on 2 files)
      3 test/status.125		 (the revised parser misses an quotation exp.)
     11 total

   The files that don't pass the test contain either quotations
   or syntax that has not been implemented in the original
   quotation system. See DOCUMENTATION below for the exit codes
   of qocheck.


   The next step is to apply the test to all ml files on your
   system. Do 

   locate .ml | grep \.ml$ > test/allmlfiles
   make fulltest

   If you see an exit status of 1, 2, 3, 200, 201 or 202 you found
   a bug. Please report it to me. The other possible exit values
   are only a bug if the input contains only core Ocaml syntax
   plus modules plus classes (but without variants, optional or
   labelled arguments, or quotations).



==========================
DOCUMENTATION
==========================


    Original quotations
    ===================

The quotation system is documented in the html files in
subdirectory doc or online at
http://wwwtcs.inf.tu-dresden.de/~tews/ocamlp4/qo_doc.html


    Pretty printer pp_qo.cma, pp_q.cma
    ==================================

These pretty printers emit an human readable english description
of the internal ast (in contrast to ocaml-ast-analyze, which
pretty prints the constructors from mLast.mli). The main
difference between pp_qo.cma and pp_q.cma is, that pp_qo.cma is
written with the original quotations provided here, while
pp_q.cma exploits the revised quotations from the ocaml
distribution. 

To use the pretty printers do

   camlp4o pp_qo.cma <your input file>

You might have to use "-I <location of pp_qo.cma" or an absolute
path for pp_qo.cma if it is not installed in the standard camlp4
search path.

The two pretty printers might print slightly different text for
the same input because of two reasons: Firstly, the original
quotations provided here are slightly more general, and secondly,
pp_qo.cma contains more code for testing the quotation expander.

Both pretty printers support the following options:

  -pp-version     output version and exit
  -fail           abort on unknown ast nodes
  -with-end-tags  add lines to terminate the description of nodes
  -test           enable additional testing code

-test is not fully implemented yet. Even without this option some
testing code is enabled.


    Parser paqo_o
    =============

The parser paqo_o.cmo is a (partially finished) drop-in
replacement for pa_o.cmo. Apart from some location fields both
parsers generate identical ast's. With the switch -compatible
Obj.set_field is used to change these location fields so that the
ast's are completely identical.


    qocheck
    =======

The test frame qocheck uses paqo_o.cmo and pa_o.cmo to parse one
file and compares the resulting abstract syntax trees. If they
are equal it checks if both pretty printers can print all nodes
in the ast. 

In case the the ast's differ, it can
- marshal both ast's into a file (option -dumpast), 
- save a pretty printed version (using pp_qo) of both ast's (option -pp)
- pretty print the portions that differ via the toplevel (option -dumpdiffs)

Unless -q is given qocheck outputs all its findings. The meaning
of the exit codes is as follows:

    0-3      both parsers work, ast's are identical
    0        pretty printers work (everything is fine)
    1        pretty printer pp_qo fails (should never happen)
    2        pretty printer pp_q fails (should never happen)
    3        both pretty printer fail (should never happen)
	     
    10-12    both parser work but the ast's differ
    10       the directive flag differs
    11       the number of str_item's in the ast's differs
    12       same number of items but some items differ
	     
An exit code 10-12 can happen if the file contains syntax that is
not yet supported in the original quotation system. Otherwise it
is a bug.
             
    20-26    parser pa_o works but pa_qo fails
    20       with a parsing error
    21       with exception Failure
    22       with assert
    23       with an exception with location info (should never happen)
    24       with an exception without location info (should never happen)
    25       with a quotation error (such as quotation not found)
    26       with a lexing error

The parser paqo_o can fail because of syntax that is not yet
supported or contains quotations. Otherwise it is a bug.

    120-126  parser pa_o fails (pa_qo is not applied in this case)
    120      with a parsing error
    121      with exception Failure
    122      with assert
    123      with an exception with location info (should never happen)
    124      with an exception without location info (should never happen)
    125      with a quotation error (such as quotation not found)
    126      with a lexing error

The parser pa_o can fail on invalid input (like parsing
asmcomp/amd64/selection.ml on a 32 bit system) or if the input
contains quotations. Otherwise it is a bug in pa_o.ml.

    >200     general errors
    200      unknown option
    201      dynlink exception (should never happen)
    202      error on one of the pipes used internally (should never happen)
    203      input file not found

On my system I find 8226 files with .ml suffix. Out of those 3801
pass the test, 4 fail with error 11, 109 fail with error 12, 3618
fail with error 20, 670 fail with error 120, 17 fail with error
125 and 7 fail with error 126.


==========================
ACKNOWLEDGEMENTS
==========================

This library contains significant portions of the Ocaml source
distribution. More precisely, the grammar in qo_MLast.ml and in
paqo_o.ml is taken almost literally from camlp4/etc/pa_o.ml, the
semantic actions in qo_MLast.ml are taken from
camlp4/meta/q_MLast.ml.


==========================
LICENCE
==========================

All files in this directory tree that contain a copyright notice
are distributed under the GNU library general public license,
version 2, see file LICENCE.


==========================
CONTACT
==========================

Please send bug reports, comments and questions to
tews@tcs.inf.tu-dresden.de.


-----------------------------------------------------------------
Hendrik Tews     Department of Theoretical Computer Science
                 Technische Universitaet Dresden, Germany

e-mail:          tews@tcs.inf.tu-dresden.de
www:             http://home.pages.de/~tews/
-----------------------------------------------------------------


*** Local Variables: ***
*** mode: text ***
*** version-control: t ***
*** kept-new-versions: 5 ***
*** delete-old-versions: t ***
*** End: ***
