.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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 turned on, 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MakeMethods::Utility::TextBuilder 3pm"
.TH MakeMethods::Utility::TextBuilder 3pm "2016-06-10" "perl v5.22.2" "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"
Class::MakeMethods::Utility::TextBuilder \- Basic text substitutions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& print text_builder( $base_text, @exprs )
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a single function, which implements a simple \*(L"text macro\*(R" mechanism for assembling templated text strings.
.PP
.Vb 1
\&  $expanded_text = text_builder( $base_text, @exprs )
.Ve
.PP
Returns a modified copy of \f(CW$base_text\fR using rules from the \f(CW@exprs\fR list.
.PP
The \f(CW@exprs\fR list may contain any of the following:
.IP "\(bu" 4
A string, in which any '*' characters will be replaced by the base text. The interpolated string then replaces the base text.
.IP "\(bu" 4
A code-ref, which will be called with the base text as its only argument. The result of that call then replaces the base text.
.IP "\(bu" 4
A hash-ref, which will be added to the substitution hash used in the second pass, below.
.IP "\(bu" 4
An array-ref, containing additional expressions to be treated as above.
.PP
After any initial string and code-ref rules have been applied, the hash of substitution rules are applied.
.PP
The text will be searched for occurrences of the keys of the substitution hash, which will be modified based on the corresponding value in the hash. If the substitution key ends with '{}', the search will also match a balanced block of braces, and that value will also be used in the substitution.
.PP
The hash-ref may contain the following types of rules:
.IP "\(bu" 4
\&'string' => 'string'
.Sp
Occurrences of the first string are to be replaced by the second.
.IP "\(bu" 4
\&'string' => \fIcode_ref\fR
.Sp
Occurrences of the string are to be replaced by the results of calling the subroutine with no arguments.
.IP "\(bu" 4
\&'string{}' => 'string'
.Sp
Occurrences of the first string and subsequent block of braces are replaced by a copy of the second string in which any '*' characters have first been replaced by the contents of the brace block.
.IP "\(bu" 4
\&'string{}' => \fIcode_ref\fR
.Sp
Occurrences of the string and subsequent block of braces are replaced by the results of calling the subroutine with the contents of the brace block as its only argument.
.IP "\(bu" 4
\&'string{}' => \fIhash_ref\fR
.Sp
Occurrences of the string and subsequent block of braces are replaced by using the contents of the brace block as a key into the provided hash-ref.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
The following text and modification rules provides a skeleton for a collection letter:
.PP
.Vb 2
\&  my $letter = "You owe us AMOUNT. Please pay up!\en\en" . 
\&                  "THREAT{SEVERITY}";
\&  
\&  my @exprs = (
\&    "Dear NAMEm\en\en*",
\&    "*\en\en\-\- The Management",
\&    
\&    { \*(AqTHREAT{}\*(Aq => { \*(Aqgood\*(Aq=>\*(AqPlease?\*(Aq, \*(Aqbad\*(Aq=>\*(AqOr else!\*(Aq } },
\&    
\&    "\et\et\et\etDATE\en*",
\&    { \*(AqDATE\*(Aq => \*(AqTuesday, April 1, 2001\*(Aq },
\&  );
.Ve
.PP
One might invoke this template by providing additional data for a given instance and calling the text_builder function:
.PP
.Vb 1
\&  my $item = { \*(AqNAME\*(Aq=>\*(AqJohn\*(Aq, \*(AqAMOUNT\*(Aq=>\*(Aq200 camels\*(Aq, \*(AqSEVERITY\*(Aq=>\*(Aqbad\*(Aq };
\&  
\&  print text_builder( $letter, @exprs, $item );
.Ve
.PP
The resulting output is shown below:
.PP
.Vb 2
\&                                  Tuesday, April 1, 2001
\&  Dear John,
\&  
\&  You owe us 200 camels. Please pay up!
\&  
\&  Or else!
\&  
\&  \-\- The Management
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See Class::MakeMethods for general information about this distribution.