.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Format 3pm" .TH Format 3pm "2018-03-10" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" String::Format \- sprintf\-like string formatting capabilities with arbitrary format definitions .SH "ABSTRACT" .IX Header "ABSTRACT" String::Format allows for sprintf-style formatting capabilities with arbitrary format definitions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use String::Format; \& \& my %fruit = ( \& \*(Aqa\*(Aq => "apples", \& \*(Aqb\*(Aq => "bannanas", \& \*(Aqg\*(Aq => "grapefruits", \& \*(Aqm\*(Aq => "melons", \& \*(Aqw\*(Aq => "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. .Ve .SH "DESCRIPTION" .IX Header "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 ). .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "stringf" .IX Subsection "stringf" String::Format exports a single function called stringf. stringf takes two arguments: a format string (see \s-1FORMAT STRINGS,\s0 below) and a reference to a hash of name => value pairs. These name => value pairs are what will be expanded in the format string. .SH "FORMAT STRINGS" .IX Header "FORMAT STRINGS" Format strings must match the following regular expression: .PP .Vb 8 \& qr/ \& (% # leading \*(Aq%\*(Aq \& (\-)? # left\-align, rather than right \& (\ed*)? # (optional) minimum field width \& (?:\e.(\ed*))? # (optional) maximum field width \& ({.*?})? # (optional) stuff inside \& (\eS) # actual format character \& )/x; .Ve .PP If the escape character specified does not exist in \f(CW%args\fR, then the original string is used. The alignment, minimum width, and maximum width options function identically to how they are defined in \&\fIsprintf\fR\|(3) (any variation is a bug, and should be reported). .PP 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). .PP 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 \f(CW$_\fR[0] to the subroutine reference. This allows for entries such as this: .PP .Vb 3 \& %args = ( \& d => sub { POSIX::strftime($_[0], localtime) }, \& ); .Ve .PP Which can be invoked with this format string: .PP .Vb 1 \& "It is %{%M:%S}d right now, on %{%A, %B %e}d." .Ve .PP And result in (for example): .PP .Vb 1 \& It is 17:45 right now, on Monday, February 4. .Ve .PP 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: .PP .Vb 1 \& "It is %{%M:%S right now, on %A, %B %e}d." .Ve .PP 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: .PP .Vb 1 \& "It is %{%M:%S right now, on %A, %B %e}d.%n" .Ve .PP Because of how the string is parsed, the normal \*(L"\en\*(R" and \*(L"\et\*(R" are turned into two characters each, and are not treated as a newline and tab. This is a bug. .SH "FACTORY METHOD" .IX Header "FACTORY METHOD" String::Format also supports a class method, named \fBstringfactory\fR, which will return reference to a \*(L"primed\*(R" subroutine. stringfatory should be passed a reference to a hash of value; the returned subroutine will use these values as the \f(CW%args\fR hash. .PP .Vb 8 \& my $self = Some::Groovy::Package\->new($$, $<, $^T); \& my %formats = ( \& \*(Aqi\*(Aq => sub { $self\->id }, \& \*(Aqd\*(Aq => sub { $self\->date }, \& \*(Aqs\*(Aq => sub { $self\->subject }, \& \*(Aqb\*(Aq => sub { $self\->body }, \& ); \& my $index_format = String::Format\->stringfactory(\e%formats); \& \& print $index_format\->($format1); \& print $index_format\->($format2); .Ve .PP This subroutine reference can be assigned to a local symbol table entry, and called normally, of course: .PP .Vb 1 \& *reformat = String::Format\->stringfactory(\e%formats); \& \& my $reformed = reformat($format_string); .Ve .SH "LICENSE" .IX Header "LICENSE" \&\f(CW\*(C`String::Format\*(C'\fR is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; version 2. .SH "AUTHOR" .IX Header "AUTHOR" darren chamberlain