Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all bug

NAME

       prettypr - A generic pretty printer library.

DESCRIPTION

       A  generic  pretty  printer  library.  This  module  uses  a  strict-style context passing
       implementation of John Hughes algorithm, described in "The  design  of  a  Pretty-printing
       Library".  The  paragraph-style  formatting, empty documents, floating documents, and null
       strings are my own additions to the algorithm.

       To get started, you should read about the  document()  data  type;  the  main  constructor
       functions:  text/1,  above/2,  beside/2,  nest/2,  sep/1,  and  par/2; and the main layout
       function format/3.

       If you simply want to format a paragraph of plain text,  you  probably  want  to  use  the
       text_par/2 function, as in the following example:

         prettypr:format(prettypr:text_par("Lorem ipsum dolor sit amet"), 20)

DATA TYPES

         document():

           An  abstract  character-based  "document"  representing  a number of possible layouts,
           which can be processed to produce a single concrete layout. A concrete layout can then
           be  rendered as a sequence of characters containing linebreaks, which can be passed to
           a printer or terminal that uses a fixed-width font.

           For example, a document sep([text("foo"), text("bar")]) represents the two layouts

              foo bar

           and

              foo
              bar

           Which layout is chosen depends on the available horizontal space.  When  processing  a
           document,  the  main  parameters are the paper width and the line width (also known as
           the "ribbon width"). In the resulting layout, no text should  be  printed  beyond  the
           paper width (which by default is 80 characters) as long as it can be avoided, and each
           single line of text (its indentation not counted, hence "ribbon") should preferably be
           no wider than the specified line width (which by default is 65).

           Documents  can be joined into a single new document using the constructor functions of
           this module. Note that the new document often represents a larger number  of  possible
           layouts than just the sum of the components.

EXPORTS

       above(D1::document(), D2::document()) -> document()

              Concatenates   documents   vertically.   Returns   a   document   representing  the
              concatenation of the documents D1 and D2 such that the first  line  of  D2  follows
              directly  below  the  last line of D1, and the first character of D2 is in the same
              horizontal column as the first character of D1, in all possible layouts.

              Examples:

                   ab  cd  =>  ab
                               cd

                                  abc
                   abc   fgh  =>   de
                    de    ij      fgh
                                   ij

       beside(D1::document(), D2::document()) -> document()

              Concatenates  documents  horizontally.  Returns   a   document   representing   the
              concatenation  of  the  documents  D1  and D2 such that the last character of D1 is
              horizontally adjacent to the first character of D2, in all possible layouts. (Note:
              any indentation of D2 is lost.)

              Examples:

                   ab  cd  =>  abcd

                   ab  ef      ab
                   cd  gh  =>  cdef
                                 gh

       best(D::document(), PaperWidth::integer(), LineWidth::integer()) -> empty | document()

              Selects  a  "best"  layout  for  a  document, creating a corresponding fixed-layout
              document. If no layout could be produced, the atom empty is returned  instead.  For
              details about PaperWidth and LineWidth, see format/3. The function is idempotent.

              One  possible  use  of  this  function is to compute a fixed layout for a document,
              which can then be included as part of a larger document. For example:

                   above(text("Example:"), nest(8, best(D, W - 12, L - 6)))

              will format D as a displayed-text example indented by  8,  whose  right  margin  is
              indented  by 4 relative to the paper width W of the surrounding document, and whose
              maximum individual line length is shorter by 6  than  the  line  length  L  of  the
              surrounding document.

              This  function  is used by the format/3 function to prepare a document before being
              laid out as text.

       break(D::document()) -> document()

              Forces a line break at the end of the given document. This is a  utility  function;
              see empty/0 for details.

       empty() -> document()

              Yields  the  empty  document,  which  has  neither height nor width. (empty is thus
              different from an empty text string, which has zero width but height 1.)

              Empty documents are occasionally useful; in particular, they have the property that
              above(X, empty()) will force a new line after X without leaving an empty line below
              it; since this is a common idiom, the utility function break/1 will place  a  given
              document in such a context.

              See also: text/1.

       floating(D::document()) -> document()

              Equivalent to floating(D, 0, 0).

       floating(D::document(), Hp::integer(), Vp::integer()) -> document()

              Creates  a "floating" document. The result represents the same set of layouts as D;
              however, a floating document may be moved  relative  to  other  floating  documents
              immediately beside or above it, according to their relative horizontal and vertical
              priorities. These priorities are set with the Hp and  Vp  parameters;  if  omitted,
              both default to zero.

              Notes:  Floating documents appear to work well, but are currently less general than
              you might wish, losing effect when embedded in certain contexts. It is possible  to
              nest  floating-operators  (even  with different priorities), but the effects may be
              difficult to predict. In any  case,  note  that  the  way  the  algorithm  reorders
              floating documents amounts to a "bubblesort", so don't expect it to be able to sort
              large sequences of floating documents quickly.

       follow(D1::document(), D2::document()) -> document()

              Equivalent to follow(D1, D2, 0).

       follow(D1::document(), D2::document(), Offset::integer()) -> document()

              Separates two documents by either a single space, or a line break and  intentation.
              In other words, one of the layouts

                   abc def

              or

                   abc
                    def

              will  be  generated,  using  the  optional offset in the latter case. This is often
              useful for typesetting programming language constructs.

              This is a utility function; see par/2 for further details.

              See also: follow/2.

       format(D::document()) -> string()

              Equivalent to format(D, 80).

       format(D::document(), PaperWidth::integer()) -> string()

              Equivalent to format(D, PaperWidth, 65).

       format(D::document(), PaperWidth::integer(), LineWidth::integer()) -> string()

              Computes a layout for a document and returns the corresponding text. See document()
              for further information. Throws no_layout if no layout could be selected.

              PaperWidth  specifies  the  total  width  (in character positions) of the field for
              which the text is to be laid out. LineWidth specifies the desired maximum width (in
              number  of characters) of the text printed on any single line, disregarding leading
              and trailing white space. These parameters need to be properly balanced in order to
              produce good layouts. By default, PaperWidth is 80 and LineWidth is 65.

              See also: best/3.

       nest(N::integer(), D::document()) -> document()

              Indents a document a number of character positions to the right. Note that N may be
              negative, shifting the text to the left, or zero,  in  which  case  D  is  returned
              unchanged.

       null_text(Characters::string()) -> document()

              Similar  to  text/1,  but  the  result  is  treated  as  having zero width. This is
              regardless of the actual length of the string. Null  text  is  typically  used  for
              markup, which is supposed to have no effect on the actual layout.

              The  standard  example  is  when formatting source code as HTML to be placed within
              <pre>...</pre> markup, and using e.g. <i> and <b> to make parts of the source  code
              stand  out.  In  this  case,  the markup does not add to the width of the text when
              viewed in an HTML browser, so the layout engine  should  simply  pretend  that  the
              markup has zero width.

              See also: empty/0, text/1.

       par(Docs::[document()]) -> document()

              Equivalent to par(Ds, 0).

       par(Docs::[document()], Offset::integer()) -> document()

              Arranges  documents in a paragraph-like layout. Returns a document representing all
              possible left-aligned paragraph-like layouts of the  (nonempty)  sequence  Docs  of
              documents.  Elements in Docs are separated horizontally by a single space character
              and vertically with a single line break. All lines following the first (if any) are
              indented  to  the  same left column, whose indentation is specified by the optional
              Offset parameter relative to the  position  of  the  first  element  in  Docs.  For
              example,  with an offset of -4, the following layout can be produced, for a list of
              documents representing the numbers 0 to 15:

                       0 1 2 3
                   4 5 6 7 8 9
                   10 11 12 13
                   14 15

              or with an offset of +2:

                   0 1 2 3 4 5 6
                     7 8 9 10 11
                     12 13 14 15

              The utility function text_par/2 can be used to easily transform a  string  of  text
              into a par representation by splitting it into words.

              Note that whenever a document in Docs contains a line break, it will be placed on a
              separate line. Thus, neither a layout such as

                   ab cd
                      ef

              nor

                   ab
                   cd ef

              will be generated. However, a useful idiom for making the former  variant  possible
              (when  wanted)  is  beside(par([D1, text("")], N), D2) for two documents D1 and D2.
              This will break the line between D1 and D2 if D1  contains  a  line  break  (or  if
              otherwise  necessary),  and  optionally further indent D2 by N character positions.
              The utility function follow/3 creates this context for two documents D1 and D2, and
              an optional integer N.

              See also: par/1, text_par/2.

       sep(Docs::[document()]) -> document()

              Arranges  documents  horizontally or vertically, separated by whitespace. Returns a
              document representing two alternative layouts of the (nonempty)  sequence  Docs  of
              documents, such that either all elements in Docs are concatenated horizontally, and
              separated by a  space  character,  or  all  elements  are  concatenated  vertically
              (without extra separation).

              Note:  If  some  document  in  Docs contains a line break, the vertical layout will
              always be selected.

              Examples:

                                                ab
                   ab  cd  ef  =>  ab cd ef  |  cd
                                                ef

                   ab           ab
                   cd  ef  =>   cd
                                ef

              See also: par/2.

       text(Characters::string()) -> document()

              Yields a document representing a fixed, unbreakable  sequence  of  characters.  The
              string should contain only printable characters (tabs allowed but not recommended),
              and not newline, line feed, vertical tab, etc. A tab character (\t) is  interpreted
              as  padding  of  1-8 space characters to the next column of 8 characters within the
              string.

              See also: empty/0, null_text/1, text_par/2.

       text_par(Text::string()) -> document()

              Equivalent to text_par(Text, 0).

       text_par(Text::string(), Indentation::integer()) -> document()

              Yields  a  document  representing  paragraph-formatted  plain  text.  The  optional
              Indentation  parameter  specifies  the  extra  indentation of the first line of the
              paragraph. For example, text_par("Lorem ipsum dolor sit amet", N) could represent

                   Lorem ipsum dolor
                   sit amet

              if N = 0, or

                     Lorem ipsum
                   dolor sit amet

              if N = 2, or

                   Lorem ipsum dolor
                     sit amet

              if N = -2.

              (The sign of the indentation is thus reversed compared to the par/2  function,  and
              the  behaviour varies slightly depending on the sign in order to match the expected
              layout of a paragraph of text.)

              Note that this is just a utility function, which does all the work of splitting the
              given  string  into  words  separated  by  whitespace and setting up a par with the
              proper indentation, containing a list of text elements.

              See also: par/2, text/1, text_par/1.

AUTHORS

       Richard Carlsson <carlsson.richard@gmail.com>

                                       syntax_tools 1.6.12                         prettypr(3erl)