NAME

Data::NeatFormat - neatly present arbitrary scalar and scalar list

SYNOPSIS

  use Data::NeatFormat;
  use File::Operations;
  # show first 80 characters of the user plan
  print format_scalar(load_file("$ENV{HOME}/.plan"), 80), "\n";
  # show the name and first 60 chars of at most 10 non-hidden files
  set_neat_scalar_options({breaks => 0});  # mark TAB and CR/LF as a plus
  print format_scalar_list([
    map { "$_: " . load_file($_) } glob("*")
  ], 60, 10, "\n"), "\n";
  # a different way to specify options
  use Data::NeatFormat { quotes => 0, breaks => 0, ellipsis => '..' };
  print format_scalar({ quotes => 3 }, rand, 8), "\n";

DESCRIPTION

Functions in this module are useful for debugging, when working with large scalar lists. By default all 3 functions are exported to the calling package.

FUNCTIONS

format_scalar

usage
  format_scalar($value, $max_len);
description
Returns a string containing a neat (and tidy) representation of the supplied value. Maximal scalar length returned can be specified as a parameter, default is 40.

See set_neat_scalar_options to find how global package options affect this function. By default, numbers are not quoted, other scalars quotes. TAB and CR/LF are not replaced with a plus by default, but may be. Non-printable chars replaced with a dot.

If the value is a ref and has overloaded stringify method, then it is used. Similarly, if it has as_string method, this method is called to find the ref's string presentation. If the value is an array, it is processed using format_scalar_list.

parameters
  * optional hashref of options replacing the global ones
  * supplied value (scalar)
  * optional max length (number, default: 40)
returns
Formated string.

format_scalar_list

usage
  format_scalar_list($value, $max_len, $max_num, $delim);
description
Returns a string containing a neat (and tidy) representation of the supplied list of values. The limit on a number of values used in the representation can be given as parameter (default is 20). All values in the limited list are formatted by format_scalar function.

If there are more values in the list than the specified limit, then a certain amount of the first and the last values are used with the central element in form '...[+len]...', where len is a number of skipped values. The number of skipped values (if any) is always greater than 1.

If fourth parameter (delimiter) is empty arrayref, then list of the used value scalars is returned, otherwise they are joined to one string using the supplied value delimiter (default is ', ').

parameters
  * optional hashref of options replacing the global ones
  * supplied values (array ref of scalars)
  * max length (number, optional)
  * limit of used values (number, optional)
  * value delimiter used in scalar context (string or array ref, optional)
returns
Formated string.

set_neat_scalar_options

usage
  # restore the defaults
  set_neat_scalar_options({});
description
Sets 5 options (``breaks'', ``quotes'', ``quote1'', ``quote2'', ``ellipsis''), that affect behaviour of format_scalar and format_scalar_list.

If breaks option value is 0, then TAB and CR/LF characters in the strings will be replaced with '+' (any other character with ASCII code [0 .. 31] replaced by a dot anyway), if 1 - they remain as is in the strings (default).

If quotes option value is 0, then the scalars are never enclosed in quotes, 1 - only for non-numbers and non-refs, 2 - only for non-numbers, 3 - always enclosed in quotes (except for undefined values).

quote1 and quote2 options set the start and end quote characters (may be multiple), they default to a single quote.

parameters
  * hashref of named options to set
returns
Old hashref of options.