Unix/Linux Go Back    


CentOS 7.0 - man page for string::format (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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.16.3				    2009-05-17					Format(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:31 PM.