Written in Modula-2+ by John Ellis before the dawn of history Converted to Modula-3 by Bill Kalsow on Oct 1989 Last modified on Mon Dec 12 10:25:31 PST 1994 by kalsow modified on Sun Feb 23 14:45:05 PST 1992 by meehan modified on Thu Jul 25 19:30:30 PDT 1991 by stolfi modified on Thu Jul 25 20:44:22 1991 by muller modified on Mon Apr 22 17:34:37 1991 by nichols@xerox.com

INTERFACE XFormat;

A Formatter.T is a basic tool for pretty printing, the printing of structured objects with appropriate line breaks and indentation.

Index: formatted streams; printing, structured data; pretty printers

IMPORT Text, Wx, Wr;

TYPE T <: T_;
  (*
    A Formatter.T is a filter which takes a sequence of /expressions/
    and converts them into a sequence of characters, which are sent to
    an underlying Wx.T.

    The input expressions consist of character strings intermixed with
    /formatting operators/ that specify a set of possible line breaks,
    and the relative alignment of parts in multi-line expressions.  The
    SxFormatter.T chooses a "good" subset of the given line breaks,
    inserts newlines and padding whitespaces at those points, and writes
    the result to the underlying writer. *)

PROCEDURE New (wr: Wx.T;  width: CARDINAL := 75): T;
  (*
    Creates a new Formatter.T  whose output will go to "wr".
    The /width/ parameter specifies the nominal maximum line width.
    *)

TYPE BreakType = {NonOptimal, OptimalBreak, OptimalNoBreak};

TYPE
  T_ = OBJECT METHODS

    underlyingWr (): Wx.T;
    (*
      Returns the writer that is connected to the output of /t/. *)

    close () RAISES {Wr.Failure};
    (*
      Flushes all buffered expressions to the underlying writer,
      with proper line breaks, and releases internal resources.
      The formatter /t/ should not be used afterwards. *)

    flush () RAISES {Wr.Failure};
    (*
      Flushes all buffered expressions to the underlying writer, with
      proper line breaks.  Automatically supplies /End/s for all unmatched
      /Group/s, /Begin/s, and /Align/s (see below).  Returns only after
      the output has made it to the writer.  *)

The following procedures insert characters and strings into the formatter's input stream:

putText (text: Text.T;  raw:= FALSE) RAISES {Wr.Failure};
    (*
      If /raw=TRUE/, sends an expression consisting of the given text,
      irrespective of its content.

      If /raw=FALSE/ (the default), breaks the text into substrings
      before and after each blank or newline, and sends each piece as
      a separate expression.
      *)

    putChar (c: CHAR) RAISES {Wr.Failure};
    (*
      If c='\n', sends a NewLine(t) operator to the formatter; otherwise
      sends the character /c/ itself.

      Successive calls to PutChar whose arguments are neither ' ' nor
      '\n' are compacted into a single text string.
      *)

    putMarkup (text: Text.T;  width := 0) RAISES {Wr.Failure};
    (*
      Sends an expression consisting of the given text with the
      assumption that it displays in /width/ characters of output.
      *)

The following procedures send line breaking operators to the formatter. There are four kinds of line breaks:

Break BreakOpt PartialBreak NewLine UnitedBreak

Precedence decreases from top to bottom. That is, the input expresion stream is parsed as a sequence of terms separated by /UnitedBreak/s; each term is parsed as a sequence of factors separated by /NewLine/s; and so on. These precedences can be overriden by enclosing expressions between /Group/ and /End/ operators (see below).

break (offset := 0;  type := BreakType.OptimalBreak;  freshLine := TRUE)
       RAISES {Wr.Failure};
    (*
      Specifies an optional line break.

      Breaks come in three types:

      NonOptimal:  If the expressions /e1, e2, .../ following the /Break/
      (up to the next line break or /End/) can be printed on the current
      line without exceeding the line width, they are so printed.
      Otherwise, a NewLine(t, offset, freshLine) is performed and the
      expressions are then printed.

      OptimalBreak, OptimalNoBreak: Two possibilities are compared:

        1. Printing the expressions /e1, e2, .../ without any
           preceeding newline.

        2. Doing a NewLine(t, offset, freshLine) and then printing
           those expressions.

      The option that uses fewer lines without exceeding the line width
      is chosen.  Ties are broken in favor of either 1 (OptimalNoBreak)
      or 2 (OptimalBreak).

      In general, optimal breaks are more expensive than
      non-optimal ones. *)

    partialBreak (offset := 0;  freshLine := TRUE)  RAISES {Wr.Failure};
    (*
      Performs a Newline(t, offset, freshLine) if more than one line
      has been used up to this point to print the current innermost
      object delimited by Begin/End. *)

    newLine (offset := 0;  freshLine := TRUE) RAISES {Wr.Failure};
    (*
      Starts a new line indented /offset/ spaces from the current left
      margin (see /Begin/).   If /freshline/ is true, starts a newline only if
      /leftMargin + offset < c/, where /c/ is the current column of the
      current position. *)

    unitedBreak (offset := 0;  freshLine := TRUE) RAISES {Wr.Failure};
    (*
      Inserts a new member of an all-or-none group of line breaks.

      If all the expressions in the innermost /Group/ or /Begin/ can be
      printed so that they all fit on the current line, then they are
      so printed, and every top-level /UnitedBreak/ in that group is ignored.
      Otherwise, every top-level /UnitedBreak/ in that group is
      equivalent to a NewLine(t, offset, freshLine). *)

group () RAISES {Wr.Failure};
    (*
      Logical parenthesis: the expressions between a /Group/ and the matching
      /End/ will be treated as a single expression. *)

    begin (offset := 0;  width: CARDINAL := LAST(CARDINAL)) RAISES {Wr.Failure};
    (*
      The operators /Begin/ and /End/ delimit a structured object,
      consisting of the enclosed expressions and formatting operators.

      /Begin/ establishes a new left margin "offset" spaces to the right
      of the first character of the object.  Any line breaks occuring
      in the printing of the enclosed expressions will be relative to
      this new margin.  If "offset" = LAST( INTEGER ), then the current
      left margin is retained.

      If /width/ < LAST(INTEGER), the enclosed expressions are printed
      assuming this new nominal line width.

      The old left margin and line width are restored after the object
      has been printed.  *)

    align (
      columns:      CARDINAL;
      tryOneLine:   BOOLEAN := TRUE;
      offset:       INTEGER := 0;
      alignPred:    AlignPred := NIL;
    )  RAISES {Wr.Failure};
    (*
      The /Align/ operator produces a table with multiple
      columns, aligned if possible.

      The expressions between the /Align/ and the matching /End/ describe
      the rows of the table.  Each row should be either a list of
      expressions delimited by /Group/ and /End/, or a non-aligned row
      (see NoAlign).  The /offset/ parameter specifies the left-margin
      offset for each row.

      Each expression in a row will be in a separate column.  It is an
      error if a row has more than /columns/ entries, but a row may have
      fewer.

      IF /tryOneLine/ is true and the initial output position is in the
      first line of the enclosing Begin/End object, then Align will
      print all the rows on that one line (if they fit).

      Align will align the maximal set of leading rows such that each row
      fits on a single line, each row's columns satisfy the /alignPred/
      predicate, and the row is not a NoAlign row.  Then it will
      recursively align the rest of the rows without regard to the
      alignment of the leading rows.  *)

    noAlign ()  RAISES {Wr.Failure};
    (*
      A /NoAlign/ operator, valid only as a top-level member in an
      Align/End group, specifies that the following expression /e/ should
      not be aligned with the previous or succeeding rows, and should
      not affect their alignment.

      The expression /e/ is printed without any leading newline.
      Typically, /e/ will be a group or a raw text containing its own
      leading newline, but not a trailing newline.  *)

    col (column: INTEGER; relative := FALSE; space: CARDINAL := 0)
      RAISES {Wr.Failure};
    (*
      If the current position of the formatter is less than "column"
      (zero-based), emit enough spaces to go to that column.  Otherwise, emit
      "space" spaces.  If "relative" is TRUE, interpret "column" as being
      relative to the current left margin; in this case, it is meaningful
      for "column" to be negative. *)

    end () RAISES {Wr.Failure};
    (*
      Delineates the end of /Group/, /Begin/, and /Align/ operators.

      The /Flush/ procedure automatically supplies /End/s
      for all unmatched /Group/s, /Begin/s, and /Align/s. *)

  END; (* OBJECT T_ *)

TYPE
  AlignPred = OBJECT METHODS

      pred (
        column:   CARDINAL;
        maxWidth: CARDINAL;
        width:    CARDINAL
      ): BOOLEAN;

    END;
  (*
    If the /alignPred/ parameter of /Align/ is non-nil, then

        alignPred.pred(arg, column, maxWidth, width)

    is called for each column in each row, where /column/ is the 0-based
    column number, /maxWidth/ is the maximum width of that column in
    the previous rows being aligned, and /width/ is the width of column
    in the current row.

    If any of these calls returns FALSE, the entire row is printed
    without any column alignment, as if it were preceded by a /NoAlign/
    operator. *)

END XFormat.