Upgrading from OCaml 2.99 or OLabl to OCaml 3.00

[Jacques Garrigue <garrigue@kurims.kyoto-u.ac.jp>]

Objective Caml 3.00 has been released, and it is finally quite
different from 2.99.

Here is a summary of the changes, to help you upgrade.
(This is not in the OCaml Changelog, since 2.99 was only a beta)
There are also tools to help you, presented at the end of this note.

* Syntax

- Labels: to keep maximal compatibility with OCaml 2.0x, the syntax of
    labels in programs changed. Here is a conversion table (1):

        label:          ->      ~label:
        :label          ->      ~label
        (label:x : type)->      ~label:(x : type)
        (:label : type) ->      ~(label : type)
        ?label:         ->      ?label:         (unchanged)
        ?:label         ->      ?label
        ?(label:x = v)  ->      ?label:(x = v)
        ?(:label = v)   ->      ?(label = v)

     Notice that you cannot use keywords as labels anymore.

     Also, for OLabl programs, the syntax for default values changed:

        ?label:x [< v >] ->     ?label:(x = v)

     Semantics of optional parameters were changed between OLabl
     and OCaml 2.99. See the tutorial for the new semantics.

- Syntax of labels in types do not change (no extra ~).

- Variant types: in order to get more symmetry with sum types, an
  extra "of" was introduced before the parameter type.

        [`A int | `B bool]      ->      [`A of int | `B of bool]

* Labelling of libraries

The labellings of many functions in the libraries were changed, for
various reasons.

- To reduce the number of labelled functions in the standard
  libraries.
  Basically, labels were omitted wherever they do not provide useful
  information.
        E.g. List.nth : 'a list -> pos:int -> 'a
        became List.nth : 'a list -> int -> 'a
  In practice, most functions of two arguments were removed their
  labels.

- To avoid keyword labels, like fun:, to:, in:, end: ...

There is no exhaustive list of label changes, but here are some of
them:
        fun:    ->      f:
        pred:   ->      f:
        end:    ->      stop:
        to:     ->      (no label)
        key:,pos:,len:,size: -> often omitted

- Also there were changes in LablTk, to uniformize, and make easier
  use in classic mode.
  The standard parameter order is now
    * <labeled> <optional> <non-labeled> when there are optional arguments
    * <non-labeled> <labeled> when there are no optional arguments
  In the Canvas module, both the widget and the shape id are left
  unlabelled.


Helpful tools

* ocaml299to3
  This simple program does label syntax conversion automatically,
  following table (1). Also, it systematically converts fun: into f:.
  (Other label changes have to be done by hand.)
  It is clever enough to distinguish between terms and types (where no
  conversion should be done).  Since it only inserts "~"'s in your
  code, layout and comments are preserved.

  To convert all files in a directory, just type:

        % ocaml299to3 *.ml

  For all modified files, the orignal is kept as file.bak.

* Camlp4 3.00
  If you prefer the old syntax, using only ":", camlp4 can help you.
  In the upcoming release of camlp4, a grammar pa_olabl is provided
  that parses Ocaml 2.99 syntax.
  This does not mean that your programs will run unmodified, since many
  labels changed in 3.00, but you can keep the old style.

  Quoting Daniel de Raglaudre, here is how to use it:
    To compile with the 2.99 syntax, use
        ocamlc -pp "camlp4o pa_olabl.cmo"

    To switch the toplevel syntax to 2.99,
       ocaml -I `camlp4 -where`
       # #load "camlp4o.cma";;    (* Camlp4 parses *)
       # #load "pa_olabl.cmo";;   (* switch parser to 2.99 *)

    To create a toplevel parsing the 2.99 syntax,
        ocamlmktop -o olabl -I `camlp4 -where` gramlib.cma \
            camlp4_top.cma pa_olabl.cmo

This information, and eventual updates, wil be available at
        http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/compat.html

---------------------------------------------------------------------------
Jacques Garrigue      Kyoto University     garrigue at kurims.kyoto-u.ac.jp
		<A HREF=http://wwwfun.kurims.kyoto-u.ac.jp/~garrigue/>JG</A>