Document pretty-printing mechanism

Author: smowton

src/langapi/language_util.cpp

@@ -51,11 +51,73 @@ static languaget* get_language(
 
 std::vector<pretty_printer_factoryt> registered_pretty_printers;
 
+/*******************************************************************\
+
+Function: register_global_pretty_printer
+
+  Inputs: `new_printer`: factory method returning
+             `unique_ptr<pretty_printert>`
+
+ Outputs:
+
+ Purpose: This registers a custom pretty-printer for use printing
+          expressions with `from_expr` and `from_type` also defined
+          in language_util.h. The function given should allocate
+          an instance of the printer and return a unique_ptr that
+          disposes of it appropriately (so if allocated with `new`,
+          ordinary `std::unique_ptr` will do the trick).
+          `from_expr` and `from_type` will always build a stack of
+          printer classes of the form:
+          L -> C1 -> C2 ... Cn -> X
+
+          L is the language frontend pretty-printer associated
+          with an expression, C1 ... Cn are instances of the registered
+          custom printers in order of registration, and X is the fallback
+          irep-to-lisp printer `norep_pretty_printert`. The -> arrows
+          represent `next_pretty_printer` fields used to defer printing
+          of expressions a particular printer can't handle; all printers
+          in the stack also get `top_pretty_printer` set to point at L,
+          which they should use when printing subexpressions to give
+          the whole stack a chance to provide a representation.
+
+          Note at present language custom printers such as `expr2javat`
+          are subclasses of `expr2ct` rather than using this deferral
+          mechanism; thus even when a Java expression is being printed
+          there is still only one L in the stack, rather than
+          expr2javat -> expr2ct -> C1 ... Cn -> X
+          as one might expect. The language printers (in particular
+          expr2ct) always assume they are at the top of the stack
+          (so top_pretty_printer == this), and will need adapting if
+          we want to e.g. place a custom printer *above* expr2ct
+          in the future.
+
+\*******************************************************************/
+
 void register_global_pretty_printer(pretty_printer_factoryt new_printer)
 {
   registered_pretty_printers.push_back(new_printer);
 }
 
+/*******************************************************************\
+
+Function: get_pretty_printer_stack
+
+  Inputs: `ns`: namespace
+          `language_printer`: pointer to instance of a pretty-printer
+             that should be placed at the head of the printer stack.
+
+ Outputs:
+
+ Purpose: (See `register_global_pretty_printer` above for context)
+          Takes a reference to language-specific pretty-printer L,
+          instantiates custom printers C1 .. Cn if any have been
+          registered, creates the fallback norep pretty-printer X,
+          and sets their next_ and top_pretty_printer pointers.
+          A vector of unique pointers is returned whose back member
+          is the head of the stack (L, in the notation used above).
+
+\*******************************************************************/
+
 static std::vector<std::unique_ptr<pretty_printert>> get_pretty_printer_stack(
   const namespacet &ns,
   std::unique_ptr<pretty_printert> language_printer)
@@ -84,11 +146,17 @@ static std::vector<std::unique_ptr<pretty_printert>> get_pretty_printer_stack(
 
 Function: from_expr
 
-  Inputs:
+  Inputs: `ns`: global namespace
+          `identifier`: symbol-table identifier associated with `expr`
+            or the empty string if none
+          `expr`: expression to print
 
- Outputs:
+ Outputs: Returns pretty-printed string equivalent of `expr`.
 
- Purpose:
+ Purpose: Pretty-prints an expression. If custom pretty-printers have
+          been registered they will be instantiated and may take part
+          in printing `expr`; see `register_global_pretty_printer` for
+          details.
 
 \*******************************************************************/
 
@@ -106,11 +174,17 @@ std::string from_expr(
 
 Function: from_type
 
-  Inputs:
+  Inputs: `ns`: global namespace
+          `identifier`: symbol-table identifier associated with `type`
+            or the empty string if none
+          `type`: type to print
 
- Outputs:
+ Outputs: Returns pretty-printed string equivalent of `type`.
 
- Purpose:
+ Purpose: Pretty-prints an type. If custom pretty-printers have
+          been registered they will be instantiated and may take part
+          in printing `type`; see `register_global_pretty_printer` for
+          details.
 
 \*******************************************************************/
 

src/langapi/pretty_printer.h

@@ -1,8 +1,8 @@
 /*******************************************************************\
 
-Module:
+Module: Generic expression / type pretty-printer
 
-Author: Daniel Kroening, [email protected]
+Author: Chris Smowton, [email protected]
 
 \*******************************************************************/
 
@@ -18,6 +18,16 @@ Author: Daniel Kroening, [email protected]
 
 #include <cassert>
 
+/*
+ * Interface to an expression and/or type pretty-printer.
+ * The convert(...) routines should pretty-print the expressions
+ * they know how to deal with, and defer to next_pretty_printer
+ * for those they can't handle, and top_pretty_printer for
+ * subexpressions (whether it understands them or not).
+ * Per default they always defer.
+ * See `util/language_util.h` and particularly
+ * `register_global_pretty_printer` for detail on how these are used.
+ */
 class pretty_printert
 {
  public: