home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / C / Applications / Moscow ML 1.42 / lib / PP.sig < prev    next >
Encoding:
Text File  |  1997-08-18  |  6.6 KB  |  178 lines  |  [TEXT/Moml]
  1. (* PP -- from the SML/NJ library *)
  2.  
  3. type ppconsumer = {consumer  : string -> unit,
  4.                    linewidth : int,
  5.                    flush     : unit -> unit}
  6.  
  7. datatype break_style = 
  8.     CONSISTENT
  9.   | INCONSISTENT
  10.  
  11. val mk_ppstream    : ppconsumer -> ppstream
  12. val dest_ppstream  : ppstream -> ppconsumer
  13. val add_break      : ppstream -> int * int -> unit
  14. val add_newline    : ppstream -> unit
  15. val add_string     : ppstream -> string -> unit
  16. val begin_block    : ppstream -> break_style -> int -> unit
  17. val end_block      : ppstream -> unit
  18. val clear_ppstream : ppstream -> unit
  19. val flush_ppstream : ppstream -> unit
  20. val with_pp        : ppconsumer -> (ppstream -> unit) -> unit
  21. val pp_to_string   : int -> (ppstream -> 'a -> unit) -> 'a -> string
  22.  
  23. (* This unit provides tools for creating customized Oppen-style
  24.    pretty-printers, based on the type ppstream.  A ppstream is an
  25.    output stream that contains prettyprinting commands.  The commands
  26.    are placed in the stream by various function calls listed below.
  27.  
  28.    There following primitives add commands to the stream:
  29.    begin_block, end_block, add_string, add_break, and add_newline.
  30.    All calls to add_string, add_break, and add_newline must happen
  31.    between a pair of calls to begin_block and end_block must be
  32.    properly nested dynamically.  All calls to begin_block and
  33.    end_block must be properly nested (dynamically).
  34.  
  35.    A ppconsumer is a record 
  36.                  {consumer  : string -> unit,
  37.                   linewidth : int,
  38.                   flush     : unit -> unit}
  39.    of a string consumer, a specified linewidth, and a flush function
  40.    which is called whenever flush_ppstream is called.
  41.  
  42.    A prettyprinter can be called outright to print a value.  In
  43.    addition, a prettyprinter for a nullary datatype ty can be
  44.    installed in the top-level system.  Then the installed
  45.    prettyprinter will be invoked automatically whenever a value of
  46.    type ty is to be printed.
  47.  
  48.    [type break_style] determines the way a block is broken into
  49.    lines.  Style CONSISTENT means that if any line break occurs
  50.    inside the block, then all indicated line breaks occur.  Style
  51.    INCONSISTENT means that breaks will be inserted to only to avoid
  52.    overfull lines.
  53.  
  54.    [mk_ppstream {consumer, linewidth, flush}] creates a new ppstream
  55.    which invokes the consumer to output text, putting at most
  56.    linewidth characters on each line.
  57.  
  58.    [dest_ppstream ppstrm] extracts the linewidth, flush function, and
  59.    consumer from a ppstream.
  60.  
  61.    [add_break ppstrm (size, offset)] notifies the pretty-printer that
  62.    a line break is possible at this point.  
  63.    * When the current block style is CONSISTENT:
  64.       ** if the entire block fits on the remainder of the line, then
  65.          output size spaces; else
  66.       ** increase the current indentation by the block offset;
  67.          further indent every item of the block by offset, and add
  68.          one newline at every add_break in the block.
  69.    * When the current block style is INCONSISTENT:
  70.       ** if the next component of the block fits on the remainder of
  71.          the line, then output size spaces; else
  72.       ** issue a newline and indent to the current indentation level
  73.          plus the block offset plus the offset.
  74.  
  75.    [add_newline ppstrm] issues a newline.
  76.  
  77.    [add_string ppstrm str] outputs the string str to the ppstream.
  78.  
  79.    [begin_block ppstrm style blockoffset] begins a new block and
  80.    level of indentation, with the given style and block offset.
  81.  
  82.    [end_block ppstrm] closes the current block.  
  83.  
  84.    [clear_ppstream ppstrm] restarts the stream, without affecting the
  85.    underlying consumer.
  86.  
  87.    [flush_ppstream ppstrm] executes any remaining commands in the
  88.    ppstream (that is, flushes currently accumulated output to the
  89.    consumer associated with ppstrm); executes the flush function
  90.    associated with the consumer; and calls clear_ppstream.
  91.  
  92.    [with_pp consumer f] makes a new ppstream from the consumer and
  93.    applies f (which can be thought of as a producer) to that
  94.    ppstream, then flushed the ppstream and returns the value of f.
  95.  
  96.    [pp_to_string linewidth printit x] constructs a new ppstream
  97.    ppstrm whose consumer accumulates the output in a string s.  Then
  98.    evaluates (printit ppstrm x) and finally returns the string s.
  99.  
  100.    
  101.    Example 1: A simple prettyprinter for Booleans:
  102.  
  103.        load "PP";
  104.        fun ppbool pps d = 
  105.            let open PP
  106.            in
  107.                begin_block pps INCONSISTENT 6; 
  108.                add_string pps (if d then "right" else "wrong");
  109.                end_block pps
  110.            end;
  111.  
  112.    Now one may define a ppstream to print to, and exercise it:
  113.  
  114.        val ppstrm = PP.mk_ppstream {consumer  = 
  115.                                     fn s => TextIO.output(TextIO.stdOut, s), 
  116.                                     linewidth = 72,
  117.                                     flush     = 
  118.                      fn () => TextIO.flushOut TextIO.stdOut};
  119.  
  120.        fun ppb b = (ppbool ppstrm b; PP.flush_ppstream ppstrm);
  121.  
  122.        - ppb false;
  123.        wrong> val it = () : unit   
  124.  
  125.    The prettyprinter may also be installed in the toplevel system;
  126.    then it will be used to print all expressions of type bool
  127.    subsequently computed:
  128.  
  129.        - installPP ppbool;
  130.        > val it = () : unit
  131.        - 1=0;
  132.        > val it = wrong : bool
  133.        - 1=1;
  134.        > val it = right : bool
  135.  
  136.    See library Meta for a description of installPP.
  137.  
  138.  
  139.    Example 2: Prettyprinting simple expressions (file examples/ppexpr.sml)
  140.  
  141.        datatype expr = 
  142.            Cst of int 
  143.          | Neg of expr
  144.          | Plus of expr * expr
  145.  
  146.        fun ppexpr pps e0 = 
  147.            let open PP
  148.                fun ppe (Cst i)        = add_string pps (Int.toString i)
  149.                  | ppe (Neg e)        = (add_string pps "~"; ppe e)
  150.                  | ppe (Plus(e1, e2)) = (begin_block pps CONSISTENT 0;
  151.                                          add_string pps "(";
  152.                                          ppe e1; 
  153.                                          add_string pps " + ";
  154.                                          add_break pps (0, 1);
  155.                                          ppe e2; 
  156.                                          add_string pps ")";
  157.                                          end_block pps)
  158.            in
  159.                begin_block pps INCONSISTENT 0; 
  160.                ppe e0;
  161.                end_block pps
  162.            end
  163.  
  164.        val _ = installPP ppexpr;
  165.  
  166.        (* Some example values: *)
  167.  
  168.        val e1 = Cst 1;
  169.        val e2 = Cst 2;
  170.        val e3 = Plus(e1, Neg e2);
  171.        val e4 = Plus(Neg e3, e3);
  172.        val e5 = Plus(Neg e4, e4);
  173.        val e6 = Plus(e5, e5);
  174.        val e7 = Plus(e6, e6);
  175.        val e8 = 
  176.            Plus(e3, Plus(e3, Plus(e3, Plus(e3, Plus(e3, Plus(e3, e7))))));
  177. *)
  178.