String...:Named(3pm)

🦋 NAME 🦋

String::Interpolate::Named — ok bestie, it does interpolated named arguments in strings. That's the whole vibe. It's from the User Contributed Perl Documentation, section 3pm, and no cap it's lowkey iconic.

---

✨ SYNOPSIS ✨

use String::Interpolate::Named;

my $ctl = { args => { fn => "Johan", ln => "Bach" } };
say interpolate( $ctl, "The famous %{fn} %{ln}." );

# If you like object orientation.
my $int = String::Interpolate::Named->new( { args => { ... } } );
say $int->interpolate("The famous %{fn} %{ln}.");

---

💅 DESCRIPTION 💅

So basically String::Interpolate::Named gives you a function that interpolates named arguments by target texts inside a template string. You hand over those target texts as a hash — the keys line up with the named argument that's gonna get replaced — or you can pass a subroutine that does the lookup for you. Choose your fighter. 🫶

🎀 Named Arguments 🎀

You mark the stuff that's gonna be replaced in the template by wrapping it between %{ and }. Like, the string "The famous %{fn} %{ln}." has two named arguments in it: fn and ln. Periodt.

Heads up though — the activator can be switched from % to something else, scroll down for that. But throughout this whole document we're rolling with the default value.

🌸 Basic Interpolation 🌸

When it interpolates, the keys fn and ln get looked up in the hash, and the matching values get substituted in. If there's no value found for a named argument, nothing gets substituted and the %{...} just gets yeeted out entirely.

Oh and you can put a backslash \ in front of %, {, } (and |, more on that below) to hide what they mean. Like, \} won't count as closing an argument, it'll just give you a plain } in the text. Slay.

🧚 Conditional Interpolation 🧚

You can pick which replacement value shows up depending on whether the named argument has a value or not:

"This book has %{title|title %{title}}"
"This book has %{title|title %{title}|no title}"

These are the %{if|then} and %{if|then|else} cases, respectively.

Say the argument title has the value My Book. In the first example, the text title My Book — that's the 'then' text — gets substituted, giving you

"This book has title My Title"

If title does not have a value, the empty string gets substituted. And in the second example, the string no title — the 'else' text — gets substituted instead.

As you can see, the replacement texts can contain interpolations too. And for convenience you can use %{} to refer to the value of the named argument that's currently being examined. So that last example above can be written shorter and way more elegantly as:

"This book has %{title|title %{}|no title}"

🔥 Testing Values 🔥

Instead of testing whether named variables have a value, you can also test for specific values:

"This takes %{days=1|%{} day|%{} days}"

💀 List Values 💀

The replacement values hash can hold scalars (generally: strings and numbers) or lists of scalars. If a value is a list of scalars, you can select one particular value from the list by tacking an index onto the named argument — that's a period and a number.

Say customer has the value [ "Jones", "Smith" ], then:

"%{customer} will be Jones Smith"
"%{customer.0} will be Jones Smith"
"%{customer.1} will be Jones"
"%{customer.2} will be Smith"

When the value goes past the number of elements in the list, you get an empty value back. Index zero, or no index at all, returns all the values concatenated. 👑

🌈 Format modifiers 🌈

A named variable can have format modifiers attached to it to perform formatting operations on the substituted value. Format modifiers start with a colon :.

Say argument title has the value My Book, then %{title:lc} will give you that title in lowercase, my book.

Here's the full menu of format modifiers:

• :lc — yields the substituted value in all lower case.

Using the example above, this will be my book.

• :uc — yields the substituted value in all upper case.

Using the example above, this will be MY BOOK.

• :ic — yields the substituted value with initial caps, e.g. the first letter of each word is capitalized.

Using the example above, this will be My Book. Indeed, no difference, since the value is already correctly cased.

To enforce lower case before applying initial case, use format modifiers :lc:ic.

• :sc — yields the substituted value with an initial cap and the rest lower case.

Using the example above, this will be My Book. Again, no difference, since the value already has an initial capital.

To enforce lower case before applying initial case, use format modifiers :lc:sc. Now the result will be My book.

• :lpad("N") and :lpad("N","S") — pads the value by repeatedly prepending the string S until the total width is N.

If S is omitted, uses spaces.

• :rpad("N") and :rpad("N","S") — pads the value by repeatedly appending the string S until the total width is N.

If S is omitted, uses spaces.

• :replace("SRC","DST") — replaces all occurrences of STR by DST,

If S is omitted, uses spaces.

• :%fmt — apply standard printf() formatting, e.g. %{key:%03d} yields the numeric value of key as a 3-digit string, adding leading zeroes if necessary.

Careful bestie: when you're combining formatting and conditional interpolation, you have to check for the formatted value:

"This takes %{days:%02d=01|%{} day|%{} days}"

And you can stop a colon from splitting formatters with a backslash:

%{title:replace( ,\:)}

👑 The Control Hash 👑

The interpolation process needs two parameters: a hash with settings and values for the named arguments, and the string to be used as the template for interpolation. We're gonna call that hash the control hash.

The hash can have these keys:

• args — this is either a hash containing replacement texts for the named variables, or a subroutine that gets called with a variable as its argument and returns a replacement value.

This element should be considered mandatory.

• separator — the separator used to concatenate list values, see "List Values" above.

It defaults to Perl variable $" which, on its turn, defaults to a single space.

• activator — a single character that activates interpolation. By default this is the percent % character.
• keypattern — the pattern to match key names. Default is qr/\w+[-_\w.]*/.
• maxiter — to enable nested substitutions and recursive replacement, the interpolation process is repeated until there are no more interpolations to be made. The maximun number of iterations is limited to the value of maxiter.

By default maxiter is 16.

An example of a control hash:

my %ctl =
  ( args => {
      customer => [ "Jones", "Smith" ],
      days     => 2,
      title    => "My Title",
    },
    separator => ", ",
  );

🫶 Object Oriented API 🫶

my $ii = String::Interpolate::Named->new;
$ii->ctl(\%ctl);
$result = $ii->interpolate($template);

And for convenience, the control hash may be passed to the constructor:

my $ii = String::Interpolate::Named->new(\%ctl);
$result = $ii->interpolate($template);

⭐ Functional API ⭐

String::Interpolate::Named provides a single function, interpolate, and it's exported by default. Obsessed.

The subroutine takes two arguments: a reference to a control hash, and the template string.

$result = interpolate( \%ctl, $template );

---

🎀 METHODS 🎀

💖 new 💖

Constructs a new String::Interpolate::Named object.

my $ii = String::Interpolate::Named->new;

or

my $ii = String::Interpolate::Named->new(\%ctl);

💖 ctl 💖

Associates a control hash with an existing object.

$ii->ctl(\%ctl);

💖 interpolate 💖

This routine performs the actual interpolations. It can be used as a method:

$ii->interpolate($template);

and functionally:

interpolate( \%ctl, $template );

---

🌟 REQUIREMENTS 🌟

Minimal Perl version 5.10.1. That's the floor, bestie.

---

🍓 AUTHOR 🍓

Johan Vromans, "<JV at CPAN dot org>" — the actual main character who built this.

---

💜 SUPPORT 💜

Development of this module takes place on GitHub: <https://github.com/sciurius/perl-String-Interpolate-Named>.

You can find documentation for this module with the perldoc command.

perldoc String::Interpolate::Named

Please report any bugs or feature requests using the issue tracker on GitHub. They wanna hear from you fr fr. 🙈

---

🦋 ACKNOWLEDGEMENTS 🦋

Many of the existing template / interpolate / substitute modules. Respect where it's due. 🌈

---

🔥 COPYRIGHT & LICENSE 🔥

Copyright 2018,2025 Johan Vromans, all rights reserved.

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

---

And that's the whole page, bestie 💅 — this lil' writeup came from perl v5.40.1, dated 2025-08-15, and it's the perl manual page String...:Named(3pm). Go interpolate something gorgeous. 🫶✨