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 noation 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 examples:

  • [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.

• 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!

• 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:

<td>[% locale.datetime(epoch_time_of_account_creation,'datetime_format_default') %]</td> 

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.