mlin/twt

======================================================================
                   "The Whitespace Thing" for OCaml
                                v0.93
             http://people.csail.mit.edu/mikelin/ocaml+twt/

                     by Mike Lin (mikelin@mit.edu)
======================================================================

-----------
DESCRIPTION
-----------

"The Whitespace Thing" for OCaml is a preprocessor (invoked as
ocaml+twt) that uses indentation to auto-parenthesize multiline
expressions, eliminating the need for much OCaml syntax clutter. The
syntactic style is thus akin to Python and Haskell in this regard.

The implementation strategy used in the present version of the
preprocessor has some limitations, but it works very well, and I use
it for all my new code.

-------------------------
INSTALLATION INSTRUCTIONS
-------------------------

To install, run

make install

This installs the executable in the same directory as ocamlc. To
override this, use:

make INSTALLDIR=/some/path install

-----
USAGE
-----

To use the preprocessor, either manually invoke it using `ocaml+twt
mycode.ml` and pipe the results to a file, or (more usefully) use the
preprocessor flag to ocamlc:

ocamlc -pp ocaml+twt mycode.ml

The preprocessor has several command line options that are
self-explanatory by looking at the usage printed by ocaml+twt without
parameters.

----------------------
LANGUAGE DOCUMENTATION
----------------------

See the quick reference in the doc subdirectory, and the examples
subdirectory. Also the web site for the latest.

-------------------
AN EXAMPLE MAKEFILE
-------------------

PP = ocaml+twt

all: prog1 prog2

prog1: mod1.cmi mod1.cmx prog1.cmx
	ocamlopt -o $@ mod1.cmx prog1.cmx
prog2: prog2.cmx
	ocamlopt -o $@ prog2.cmx

%.cmx : %.ml
	ocamlopt -c -pp $(PP) $<
%.cmi : %.mli
	ocamlopt -c -pp $(PP) $<

--

With ocamlbuild, you can have something like this in the _tags file in
your project directory:

<**/*.ml> or <**/*.mli>: ocaml, pp(ocaml+twt), debug

If you use OCamlMakefile, you can make the first line of your file
(*pp ocaml+twt *)
to have it preprocessed.

-----------------
PPCOMPOSE UTILITY
-----------------

Because the -pp flag to ocamlc is somewhat limited, I included a
`ppcompose` utility that makes it simple to compose several
preprocessors. For example, I compose a list comprehension camlp4
syntax with ocaml+twt as follows:

ocamlc -pp "ppcompose 'camlp4o pa_compr.cmo' 'ocaml+twt -spaceonly'" source.ml

The last preprocessor specified on the command line is applied first
to the source code. This means you usually want ocaml+twt last.

---------------
VERSION HISTORY
---------------

02/01/12 version 0.93
- Handle OCaml 3.12's new 'include module type of...' in module
  signatures
- Allow pass-through of named operands in applications: f ~x
- Allow one-liner consequents for predicates:
    if pred1 then consq1
    else if pred2 then consq2
    else consq3
- Allow one-liner try and with bodies (similar):
    try expr1
    with Not_found -> expr2

08/02/10 version 0.92
- Accepts piped input
- Supports output to file (new option -o)
- ppcompose properly cleans up after itself, and makes less stderr noise
  by default (new option -v)
- New ocaml 3.12 keywords: val! method! inherit!
- bugfix: doesn't screw up with character literals '(' and ')'
- bugfix: allows passed-along optional arguments on their own lines

03/11/08 version 0.91
- Bug fixes to handling of escaped characters within string and
character literals

01/16/07 version 0.90
- Major backwards-incompatible change: elimination of "in" from let,
and elimination of requirement to indent let body.

12/10/06 version 0.86
- moved all parentheses inserted by the preprocessor from the
beginning of a line to the end of the previous line, making column
numbers in error messages usually match up, and improving the
readability of the postprocessed code. Thanks to Ingo Bormuth for the
idea and patch.

07/24/06 version 0.85
- ocamlc now shows the preprocessed filename in errors
- bugfix: your labelled or optional arguments on their own lines can
now have underscores in their names
- bugfix: you can now declare exceptions in module signatures
- bugfix: you can now have type constraints in object definitions
- bugfix: you can now have recursive object types (not thoroughly tested)
- bugfix: you can now have #load and other directives

02/19/06 version 0.81
- added the 'ppcompose' utility
- bugfix: you can now have a character literal on its own line
- bugfix: you can now have a labelled or optional argument on its own line
- bugfix: you can now have a polymorphic variant constructor on its own line

11/21/05 version 0.8
- initial release. works quite well, but the preprocessor's handling
of various pathological cases of syntax involving objects, module
signatures, and functors has not been rigorously tested.