0001651: incorrect and incomplete camlp4 documentation

View Issue Details [ Jump to Notes ]

[ Issue History ] [ Print ]

Project

Category

View Status

Date Submitted

Last Update

0001651

OCaml

OCaml documentation

public

2003-04-22 18:26

2012-09-11 09:18

Reporter

administrator

Assigned To

Priority

normal

Severity

minor

Reproducibility

always

Status

resolved

Resolution

suspended

Platform

OS Version

Product Version

Target Version

Fixed in Version

Summary

0001651: incorrect and incomplete camlp4 documentation

Description

Hi,

Appendix A (quotations) of the camlp4 reference manual is
incorrect or incomplete in the following cases:

1. there are no quotations documented for the two types
   MLast.row_field and MLast.with_constr. Further there is no
   location function "loc_of_..." defined for these two types.

2. for the following constructors from MLast there is no
   quotation or the given quotation contains errors:

ExVrn (_, _)
ExSnd (_, _, _)
ExOvr (_, _)
ExOlb (_, _, _)
ExNew (_, _)
ExLmd (_, _, _, _)
PaVrn (_, _)
PaTyp (_, _)
PaRec (_, _)
PaOlb (_, _, _, _)
PaLab (_, _, _)
PaFlo (_, _)
PaArr (_, _)
TyObj (_, _, true)
SgInc (_, _)
SgDir (_, _, _)
SgClt (_, _)
SgCls (_, _)
StInc (_, _)
StDir (_, _, _)
StClt (_, _)
StCls (_, _)
MeTyc (_, _, _)
CtSig (_, _, _)
CrMth (_, _, _, _, _)

3. the following quotations do not work as given, they produce
   the following error messages:

<:patt< { $ppl$ } >>: record.
Parse error: '=' expected after [patt_label_ident] (in [label_patt])

<:module_expr< ( $me$ : $mt$ ) ] >>: module type constraint.
Parse error: end of input expected after [module expression] (in [module
  expression])

<:class_type< object $s$ $list:csil$ end >>: class object type
Parse error: ';' expected after [class signature item] (in [class
type])

<:class_str_item< method $s$ : $t$ >>: method.
Parse error: '=' expected after [type] (in [class structure item])

<:class_str_item< method private $s$ : $t$ >>: private method.
Parse error: '=' expected after [type] (in [class structure item])

4. the quotation

<:class_sig_item< value $mut:m$ $s$ = $t$ >>: value.

   should be

<:class_sig_item< value $mut:m$ $s$ : $t$ >> ....

For the compilation of these errors I used the attached ocaml
file. It would be nice if the next camlp4 release would contain
an example file with a complete pattern match over the syntax
tree written entirely with quotations.

Bye,

Hendrik

----------------

(* A.2 Quotation expr *)

let f = function
  | <:expr< $e1$ . $e2$ >> -> ()
  | <:expr< $anti:e$ >> -> ()
  | <:expr< $e1$ $e2$ >> -> ()
  | <:expr< $e1$ .( $e2$ ) >> -> ()
  | <:expr< [| $list:el$ |] >> -> ()
  | <:expr< $e1$ := $e2$ >> -> ()
  | <:expr< $chr:c$ >> -> ()

(* in new version *)
  | <:expr< ($e$ :> $t$) >> -> ()
  | <:expr< ($e$ : $t1$ :> $t2$) >> -> ()

  | <:expr< $flo:s$ >> -> ()
  | <:expr< for $s$ = $e1$ $to:b$ $e2$ do { $list:el$ } >> -> ()
  | <:expr< fun [ $list:pwel$ ] >> -> ()
  | <:expr< if $e1$ then $e2$ else $e3$ >> -> ()
  | <:expr< $int:s$ >> -> ()

(* in new version *)
  | <:expr< ~ $i$ : $e$ >> -> ()
  | <:expr< lazy $e$ >> -> ()

  | <:expr< let $rec:b$ $list:pel$ in $e$ >> -> ()
  | <:expr< $lid:s$ >> -> ()
  | <:expr< match $e$ with [ $list:pwel$ ] >> -> ()
  | <:expr< { $list:eel$ } >> -> ()
  | <:expr< do { $list:el$ } >> -> ()
  | <:expr< $e1$ .[ $e2$ ] >> -> ()
  | <:expr< $str:s$ >> -> ()
  | <:expr< try $e$ with [ $list:pwel$ ] >> -> ()
  | <:expr< ( $list:el$ ) >> -> ()
  | <:expr< ( $e$ : $t$ ) >> -> ()
  | <:expr< $uid:s$ >> -> ()
  | <:expr< while $e$ do { $list:el$ } >> -> ()

(* missing
(ExVrn (_, _)|ExSnd (_, _, _)|ExOvr (_, _)|ExOlb (_, _, _)|ExNew (_, _)|
ExLmd (_, _, _, _))
*)

(* A.3 Quotation patt *)

let f = function
  | <:patt< $p1$ . $p2$ >> -> ()
  | <:patt< $anti:e$ >> -> ()
  | <:patt< ( $p1$ as $p2$ ) >> -> ()
  | <:patt< _ >> -> ()
  | <:patt< $p1$ $p2$ >> -> ()
  | <:patt< $chr:c$ >> -> ()
  | <:patt< $int:s$ >> -> ()
  | <:patt< $lid:i$ >> -> ()
  | <:patt< $p1$ | $p2$ >> -> ()
  | <:patt< $p1$ .. $p2$ >> -> ()

  (* | <:patt< { $ppl$ } >> -> () *)
(* error message
Parse error: '=' expected after [patt_label_ident] (in [label_patt])
*)

  | <:patt< $str:s$ >> -> ()
  | <:patt< ( $list:pl$ ) >> -> ()
  | <:patt< ( $p$ : $t$ ) >> -> ()
  | <:patt< $uid:s$ >> -> ()

(*missing
(PaVrn (_, _)|PaTyp (_, _)|PaRec (_, _)|PaOlb (_, _, _, _)|PaLab (_, _, _)|
PaFlo (_, _)|PaArr (_, _))
*)

(* A.5 Quotation ctyp *)

let f = function
  | <:ctyp< $t1$ . $t2$ >> -> ()
  | <:ctyp< $t1$ as $t2$ >> -> ()
  | <:ctyp< _ >> -> ()
  | <:ctyp< $t1$ $t2$ >> -> ()
  | <:ctyp< $t1$ -> $t2$ >> -> ()
  | <:ctyp< # $list:sl$ >> -> ()
  | <:ctyp< ~ $s$ : $t$ >> -> ()
  | <:ctyp< $lid:s$ >> -> ()
  | <:ctyp< $t1$ == $t2$ >> -> ()
  | <:ctyp< < $list:fl$ > >> -> ()
  | <:ctyp< ? $s$ : $t$ >> -> ()

(* was
  | <:ctyp< ! $list:sl$ : $t$ >> -> ()
but fixed in new docs *)

  | <:ctyp< ! $list:sl$ . $t$ >> -> ()

  | <:ctyp< '$s$ >> -> ()
  | <:ctyp< { $list:sbtl$ } >> -> ()
  | <:ctyp< [ $list:stll$ ] >> -> ()
  | <:ctyp< ( $list:tl$ ) >> -> ()
  | <:ctyp< $uid:s$ >> -> ()
  | <:ctyp< [| $list:rfl$ |] >> -> ()
(*missing
TyObj (_, _, true)
*)

(* A.6 Quotation sig_item *)

let f = function
  | <:sig_item< declare $list:sil$ end >> -> ()
  | <:sig_item< exception $s$ of $list:tl$ >> -> ()
  | <:sig_item< external $s$ : $t$ = $list:sl$ >> -> ()
  | <:sig_item< module $s$ : $mt$ >> -> ()
  | <:sig_item< module type $s$ = $mt$ >> -> ()
  | <:sig_item< open $sl$ >> -> ()
  | <:sig_item< type $list:sslt$ >> -> ()
  | <:sig_item< value $s$ : $t$ >> -> ()
(* missing
(SgInc (_, _)|SgDir (_, _, _)|SgClt (_, _)|SgCls (_, _))
*)

(* A.7 Quotation str_item *)

let f = function
  | <:str_item< declare $list:stl$ end >> -> ()
  | <:str_item< exception $s$ of $list:tl$ >> -> ()
  | <:str_item< $exp:e$ >> -> ()
  | <:str_item< external $s$ : $t$ = $list:sl$ >> -> ()
  | <:str_item< module $s$ = $me$ >> -> ()
  | <:str_item< module type $s$ = $mt$ >> -> ()
  | <:str_item< open $sl$ >> -> ()
  | <:str_item< type $list:sslt$ >> -> ()
  | <:str_item< value $rec:b$ $list:pel$ >> -> ()
(*missing
(StInc (_, _)|StDir (_, _, _)|StClt (_, _)|StCls (_, _))
*)

(* A.8 Quotation module_type *)

let f = function
  | <:module_type< $mt1$ . $mt2$ >> -> ()
  | <:module_type< $mt1$ $mt2$ >> -> ()
  | <:module_type< functor ( $s$ : $mt1$ ) -> $mt2$ >> -> ()
  | <:module_type< $lid:i$ >> -> ()

(* in new version *)
  | <:module_type< '$i$ >> -> ()

  | <:module_type< sig $list:sil$ end >> -> ()
  | <:module_type< $uid:i$ >> -> ()
  | <:module_type< $mt$ with $list:wcl$ >> -> ()

(* A.9 Quotation module_expr *)

let f = function
  | <:module_expr< $me1$ . $me2$ >> -> ()
  | <:module_expr< $me1$ $me2$ >> -> ()
  | <:module_expr< functor ( $s$ : $mt$ ) -> $me$ >> -> ()
  | <:module_expr< struct $list:stl$ end >> -> ()

(*
  | <:module_expr< ( $me$ : $mt$ ) ] >> -> ()

error :
Parse error: end of input expected after [module expression] (in [module
  expression])
*)

  | <:module_expr< $uid:i$ >> -> ()
(*missing
MeTyc (_, _, _)
*)

(* A.10 Quotation class_expr *)

let f = function
  | <:class_expr< $ce$ $e$ >> -> ()
  | <:class_expr< $list:sl$ [ $list:tl$ ] >> -> ()
  | <:class_expr< fun $p$ -> $ce$ >> -> ()
  | <:class_expr< let $rec:b$ $list:lb$ in $ce$ >> -> ()
  | <:class_expr< object $p$ $list:csil$ end >> -> ()
  | <:class_expr< ( $ce$ : $ct$ ) >> -> ()

(* A.11 Quotation class_type *)

let f = function
  | <:class_type< $list:sl$ [ $list:tl$ ] >> -> ()
  | <:class_type< [ $t$ ] -> $ct$ >> -> ()

(*
  | <:class_type< object $s$ $list:csil$ end >> -> ()
error:
Parse error: ';' expected after [class signature item] (in [class type])
*)
(* missing
CtSig (_, _, _)
*)

(* A.12 Quotation class_sig_item *)

let f = function
  | <:class_sig_item< type $t1$ = $t2$ >> -> ()
  | <:class_sig_item< declare $list:csil$ end >> -> ()
  | <:class_sig_item< inherit $ct$ >> -> ()
  | <:class_sig_item< method $s$ : $t$ >> -> ()
  | <:class_sig_item< method private $s$ : $t$ >> -> ()

(*
  | <:class_sig_item< value $mut:m$ $s$ = $t$ >> -> ()
error
Parse error: ':' expected after [label] (in [class signature item])

should be
*)
  | <:class_sig_item< value $mut:m$ $s$ : $t$ >> -> ()

  | <:class_sig_item< method virtual $s$ : $t$ >> -> ()
  | <:class_sig_item< method virtual private $s$ : $t$ >> -> ()

(* A.13 Quotation class_str_item *)

let f = function
  | <:class_str_item< declare $list:csil$ end >> -> ()
  | <:class_str_item< type $t1$ = $t2$ >> -> ()
  | <:class_str_item< inherit $ct$ >> -> ()
  | <:class_str_item< initializer $e$ >> -> ()

(*
  | <:class_str_item< method $s$ : $t$ >> -> ()
error
Parse error: '=' expected after [type] (in [class structure item])
*)

(*
  | <:class_str_item< method private $s$ : $t$ >> -> ()
error
Parse error: '=' expected after [type] (in [class structure item])
*)

  | <:class_str_item< method virtual $s$ : $t$ >> -> ()
  | <:class_str_item< method virtual private $s$ : $t$ >> -> ()
  | <:class_str_item< value $mut:m$ $s$ = $t$ >> -> ()
(*missing
CrMth (_, _, _, _, _)
*)

(* missing types
and row_field =

and with_constr =
*)

(*** Local Variables: ***)
(*** version-control: t ***)
(*** kept-new-versions: 5 ***)
(*** compile-command: "ocamlc -pp \"camlp4o q_MLast.cmo\" -c -I \"`camlp4 -where`\" quotation_test.ml" ***)
(*** delete-old-versions: t ***)
(*** End: ***)
----------------
----------------

Notes
(0002997) administrator (administrator) 2003-07-16 17:42	assigned to MM

(0007775) Hendrik Tews (reporter) 2012-07-18 09:46	This report applies to camlp4 of ocaml 3.09 and earlier. For the current camlp4 quotations and the AST are documented at http://brion.inria.fr/gallium/index.php/Abstract_Syntax_Tree [^] and can be fixed directly there. As the original reporter I would say this bug can be closed. Hendrik

(0008053) doligez (manager) 2012-09-11 09:18	Indeed, the camlp4 referenced here has become camlp5. Maybe the camlp5 maintainer would like to have a look at this PR, but this is not about the core OCaml distribution anymore.

Issue History
Date Modified	Username	Field	Change
2005-11-18 10:14	administrator	New Issue
2005-12-15 15:45	doligez	Category	OCaml general => OCaml documentation
2005-12-15 15:45	doligez	Description Updated
2012-07-11 17:38	doligez	Target Version	=> 4.01.0+dev
2012-07-18 09:46	Hendrik Tews	Note Added: 0007775
2012-07-31 13:37	doligez	Target Version	4.01.0+dev => 4.00.1+dev
2012-09-11 09:18	doligez	Note Added: 0008053
2012-09-11 09:18	doligez	Status	acknowledged => resolved
2012-09-11 09:18	doligez	Resolution	open => suspended
2012-09-11 09:18	doligez	Target Version	4.00.1+dev =>

Relationships