Bracket Notation Cheat Sheet

Bracket notation is like a tiny template. It is not as terse as sprintf and not as flexible as Template::Toolkit. You can learn more about bracket notation here.

Essential Information

The essential information that you will need to know when working with locales and bracket notation is as follows:

• Areas inside of square brackets ( []) are dynamic.
• Inside of brackets, you can reference arguments with their position, starting at 1, preceded by an underscore ( _). For example:

  •  maketext('Hello [_1], I am [_2], $your_name, $myname)

• You can refer to all arguments with an underscore ( _) followed by an asterisk ( *). For example: _*
• You can use the arguments as many times as you like in any order. For example:

  • [_2], [_1] seeks [_2]

• You can also use methods to operate on a given argument or value. For example:

  • There are [numf,_1] stars in the galaxy.

• Method arguments do not have to reference any arguments. For example:

  • Do [output,strong,NOT] go in there!

• Method arguments are comma-separated and will include any leading or trailing whitespace. For example:
  • Correct:

    [quant_1,file,files,No files] matched your query.

  • Incorrect:

    [quant_1 ,file ,files ,No files ] matched your query.

• You can include literal square brackets ( []) by escaping them with a tilde ( ~). For example:
  • 'This is a left bracket: ~[' renders as 'This is a left bracket: [.
  • 'This is a right bracket: ~]' renders as 'This is a right bracket: ]'
• You can have literal commas inside bracket notation by escaping them with a tilde ( ~). For example:

  • [method,arg1,arg~,2,arg3]

• Bracket notation cannot be nested.

Bracket Notation Methods

Bracket notation methods provide a way for various locales to handle specific data. The core bracket notation methods can be found at CPAN.

• quant — Quantifies a noun. For example:

  • [quant,_1,singular,plural]

  • [quant,_1,file,files] matched your query.

  • [quant,_1,singular,plural,zero/negative]

  • [quant,_1,file,files,No files] matched your query.

• numerate — Numerates a noun. It is similar to quant, but without the number prefixing or zeroth form optional argument used by quant. This allows, for example:

  • maketext('[numf,_1] submitted [numerate,_1,word is,words are] incorrect.',1);

    to render

    1 submitted word is incorrect.

    rather than the 1 submitted 1 word is incorrect. you would see if you used quant instead.

  • maketext('[numf,_1] submitted [numerate,_1,word is,words are] incorrect.',42);

    to render

    42 submitted words are incorrect.

    rather than the 42 submitted 42 words are incorrect. you would see if you used quant instead.
• numf — Formats a number. For example:

  • [numf,_1]

• sprintf — The same as sprintf().

  • [sprintf,%s is %d,_1,_2]

Additional methods can be found in this ::Utils module.

• join — Joins a list of items with a given separator. For example:
  • [join,-,_*]
• list — Creates an and/or list phrase. For example:

  • You chose [list,and,_*].

  • You chose A.

  • You chose A and B.

  • You chose A, B, and C.

  • You chose A, B, C, and D.

• boolean — Alternative text, based on boolean state.

  • [boolean,_1,true,false]

  • [boolean,_1,true,false,undefined]

• output — Formats text for output that is UI-agnostic. For example:

  • [output,format,_1]

  • Do [output,strong,NOT] go in there!

  • Your domain [output,class,_1,highlight] has been set up.

  • I [output,chr,60]3 ascii art!

  • Notes:
    • The url() function also takes arbitrary options in key/value pairs that become attributes in the a HTML tag.
    • The URL should be an argument, so that a URL change will not result in the key changing. For example:
      • Correct:

        maketext('Visit [output,url,_1,cPanel] today.', 'http://cpanel.net');

      • Incorrect:

        maketext('Visit [output,url,http://cpanel.net,cPanel] today.');

    • The url() function can also take a single string in place of the “html,...,plain,...” configuration hash and handle it appropriately. For example:

      maketext('Visit [output,url,_1,cPanel] today.', 'http://cpanel.net');

      results in:

                    HTML: Visit <a href="http://cpanel.net">cPanel</a> today.
                    CLI: Visit cPanel (http://cpanel.net) today.

      Note: The CLI () may change to <>.
    • The attr() is like class() except the arguments are a hash of arbitrary options that become attributes in the span HTML tag.

• format_bytes — Displays bytes in human-readable values in the largest unit appropriate. For example:

  • You have used [format_bytes,_1] of your allotted [format_bytes,_2].

• datetime — Formats epoch seconds into text appropriate for the current locale.
  • The first argument is always the epoch second.
  • Currently, the first argument must account for any time zone.
  • time() — $TZ_Offset_in_seconds.
    • This will be a problem if the format displays the time zone, so in the future we'll have a TZ setting and incorporate that properly. So, you can just pass time().
  • The first argument defaults to time().
  • The second argument can be [date|time|datetime]_format_[long|full|medium|short|default].
  • The second argument defaults to 'date_format_long'.

Note: If you want to display the date and time by itself, call the datetime method directly, as in the following example:

[% locale.datetime(epoch_time_of_account_creation,'datetime_format_default') %] 

• comment — Allows embedded comments:

  The transmogrifier has been constipulated to level [_1][comment,The argument is the variable name containing the superposition of the golden ratio's decimal place in relation to pi as mildegredaded by the authoritative falloosifier.].

renders as 'The transmogrifier has been constipulated to level X.'

Notes:

• The convert() function has been disabled.
• The datetime() function has also been customized.
• format_bytes() uses an internal Cpanel module instead of the CPAN module listed in the POD.

Using Special Characters

You can use special characters in maketext() phrases. Here is what you need to know.

Things that need to be quoted should use curly quotes (“”). Not straight quotes("").

You can use the following table for copying and pasting symbols:

Symbol	Description
™	Trademark symbol
®	Registered trademark symbol
©	Copyright symbol
“	Left double quotation marks
”	Right double quotation marks
…	Ellipsis
‘	Left single quotation mark
’	Right single quotation mark
∞	Infinity symbol

Here is a reference for characters that could cause problems in markup:

  Use [output,chr,34] or [output,chr,"]
  Use [output,chr,38] or [output,chr,&]
  Use [output,chr,39] or [output,chr,']
  Use [output,chr,60] or [output,chr,<]
  Use [output,chr,62] or [output,chr,>]

When using bracket notation outside of Perl (this includes YAML files), you should use the character itself:

[% locale.maketext('The file "[_1]" was updated.', file) %] <cptext 'The file “[_1]” was updated.', $file> 

However, to use non-ASCII characters in Perl code, you should use grapheme cluster notation.

Using chr() Inside of Bracket Notation

Although you can't next bracket notation, you can achieve the same results by using chr() in your string. This applies to any output() method.

Example: You need to render [output,chr,<] inside of a string that is also "strong": The less-than character [output,strong,is “<”].

To solve this problem using chr(), you would write:

The less-than character [output,strong,is 'chr(<)'].