pretty_print

Definition: include builtins\pretty.e -- (also included by builtins\misc.e)

pretty_print(integer fn, object x, sequence options = PRETTY_DEFAULT)
-- or --
string o = pretty_sprint(object x, sequence options = PRETTY_DEFAULT)

Description: Print an object to a file or device, using braces { , , , }, indentation, and multiple lines to show the structure.

pwa/p2js: Not supported, see ppp instead.

Comments:

Note that Pete’s Pretty Print was written to address many of the percieved limitations of this routine and is recommended for all new code, rather than this, and/or convert to using that routine rather than waste time trying to fix any problems that might arise with this one.

fn: an integer, the file/device number to write to.
x: the object to display/convert to printable form.
options: a sequence of up to length 10, with the following defaults and meanings:

Element	Default	Meaning
DISPLAY_ASCII (1)	1	display ASCII characters: 0 -- never 1 -- alongside any integers in printable ASCII range (default) 2 -- display as "string" when all integers of a sequence are in ASCII range 3 -- show strings, and quoted characters (only) for any integers in ASCII range as well as the characters: \t \r \n
INDENTATION (2)	2	amount to indent for each level of sequence nesting (was INDENT in Euphoria, but that clashed with eaundo.ew)
START_COLUMN (3)	1	column we are starting at
WRAP (4)	78	approximate column to wrap at
INT_FORMAT (5)	"%d"	format to use for integers
FP_FORMAT (6)	"%.10g"	format to use for floating-point numbers
MIN_ASCII (7)	32	The smallest printable ascii character. Defaults to 32 (space).
MAX_ASCII (8)	126+W	The largest printable asciii character. Defaults to 126 (#7E) on Linux, 127 (#7F) on Windows.
MAX_LINES (9)	1000000000	maximum number of lines to output
LINE_BREAKS (10)	1	line breaks between elements: 1 = default (yes) 0 = no line breaks -1 = line breaks to wrap only

Pass {} in options to select all the defaults. If the length is less than 10, unspecified options at the end of the sequence will keep the default values, for example {0, 5} will choose "never display ASCII" plus 5-character indentation, with defaults for everything else.

The display will start at the current cursor position. Normally you will want to call pretty_print() when the cursor is in column 1 (after printing a \n character).

If you want to start in a different column, you should call position() and specify a value for option [3]. This will ensure that the first and last braces in a sequence line up vertically.

When specifying the format to use for integers and floating-point numbers, you can add some decoration, e.g. "(%d)" or "$ %.2f"

The pretty_sprint() function formats outputs the same as pretty_print(), but returns the sequence obtained instead of sending it to some file.

As this is a simple compatibility shim for Euphoria, the constants DISPLAY_ASCII..LINE_BREAKS and PRETTY_DEFAULT are declared in builtins\pretty.e, rather than psym.e, and cannot be used before the include statement.

The file builtins\pretty.e is included by builtins\misc.e, for legacy code that expects it is (still) declared in that file.

Example 1:

pretty_print(1, "ABC", {})   
-- {65'A',66'B',67'C'}

Example 2:

pretty_print(1, {{1,2,3}, {4,5,6}}, {}) 
-- {
--   {1,2,3},
--   {4,5,6}
-- }

Example 3:

pretty_print(1, {"Euphoria", "Programming", "Language"}, {2})  
-- {
--   "Euphoria",
--   "Programming",
--   "Language"
-- }

Example 4:

puts(1, "word_list = ") -- moves cursor to column 13
pretty_print(1, {{"Euphoria", 8, 5.3}, 
                 {"Programming", 11, -2.9}, 
                 {"Language", 8, 9.8}}, 
                {2, 4, 13, 78, "%03d", "%.3f"}) -- first 6 of 8 options
-- word_list = {
--     {
--         "Euphoria",
--         008,
--         5.300
--     },
--     {
--         "Programming",
--         011,
--         -2.900
--     },
--     {
--         "Language",
--         008,
--         9.800
--     }
-- }

See Also: print, sprint, printf, sprintf, ppp