From 6dfa0b88e6754f82c3d0f6e4e2387f36fddd5b17 Mon Sep 17 00:00:00 2001 From: Nathan Rebours Date: Wed, 17 Jan 2024 16:15:31 +0100 Subject: [PATCH] Move the exception handling section to the driver spec Signed-off-by: Nathan Rebours --- doc/driver.mld | 22 ++++++++++++++++++++++ doc/good-practices.mld | 25 ------------------------- 2 files changed, 22 insertions(+), 25 deletions(-) diff --git a/doc/driver.mld b/doc/driver.mld index 7cac676ca..1ca06b657 100644 --- a/doc/driver.mld +++ b/doc/driver.mld @@ -119,6 +119,28 @@ driver.exe [extra_args] v} {%html: %} +{3 Exceptions handling} + +In general, raising an exception in a registered transformation will make the +ppxlib driver crash with an uncaught exception error. However, when spawned with +the [-embed-errors] or [-as-ppx] flags (that's the case when Merlin calls the +driver) the ppxlib driver still handles a specific kind of exception: Located +exceptions. They have type {{!Ppxlib.Location.exception-Error}[Location.Error]} +and contain enough information to display a located error message. + +During its {{!page-driver.driver_execution}execution}, the driver will run many +different rewriters. In the case described above, it will catch any located +exception thrown by a rewriter. When catching an exception, it will collect the +error in a list, take the last valid AST (the one that was given to the raising +rewriter) and continue its execution from there. + +At the end of the rewriting process, the driver will prepend all collected errors +to the beginning of the AST, in the order in which they appeared. + +The same mechanism applies for the context-free rewriters: if any of them raises, +the error is collected, the part of the AST that the rewriter was responsible to +rewrite remains unmodified, and the context-free phase continues. + {2 Cookies} Cookies are values that are passed to the driver via the command line, or set as diff --git a/doc/good-practices.mld b/doc/good-practices.mld index a3b9525c4..d1999ba89 100644 --- a/doc/good-practices.mld +++ b/doc/good-practices.mld @@ -83,31 +83,6 @@ error, the embedding mechanism has many advantages. For instance, embedding allows to report multiple errors, and to output the part of the code that could be generated successfully. -{2 Ppxlib and exceptions} - -In general, raising an exception in a registered transformation will make the -ppxlib driver crash with an uncaught exception error. However, when spawned with -the [-embed-errors] or [-as-ppx] flags (that's the case when Merlin calls the -driver) the ppxlib driver still handles a specific kind of exception: Located -exceptions. They have type {{!Ppxlib.Location.exception-Error}[Location.Error]} -and contain enough information to display a located error message. - -During its {{!page-driver.driver_execution}execution}, the driver will run many -different rewriters. In the case described above, it will catch any located -exception thrown by a rewriter. When catching an exception, it will collect the -error in a list, take the last valid AST (the one that was given to the raising -rewriter) and continue its execution from there. - -At the end of the rewriting process, the driver will prepend all collected errors -to the beginning of the AST, in the order in which they appeared. - -The same mechanism applies for the context-free rewriters: if any of them raises, -the error is collected, the part of the AST that the rewriter was responsible to -rewrite remains unmodified, and the context-free phase continues. - -The function provided by the API to raise located errors is -{{!Ppxlib.Location.raise_errorf}[Location.raise_errorf]}. - {2 Embedding the Errors in the AST} It is better to always return a valid AST, as complete as possible, but with