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

FreeBSD Manual Pages

  
 
  

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

NAME
       String::Format -	sprintf-like string formatting capabilities with
       arbitrary format	definitions

ABSTRACT
       String::Format allows for sprintf-style formatting capabilities with
       arbitrary format	definitions

SYNOPSIS
	 use String::Format;

	 my %fruit = (
	       'a' => "apples",
	       'b' => "bannanas",
	       'g' => "grapefruits",
	       'm' => "melons",
	       'w' => "watermelons",
	 );

	 my $format = "I like %a, %b, and %g, but not %m or %w.";

	 print stringf($format,	%fruit);

	 # prints:
	 # I like apples, bannanas, and	grapefruits, but not melons or watermelons.

DESCRIPTION
       String::Format lets you define arbitrary	printf-like format sequences
       to be expanded.	This module would be most useful in configuration
       files and reporting tools, where	the results of a query need to be
       formatted in a particular way.  It was inspired by mutt's index_format
       and related directives (see
       <URL:http://www.mutt.org/doc/manual/manual-6.html#index_format>).

FUNCTIONS
   stringf
       String::Format exports a	single function	called stringf.	 stringf takes
       two arguments:  a format	string (see FORMAT STRINGS, below) and a
       reference to a hash of name => value pairs.  These name => value	pairs
       are what	will be	expanded in the	format string.

FORMAT STRINGS
       Format strings must match the following regular expression:

	 qr/
	    (%		   # leading '%'
	     (-)?	   # left-align, rather	than right
	     (\d*)?	   # (optional)	minimum	field width
	     (?:\.(\d*))?  # (optional)	maximum	field width
	     ({.*?})?	   # (optional)	stuff inside
	     (\S)	   # actual format character
	    )/x;

       If the escape character specified does not exist	in %args, then the
       original	string is used.	 The alignment,	minimum	width, and maximum
       width options function identically to how they are defined in
       sprintf(3) (any variation is a bug, and should be reported).

       Note that Perl's	sprintf	definition is a	little more liberal than the
       above regex; the	deviations were	intentional, and all deal with numeric
       formatting (the #, 0, and + leaders were	specifically left out).

       The value attached to the key can be a scalar value or a	subroutine
       reference; if it	is a subroutine	reference, then	anything between the
       '{' and '}' ($5 in the above regex) will	be passed as $_[0] to the
       subroutine reference.  This allows for entries such as this:

	 %args = (
	     d => sub {	POSIX::strftime($_[0], localtime) },
	 );

       Which can be invoked with this format string:

	 "It is	%{%M:%S}d right	now, on	%{%A, %B %e}d."

       And result in (for example):

	 It is 17:45 right now,	on Monday, February 4.

       Note that since the string is passed unmolested to the subroutine
       reference, and strftime would Do	The Right Thing	with this data,	the
       above format string could be written as:

	 "It is	%{%M:%S	right now, on %A, %B %e}d."

       By default, the formats 'n', 't', and '%' are defined to	be a newline,
       tab, and	'%', respectively, if they are not already defined in the
       hashref of arguments that gets passed it.  So we	can add	carriage
       returns simply:

	 "It is	%{%M:%S	right now, on %A, %B %e}d.%n"

       Because of how the string is parsed, the	normal "\n" and	"\t" are
       turned into two characters each,	and are	not treated as a newline and
       tab.  This is a bug.

FACTORY	METHOD
       String::Format also supports a class method, named stringfactory, which
       will return reference to	a "primed" subroutine.	stringfatory should be
       passed a	reference to a hash of value; the returned subroutine will use
       these values as the %args hash.

	 my $self = Some::Groovy::Package->new($$, $<, $^T);
	 my %formats = (
	       'i' => sub { $self->id	   },
	       'd' => sub { $self->date	   },
	       's' => sub { $self->subject },
	       'b' => sub { $self->body	   },
	 );
	 my $index_format = String::Format->stringfactory(\%formats);

	 print $index_format->($format1);
	 print $index_format->($format2);

       This subroutine reference can be	assigned to a local symbol table
       entry, and called normally, of course:

	 *reformat = String::Format->stringfactory(\%formats);

	 my $reformed =	reformat($format_string);

LICENSE
       "String::Format"	is free	software; you can redistribute it and/or
       modify it under the terms of the	GNU General Public License as
       published by the	Free Software Foundation; version 2.

AUTHOR
       darren chamberlain <darren@cpan.org>

perl v5.24.1			  2012-12-05			     Format(3)

NAME | ABSTRACT | SYNOPSIS | DESCRIPTION | FUNCTIONS | FORMAT STRINGS | FACTORY METHOD | LICENSE | AUTHOR

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

home | help