IntlFormatList

A module for formatting lists in a localized manner

To format lists using this module, use the provided sub C:

format-list @list

There are three named options available:

• :language (may be abbreviated to :lang)The language to use for formatting. Should be a valid BCP-47 language code. Defaults to whatever value Intl::UserLanguage's user-language returns (which defaults to 'en' if undetectable).

• :typeThere are three types possible: and, or, unit. The and type indicates a list of collective values (e.g. 'apples, oranges, and peaches'). The or type indicates a list of alternate values (e.g. 'apples, oranges, or peaches'). The unit type indicates a list of values, without specifying any relation between them (e.g. 'apples, oranges, peaches'). Defaults to and.

• :lengthThere are three lengths possible: standard, short, narrow. Many languages do not distinguish standard and short, perhaps only omitting spaces if they do. In contrast, narrow is designed for minimal contexts, but may be ambiguous between the forms and should have additional context provided if used. Defaults to standard.

Examples

If your language is set to English…

my @list = <apples oranges bananas>;
say format-list @list;              # 'apples, oranges, and bananas'
say format-list @list, :type<or>;   # 'apples, oranges, or bananas'
say format-list @list, :type<unit>; # 'apples, oranges, bananas'

But if your language is set to Spanish…

my $a = 'manzanas';
my $o = 'naranjas';
my $b = 'plátanos';
say format-list $a, $o, $b;            # 'manzanas, naranjas y plátanos'
say format-list $a, $o, $b, :type<or>; # 'manzanas, naranjas o plátanos'
say format-list $a, $o, $b, :type<unit; # 'manzanas, naranjas y plátanos'

As you can tell, the format-list sub follows the single-argument rule, allowing either a list proper or an inline list of items. All items passed in are stringified.

For developers

If you want to integrate the list formatter via RakuAST, you can obtain a Callable (currently a RakuAST::PointyBlock) by the following:

use Intl::Format::List :rakuast;
my $formatter-ast = format-list-rakuast('en', 'and', 'standard')

Presently, all three parameters (language, type, length) must be specified.

Version history

• v0.6.0

  • Added an improved caching mechanism

  • RakuAST support (autodetects based on compiler version)

• v0.5.0

  • First release as its own module

  • Much cleaner / more maintainable codebase

• v0.1 – v0.4.3

  • Initial release as a part of the Intl::CLDR module

  • No changes made after initial release

License and Copyright

© 2020–2022 Matthew Stephen Stuckwisch. Licensed under Artistic License 2.0