Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Text::Format(3)	      User Contributed Perl Documentation      Text::Format(3)

NAME
       Text::Format - Various subroutines to format text.

VERSION
       version 0.62

SYNOPSIS
	   use Text::Format;

	   my $text = Text::Format->new	(
	       {
		   text		  =>  [], # all
		   columns	  =>  72, # format, paragraphs,	center
		   leftMargin	  =>   0, # format, paragraphs,	center
		   rightMargin	  =>   0, # format, paragraphs,	center
		   firstIndent	  =>   4, # format, paragraphs
		   bodyIndent	  =>   0, # format, paragraphs
		   rightFill	  =>   0, # format, paragraphs
		   rightAlign	  =>   0, # format, paragraphs
		   justify	  =>   0, # format, paragraphs
		   extraSpace	  =>   0, # format, paragraphs
		   abbrevs	  =>  {}, # format, paragraphs
		   hangingIndent  =>   0, # format, paragraphs
		   hangingText	  =>  [], # format, paragraphs
		   noBreak	  =>   0, # format, paragraphs
		   noBreakRegex	  =>  {}, # format, paragraphs
		   tabstop	  =>   8, # expand, unexpand,  center
	       }
	   ); #	these are the default values

	   my %abbr = (foo => 1, bar =>	1);
	   $text->abbrevs(\%abbr);
	   $text->abbrevs();
	   $text->abbrevs({foo => 1,bar	=> 1});
	   $text->abbrevs(qw/foo bar/);
	   $text->text(\@text);

	   $text->columns(132);
	   $text->tabstop(4);
	   $text->extraSpace(1);
	   $text->firstIndent(8);
	   $text->bodyIndent(4);
	   $text->config({tabstop => 4,firstIndent => 0});
	   $text->rightFill(0);
	   $text->rightAlign(0);

DESCRIPTION
       The format routine will format under all	circumstances even if the
       width isn't enough to contain the longest words.	 Text::Wrap will die
       under these circumstances, although I am	told this is fixed.  If
       columns is set to a small number	and words are longer than that and the
       leading 'whitespace' than there will be a single	word on	each line.
       This will let you make a	simple word list which could be	indented or
       right aligned.  There is	a chance for croaking if you try to subvert
       the module.  If you don't pass in text then the internal	text is	worked
       on, though not modified.

       Text::Format is meant for more powerful text formatting than what
       Text::Wrap allows.  I also have a module	called Text::NWrap that	is
       meant as	a direct replacement for Text::Wrap.  Text::NWrap requires
       Text::Format since it uses Text::Format-_format to do the actual
       wrapping	but gives you the interface of Text::Wrap.

       General setup should be explained with the below	graph.

				  columns
       <------------------------------------------------------------>
       <----------><------><---------------------------><----------->
	leftMargin  indent  text is formatted into here	 rightMargin

       indent is firstIndent or	bodyIndent depending on	where we are in	the
       paragraph.

       format @ARRAY ||	\@ARRAY	|| [<FILEHANDLE>] || NOTHING
	   Allows one to do some advanced formatting of	text into a paragraph,
	   with	indent for first line and body set separately.	Can specify
	   total width of text,	right fill with	spaces or right	align or
	   justify (align to both margins), right margin and left margin, non-
	   breaking space, two spaces at end of	sentence, hanging indents
	   (tagged paragraphs).	 Strips	all leading and	trailing whitespace
	   before proceeding.  Text is first split into	words and then
	   reassembled.	 If no text is passed in then the internal text	in the
	   object is formatted.

       paragraphs @ARRAY || \@ARRAY || [<FILEHANDLE>] || NOTHING
	   Considers each element of text as a paragraph and if	the indents
	   are the same	for first line and the body then the paragraphs	are
	   separated by	a single empty line otherwise they follow one under
	   the other.  If hanging indent is set	then a single empty line will
	   separate each paragraph as well.  Calls format to do	the actual
	   formatting.	If no text is passed in	then the internal text in the
	   object is formatted,	though not changed.

       center @ARRAY ||	NOTHING
	   Centers a list of strings in	@ARRAY or internal text.  Empty	lines
	   appear as, you guessed it, empty lines.  Center strips all leading
	   and trailing	whitespace before proceeding.  Left margin and right
	   margin can be set.  If no text is passed in then the	internal text
	   in the object is formatted.

       expand @ARRAY ||	NOTHING
	   Expand tabs in the list of text to tabstop number of	spaces in
	   @ARRAY or internal text.  Doesn't modify the	internal text just
	   passes back the modified text.  If no text is passed	in then	the
	   internal text in the	object is formatted.

       unexpand	@ARRAY || NOTHING
	   Tabstop number of spaces are	turned into tabs in @ARRAY or internal
	   text.  Doesn't modify the internal text just	passes back the
	   modified text.  If no text is passed	in then	the internal text in
	   the object is formatted.

       new \%HASH || NOTHING
	   Instantiates	the object.  If	you pass a reference to	a hash,	or an
	   anonymous hash then it is used in setting attributes.

       config \%HASH
	   Allows the configuration of all object attributes at	once.  Returns
	   the object prior to configuration.  You can use it to make a	clone
	   of your object before you change attributes.

       columns NUMBER || NOTHING
	   Set width of	text or	retrieve width.	 This is total width and
	   includes indentation	and the	right and left margins.

       tabstop NUMBER || NOTHING
	   Set tabstop size or retrieve	tabstop	size, only used	by expand,
	   unexpand and	center.

       firstIndent NUMBER || NOTHING
	   Set or get indent for the first line	of paragraph.  This is the
	   number of spaces to indent.

       bodyIndent NUMBER || NOTHING
	   Set or get indent for the body of paragraph.	 This is the number of
	   spaces to indent.

       leftMargin NUMBER || NOTHING
	   Set or get width of left margin.  This is the number	of spaces used
	   for the margin.

       rightMargin NUMBER || NOTHING
	   Set or get width of right margin.  This is the number of spaces
	   used	for the	margin.

       rightFill 0 || 1	|| NOTHING
	   Set right fill or retrieve its value.  The filling is done with
	   spaces.  Keep in mind that if rightAlign is also set	then both
	   rightFill and rightAlign are	ignored.

       rightAlign 0 || 1 || NOTHING
	   Set right align or retrieve its value.  Text	is aligned with	the
	   right side of the margin.  Keep in mind that	if rightFill is	also
	   set then both rightFill and rightAlign are ignored.

       justify 0 || 1 || NOTHING
	   Set justify or retrieve its value.  Text is aligned with both
	   margins, adding extra spaces	as necessary to	align text with	left
	   and right margins.  Keep in mind that if either of rightAlign or
	   rightFill are set then justify is ignored, even if both are set in
	   which case they are all ignored.

       text \@ARRAY || NOTHING
	   Pass	in a reference to your text, or	an anonymous array of text
	   that	you want the routines to manipulate.  Returns the text held in
	   the object.

       hangingIndent 0 || 1 || NOTHING
	   Use hanging indents in front	of a paragraph,	returns	current	value
	   of attribute.  This is also called a	tagged paragraph.

       hangingText \@ARRAY || NOTHING
	   The text that will be displayed in front of each paragraph, if you
	   call	format then only the first element is used, if you call
	   paragraphs then paragraphs cycles through all of them.  If you have
	   more	paragraphs than	elements in your array than the	remainder of
	   the paragraphs will not have	a hanging indented text.  Pass a
	   reference to	your array.  This is also called a tagged paragraph.

       noBreak 0 || 1 || NOTHING
	   Set whether you want	to use the non-breaking	space feature (see
	   noBreakRegex	below).

       noBreakRegex \%HASH || NOTHING
	   Pass	in a reference to a hash that would hold the regexes on	which
	   not to break. In order for this to happen, it requires noBreak to
	   be set to true - see	above.	Without	any arguments, it returns the
	   hash. E.g:

	       {'^Mrs?\.$' => '^\S+$','^\S+$' => '^(?:S|J)r\.$'}

	   don't break names such as Mr. Jones,	Mrs. Jones, Jones Jr.

	   The breaking	algorithm is simple.  If there should not be a break
	   at the current end of sentence, then	a backtrack is done till there
	   are two words on which breaking is allowed.	If no two such words
	   are found then the end of sentence is broken	anyhow.	 If there is a
	   single word on current line then no backtrack is done and the word
	   is stuck on the end.	 This is so you	can make a list	of names for
	   example.

	   Note: this feature requires noBreak to be set to true.

       extraSpace 0 || 1 || NOTHING
	   Add extra space after end of	sentence, normally format would	add 1
	   space after end of sentence,	if this	is set to 1 then 2 spaces are
	   used.  Abbreviations	are not	followed by two	spaces.	 There are a
	   few internal	abbreviations and you can add your own to the object
	   with	abbrevs

       abbrevs \%HASH || @ARRAY	|| NOTHING
	   Add to the current abbreviations, takes a reference to your hash or
	   an array of abbreviations, if called	a second time the original
	   reference is	removed	and replaced by	the new	one.  Returns the
	   current INTERNAL abbreviations.

EXAMPLE
	   use Text::Format;

	   my $text = Text::Format->new;

	   $text->rightFill(1);
	   $text->columns(65);
	   $text->tabstop(4);

	   print $text->format("a line to format to an indented	regular
		   paragraph using 65 character	wide display");
	   print $text->paragraphs("paragraph one","paragraph two");
	   print $text->center("hello world","nifty line 2");
	   print $text->expand("\t\thello world\n","hmm,\twell\n");
	   print $text->unexpand("    hello world\n","	  hmm");

	   $text->config({columns => 132, tabstop => 4});

	   $text = Text::Format->new();

	   print $text->format(@text);
	   print $text->paragraphs(@text);
	   print $text->center(@text);
	   print $text->format([<FILEHANDLE>]);
	   print $text->format([$fh->getlines()]);
	   print $text->paragraphs([<FILEHANDLE>]);
	   print $text->expand(@text);
	   print $text->unexpand(@text);

	   $text = Text::Format->new
	       ({tabstop => 4,bodyIndent => 4,text => \@text});

	   print $text->format();
	   print $text->paragraphs();
	   print $text->center();
	   print $text->expand();
	   print $text->unexpand();

	   print Text::Format->new({columns => 95})->format(@text);

BUGS
       Line length can exceed the number of specified columns if columns is
       set to a	small number and long words plus leading whitespace exceed the
       specified column	length.	 Actually I see	this as	a feature since	it can
       be used to make up a nice word list.

LICENSE
       Copyright (c) 1998 Gabor	Egressy.  All rights reserved.

       This program is free software; you can redistribute and/or modify it
       under the same terms as Perl itself.

AUTHOR
       Gabor Egressy gabor@vmunix.com

       Copyright (c) 1998 Gabor	Egressy.  All rights reserved.	All wrongs
       reversed.  This program is free software; you can redistribute and/or
       modify it under the same	terms as Perl itself.

       Adopted and modified by Shlomi Fish, <http://www.shlomifish.org/> - all
       rights disclaimed.

ACKNOWLEDGMENTS
       Tom Phoenix

       Found a bug with	code for two spaces at the end of the sentence and
       provided	a code fragment	for a better solution. Also some preliminary
       suggestions on the design.

       Brad Appleton

       Suggestion and explanation of hanging indents, suggestion for non-
       breaking	whitespace, general suggestions	with regard to interface
       design.

       Byron Brummer

       Suggestion for better interface design and object design, code for
       better implementation of	getting	abbreviations.

       H. Merijn Brand

       Suggestion for a	justify	feature	and original code for doing the
       justification.  I changed the code to take into account the extra space
       at end of sentence feature.

       Anne Wainwright

       Inspired	a documentation	clarification about noBreak required by
       noBreakRegex , thanks to	a report with a	problem.

TODO
SUPPORT
   Websites
       The following websites have more	information about this module, and may
       be of help to you. As always, in	addition to those websites please use
       your favorite search engine to discover more resources.

       o   MetaCPAN

	   A modern, open-source CPAN search engine, useful to view POD	in
	   HTML	format.

	   <https://metacpan.org/release/Text-Format>

       o   RT: CPAN's Bug Tracker

	   The RT ( Request Tracker ) website is the default bug/issue
	   tracking system for CPAN.

	   <https://rt.cpan.org/Public/Dist/Display.html?Name=Text-Format>

       o   CPANTS

	   The CPANTS is a website that	analyzes the Kwalitee (	code metrics )
	   of a	distribution.

	   <http://cpants.cpanauthors.org/dist/Text-Format>

       o   CPAN	Testers

	   The CPAN Testers is a network of smoke testers who run automated
	   tests on uploaded CPAN distributions.

	   <http://www.cpantesters.org/distro/T/Text-Format>

       o   CPAN	Testers	Matrix

	   The CPAN Testers Matrix is a	website	that provides a	visual
	   overview of the test	results	for a distribution on various
	   Perls/platforms.

	   <http://matrix.cpantesters.org/?dist=Text-Format>

       o   CPAN	Testers	Dependencies

	   The CPAN Testers Dependencies is a website that shows a chart of
	   the test results of all dependencies	for a distribution.

	   <http://deps.cpantesters.org/?module=Text::Format>

   Bugs	/ Feature Requests
       Please report any bugs or feature requests by email to "bug-text-format
       at rt.cpan.org",	or through the web interface at
       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Text-Format>. You
       will be automatically notified of any progress on the request by	the
       system.

   Source Code
       The code	is open	to the world, and available for	you to hack on.	Please
       feel free to browse it and play with it,	or whatever. If	you want to
       contribute patches, please send me a diff or prod me to pull from your
       repository :)

       <https://github.com/shlomif/perl-Module-Format>

	 git clone https://github.com/shlomif/perl-Module-Format

AUTHOR
       Shlomi Fish <shlomif@cpan.org>

BUGS
       Please report any bugs or feature requests on the bugtracker website
       <https://github.com/shlomif/perl-Module-Format/issues>

       When submitting a bug or	request, please	include	a test-file or a patch
       to an existing test-file	that illustrates the bug or desired feature.

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2020 by Gabor Egressy.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.1			  2020-10-16		       Text::Format(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | EXAMPLE | BUGS | LICENSE | AUTHOR | ACKNOWLEDGMENTS | TODO | SUPPORT | AUTHOR | BUGS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::Format&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help