String::Formatter::Cookbook(3) User Contributed Perl Documentation String::Formatter::Cookbook(3)

# [OVERVIEW](#OVERVIEW)

String::Formatter is a pretty simple system for building formatting routines, but it can be hard to get started without an idea of the sort of things that are possible.

# [BASIC RECIPES](#BASIC_RECIPES)

## [constants only](#constants_only)

The simplest stringf interface you can provide is one that just formats constant strings, allowing the user to put them inside other fixed strings with alignment:

```
  use String::Formatter stringf => {
    input_processor => 'forbid_input',
    codes => {
      a => 'apples',
      b => 'bananas',
      w => 'watermelon',
    },
  };
  print stringf('I eat %a and %b but never %w.');
  # Output:
  # I eat apples and bananas but never watermelon.
```

If the user tries to parameterize the string by passing arguments after the format string, an exception will be raised.

## [sprintf-like conversions](#sprintf)

Another common pattern is to create a routine that behaves like Perl's "sprintf", but with a different set of conversion routines. (It will also almost certainly have much simpler semantics than Perl's wildly complex behavior.)

```
  use String::Formatter stringf => {
    codes => {
      s => sub { $_ },     # string itself
      l => sub { length }, # length of input string
      e => sub { /[^\x00-\x7F]/ ? '8bit' : '7bit' }, # ascii-safeness
    },
  };
  print stringf(
    "My name is %s.  I am about %l feet tall.  I use an %e alphabet.\n",
    'Ricardo',
    'ffffff',
    'abcchdefghijklllmnñopqrrrstuvwxyz',
  );
  # Output:
  # My name is Ricardo.  I am about 6 feet tall.  I use an 8bit alphabet.
```

**Warning**: The behavior of positional string replacement when the conversion codes mix constant strings and code references is currently poorly nailed-down. Do not rely on it yet.

## [named conversions](#named_conversions)

This recipe acts a bit like Python's format operator when given a dictionary. Rather than matching format code position with input ordering, inputs can be chosen by name.

```
  use String::Formatter stringf => {
    input_processor => 'require_named_input',
    string_replacer => 'named_replace',
    codes => {
      s => sub { $_ },     # string itself
      l => sub { length }, # length of input string
      e => sub { /[^\x00-\x7F]/ ? '8bit' : '7bit' }, # ascii-safeness
    },
  };
  print stringf(
    "My %{which}s name is %{name}s.  My name is %{name}l letters long.",
    {
      which => 'first',
      name  => 'Marvin',
    },
  );
  # Output:
  # My first name is Marvin.  My name is 6 letters long.
```

Because this is a useful recipe, there is a shorthand for it:

```
  use String::Formatter named_stringf => {
    codes => {
      s => sub { $_ },     # string itself
      l => sub { length }, # length of input string
      e => sub { /[^\x00-\x7F]/ ? '8bit' : '7bit' }, # ascii-safeness
    },
  };
```

## [method calls](#method_calls)

Some objects provide methods to stringify them flexibly. For example, many objects that represent timestamps allow you to call "strftime" or something similar. The "method\_replace" string replacer comes in handy here:

```
  use String::Formatter stringf => {
    input_processor => 'require_single_input',
    string_replacer => 'method_replace',
    codes => {
      f => 'strftime',
      c => 'format_cldr',
      s => sub { "$_[0]" },
    },
  };
  print stringf(
    "%{%Y-%m-%d}f is also %{yyyy-MM-dd}c.  Default string is %s.",
    DateTime->now,
  );
  # Output:
  # 2009-11-17 is also 2009-11-17.  Default string is 2009-11-17T15:35:11.
```

This recipe is available as the export "method\_stringf":

```
  use String::Formatter method_stringf => {
    codes => {
      f => 'strftime',
      c => 'format_cldr',
      s => sub { "$_[0]" },
    },
  };
```

You can easily use this to implement an actual stringf-like method:

```
  package MyClass;
  use String::Formatter method_stringf => {
    -as => '_stringf',
    codes => {
      f => 'strftime',
      c => 'format_cldr',
      s => sub { "$_[0]" },
    },
  };
  sub format {
    my ($self, $format) = @_;
    return _stringf($format, $self);
  }
```

2026-10-25 perl v5.44.0

---

Document: String::Formatter::Cookbook(3pm) from perl-string-formatter 1.235-r4 (Chainguard OS)
Source: https://github.com/rjbs/String-Formatter