Library

All modules defined in "gramlib.cma", but not including all Camlp5 modules used by the Camlp5 commands and kits.

  1. Ploc module
  2. Plexing module
  3. Plexer module
  4. Gramext module
  5. Grammar module
  6. Diff module
  7. Extfold module
  8. Extfun module
  9. Eprinter module
  10. Fstream module
  11. Pprintf module
  12. Pretty module
  13. Deprecated modules Stdpp and Token

Ploc module

Building and combining locations. This module also contains some pervasive types and functions.

type t = 'abstract;
Location type.

located exceptions

exception Exc of location and exn;
"Ploc.Exc loc e" is an encapsulation of the exception "e" with the input location "loc". To be used to specify a location for an error. This exception must not be raised by the OCaml function "raise", but rather by "Ploc.raise" (see below), to prevent the risk of several encapsulations of "Ploc.Exc".
value raise : t -> exn -> 'a;
"Ploc.raise loc e", if "e" is already the exception "Ploc.Exc", re-raise it (ignoring the new location "loc"), else raise the exception "Ploc.Exc loc e".

making locations

value make_loc : string -> int -> int -> (int * int) -> string -> t;
"Ploc.make_loc fname line_nb bol_pos (bp, ep) comm" creates a location starting at line number "line_nb", where the position of the beginning of the line is "bol_pos" and between the positions "bp" (included) and "ep" excluded. And "comm" is the comment before the location. The positions are in number of characters since the begin of the stream.
value make_unlined : (int * int) -> t;
"Ploc.make_unlined" is like "Ploc.make" except that the line number is not provided (to be used e.g. when the line number is unknown).
value dummy : t;
"Ploc.dummy" is a dummy location, used in situations when location has no meaning.

getting location info

value file_name : t -> string;
"Ploc.file_name loc" returns the file name of the location.
value first_pos : t -> int;
"Ploc.first_pos loc" returns the initial position of the location in number of characters since the beginning of the stream.
value last_pos : t -> int;
"Ploc.last_pos loc" returns the final position plus one of the location in number of characters since the beginning of the stream.
value line_nb : t -> int;
"Ploc.line_nb loc" returns the line number of the location or "-1" if the location does not contain a line number (i.e. built with "Ploc.make_unlined" above).
value bol_pos : t -> int;
"Ploc.bol_pos loc" returns the position of the beginning of the line of the location in number of characters since the beginning of the stream, or "0" if the location does not contain a line number (i.e. built the with "Ploc.make_unlined" above).
value comment : t -> string;
"Ploc.comment loc" returns the comment before the location.

combining locations

value encl : t -> t -> t;
"Ploc.encl loc1 loc2" returns the location starting at the smallest start and ending at the greatest end of the locations "loc1" and "loc2". In other words, it is the location enclosing "loc1" and "loc2".
value shift : int -> t -> t;
"Ploc.shift sh loc" returns the location "loc" shifted with "sh" characters. The line number is not recomputed.
value sub : t -> int -> int -> t;
"Ploc.sub loc sh len" is the location "loc" shifted with "sh" characters and with length "len". The previous ending position of the location is lost.
value after : t -> int -> int -> t;
"Ploc.after loc sh len" is the location just after loc (starting at the end position of "loc") shifted with "sh" characters and of length "len".
value with_comment : t -> string -> t;
Change the comment part of the given location

miscellaneous

value name : ref string;
"Ploc.name.val" is the name of the location variable used in grammars and in the predefined quotations for OCaml syntax trees. Default: ""loc"".
value get : string -> t -> (int * int * int * int * int);
"Ploc.get fname loc" returns in order: 1/ the line number of the begin of the location, 2/ its column, 3/ the line number of the first character not in the location, 4/ its column and 5/ the length of the location. The parameter "fname" is the file where the location occurs.
value from_file : string -> t -> (string * int * int * int);
"Ploc.from_file fname loc" reads the file "fname" up to the location "loc" and returns the real input file, the line number and the characters location in the line; the real input file can be different from "fname" because of possibility of line directives typically generated by /lib/cpp.

pervasives

type vala 'a =
  [ VaAnt of string
  | VaVal of 'a ]
;
Encloser of many abstract syntax tree notes types, in "strict" mode. This allow the system of antiquotations of abstract syntax tree quotations to work when using the quotation kit "q_ast.cmo".
value call_with : ref 'a -> 'a -> ('b -> 'c) -> 'b -> 'c;
"Ploc.call_with r v f a" sets the reference "r" to the value "v", then calls "f a", and resets "r" to its initial value. If "f a" raises an exception, its initial value is also reset and the exception is reraised. The result is the result of "f a".

Plexing module

Lexing for Camlp5 grammars.

This module defines the Camlp5 lexer type to be used in extensible grammars (see module "Grammar"). It also provides some useful functions to create lexers.

type pattern = (string * string);
Type for values used by the generated code of the EXTEND statement to represent terminals in entry rules.
  • The first string is the constructor name (must start with an uppercase character). When empty, the second string should be a keyword.
  • The second string is the constructor parameter. Empty if it has no parameter (corresponding to the 'wildcard' pattern).
  • The way tokens patterns are interpreted to parse tokens is done by the lexer, function "tok_match" below.
exception Error of string;
A lexing error exception to be used by lexers.

lexer type

type lexer 'te =
  { tok_func : lexer_func 'te;
    tok_using : pattern -> unit;
    tok_removing : pattern -> unit;
    tok_match : mutable pattern -> 'te -> string;
    tok_text : pattern -> string;
    tok_comm : mutable option (list Ploc.t) }
The type for lexers compatible with Camlp5 grammars. The parameter type "'te" is the type of the tokens.
  • The field "tok_func" is the main lexer function. See "lexer_func" type below.
  • The field "tok_using" is a function called by the "EXTEND" statement to warn the lexer that a rule uses this pattern (given as parameter). This allow the lexer 1/ to check that the pattern constructor is really among its possible constructors 2/ to enter the keywords in its tables.
  • The field "tok_removing" is a function possibly called by the "DELETE_RULE" statement to warn the lexer that this pattern (given as parameter) is no longer used in the grammar (the grammar system maintains a number of usages of all patterns and calls this function when this number falls to zero). If it is a keyword, this allows the lexer to remove it in its tables.
  • The field "tok_match" is a function called by the Camlp5 grammar system to ask the lexer how the input tokens should be matched against the patterns. Warning: for efficiency, this function must be written as a function taking patterns as parameters and, for each pattern value, returning a function matching a token, not as a function with two parameters.
  • The field "tok_text" is a function called by the grammar system to get the name of the tokens for the error messages, in case of syntax error, or for the displaying of the rules of an entry.
  • The field "tok_comm" is a mutable place where the lexer can put the locations of the comments, if its initial value is not "None". If it is "None", nothing has to be done by the lexer.
and lexer_func 'te = Stream.t char -> (Stream.t 'te * location_function)
The type of a lexer function (field "tok_func" of the type "lexer"). The character stream is the input stream to be lexed. The result is a pair of a token stream and a location function (see below) for this tokens stream.
and location_function = int -> Ploc.t;
The type of a function giving the location of a token in the source from the token number in the stream (starting from zero).
value lexer_text : pattern -> string;
A simple "tok_text" function.
value default_match : pattern -> (string * string) -> string;
A simple "tok_match" function, appling to the token type "(string * string)".

lexers from parsers or ocamllex

The functions below create lexer functions either from a "char stream" parser or for an "ocamllex" function. With the returned function "f", it is possible to get a simple lexer (of the type "Plexing.lexer" above):

   {Plexing.tok_func = f;
    Plexing.tok_using = (fun _ -> ());
    Plexing.tok_removing = (fun _ -> ());
    Plexing.tok_match = Plexing.default_match;
    Plexing.tok_text = Plexing.lexer_text}

Note that a better "tok_using" function would check the used tokens and raise "Plexing.Error" for incorrect ones. The other functions "tok_removing", "tok_match" and "tok_text" may have other implementations as well.

value lexer_func_of_parser :
  ((Stream.t char * ref int * ref int) -> ('te * Ploc.t)) -> lexer_func 'te;
A lexer function from a lexer written as a char stream parser returning the next token and its location. The two references with the char stream contain the current line number and the position of the beginning of the current line. 
value lexer_func_of_ocamllex : (Lexing.lexbuf -> 'te) -> lexer_func 'te;
A lexer function from a lexer created by "ocamllex".

function to build a stream and a location function

value make_stream_and_location :
  (unit -> ('te * Ploc.t)) -> (Stream.t 'te * location_function);

useful functions and values

value eval_char : string -> char;
value eval_string : Ploc.t -> string -> string;
Convert a char or a string token, where the backslashes are not been interpreted into a real char or string; raise "Failure" if a bad backslash sequence is found; "Plexing.eval_char (Char.escaped c)" returns "c" and "Plexing.eval_string (String.escaped s)" returns s.
value restore_lexing_info : ref (option (int * int));
value line_nb : ref (ref int);
value bol_pos : ref (ref int);
Special variables used to reinitialize line numbers and position of beginning of line with their correct current values when a parser is called several times with the same character stream. Necessary for directives (e.g. #load or #use) which interrupt the parsing. Without usage of these variables, locations after the directives can be wrong.

backward compatibilities

Deprecated since version 4.08.

type location = Ploc.t;
value make_loc : (int * int) -> location;
value dummy_loc : location;

Plexer module

This module contains a lexer used for OCaml syntax (revised and normal).

lexer

value gmake : unit -> Plexing.lexer (string * string);
"gmake ()" returns a lexer compatible with the extensible grammars. The returned tokens follow the normal syntax and the revised syntax lexing rules.

The token type is "(string * string)" just like the pattern type.

The meaning of the tokens are:

The associated token patterns