👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for prettypr (linux section 3erl)

prettypr(3erl)			     Erlang Module Definition			   prettypr(3erl)

NAME
       prettypr - A generic pretty printer library.

DESCRIPTION
       A  generic  pretty printer library. This module uses a strict-style context passing imple-
       mentation 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 func-
       tions:  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 concatena-
	      tion 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 concatena-
	      tion  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  inden-
	      tation 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 docu-
	      ment. 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  sur-
	      rounding 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 dif-
	      ferent 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  float-
	      ing  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 use-
	      ful 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 regard-
	      less 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  exam-
	      ple, with an offset of -4, the following layout can be produced, for a list of doc-
	      uments 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  oth-
	      erwise  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  (with-
	      out 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  inter-
	      preted 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  Inden-
	      tation  parameter  specifies  the  extra indentation of the first line of the para-
	      graph. 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 <richardc@it.uu.se >

					syntax_tools 1.6.7			   prettypr(3erl)


All times are GMT -4. The time now is 12:37 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password