Previous Up Next
Chapter 3 Quotations
This chapter presents the Camlp4 quotation system. A quotation is a part of a program enclosed by special parentheses in position of expression or pattern (exclusively), and whose treatment is done by an user function, called a ``quotation expander''. Several quotations are usable in the same source code.

When Camlp4 encounters such a construction, the appropriate quotation expander is called with the string contents of the quotation.

There are two kinds of quotation expanders:
3.1 Syntax

There are two kinds of quotations: The string inside a quotation is any string. It can hold other quotations. The string sequences ``<<'', ``<:id<'' and ``>>'', if not matching, must be prefixed by a backslash and backslashes must be doubled.

3.2 Creating a quotation expander

A quotation expander is a function written in OCaml. A call to the Camlp4 library function ``Quotation.add'' (see section ??) adds the quotation expander. The variable ``Quotation.default'' holds the name of the default quotation.

The file holding the quotation expander must be compiled using the OCaml compiler, with the Camlp4 library directory in its directory path (option ``-I''). An object file (ending with ``.cmo'') is created, which is loadable in Camlp4, as parameter of the command ``camlp4'', or in the OCaml toplevel using the directive ``#load''.

3.3 Antiquotations

Antiquotation is a programming technique to specify expressions or patterns in a quotation, parsed in the context of the enclosing expression or pattern where the quotation is.

The way an antiquotation is specified depends on the quotation expander: typically a specific character and an identifier, or specific parentheses and a complete expression or pattern.

3.4 Errors

If some kind of error happens while compiling a quotation, an error message is displayed, which shows the source position of the error. By default, the error message highlights the whole quotation, but a quotation expander can specify more precise ``locations'' while parsing and generating its returning string.

A ``location'' is a couple of integers: the first one is the position of the first character of the concerned text, the second one the position of the first character after the concerned text.

3.4.1 Exception raised in an expander

If an exception is raised in the expander, the quotation is highlighted, the exception name is displayed, and the parsing fails.

To be more precise, the expander can call the function ``Stdpp.raise_with_loc'' instead instead of ``raise'', this first function having a supplementary parameter which is the location of the error relative to the begin of the quotation. In this case, the error message highlights only the located part of the quotation.

3.4.2 Error while parsing the expander result (string expanders)

A problem can arise in string expanders (those returning strings). The resulting string may hold syntax errors. In this case, because there is no ``input location'' for the error, it is not directly possible to see this error.

To solve this problem, a special option of Camlp4 can be used: ``-QD'' (see the manual page). It is also possible to set the variable ``Pcaml.quotation_dump_file'' (see section ??). The offending string is then written in a file (whose name is specified by this option or this variable) and the error message gives the location of the error in this file. This technique is useful when perfecting or debugging the quotation expander: a good quotation expander should never generate errored strings.

This problem cannot arise in syntax trees expanders, because there is no parsing following the expansion.

3.4.3 Typing error

It is possible to specify precise source locations to some parts (antiquotations) of the expander resulting string. For this, there are to ways depending on the expander kind:
3.5 Predefined quotation expanders

A quotation expander is provided in the file ``q_MLast.cmo'' allowing to create abstract syntax tree nodes from concrete revised syntax. It is used in language syntax extensions (chapter 5).

Another quotation expander provided is ``q_phony.cmo''. It transforms all quotations into variables whose name holds all the text of the quotation, << and >> included. It is useful for pretty printing programs with the quotations not expanded.

Previous Up Next