# Time-stamp: "2004-01-11 18:35:34 AST"

=head1 NAME

Locale::Maketext - framework for localization

=head1 SYNOPSIS

  package MyProgram;

  use strict;

  use MyProgram::L10N;

   # ...which inherits from Locale::Maketext

  my $lh = MyProgram::L10N->get_handle() || die "What language?";

  ...

  # And then any messages your program emits, like:

  warn $lh->maketext( "Can't open file [_1]: [_2]\n", $f, $! );

  ...

=head1 DESCRIPTION

It is a common feature of applications (whether run directly,

or via the Web) for them to be "localized" -- i.e., for them

to a present an English interface to an English-speaker, a German

interface to a German-speaker, and so on for all languages it's

programmed with.  Locale::Maketext

is a framework for software localization; it provides you with the

tools for organizing and accessing the bits of text and text-processing

code that you need for producing localized applications.

In order to make sense of Maketext and how all its

components fit together, you should probably

go read L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13>, and

I<then> read the following documentation.

You may also want to read over the source for C<File::Findgrep>

and its constituent modules -- they are a complete (if small)

example application that uses Maketext.

=head1 QUICK OVERVIEW

The basic design of Locale::Maketext is object-oriented, and

Locale::Maketext is an abstract base class, from which you

derive a "project class".

The project class (with a name like "TkBocciBall::Localize",

which you then use in your module) is in turn the base class

for all the "language classes" for your project

(with names "TkBocciBall::Localize::it", 

"TkBocciBall::Localize::en",

"TkBocciBall::Localize::fr", etc.).

A language class is

a class containing a lexicon of phrases as class data,

and possibly also some methods that are of use in interpreting

phrases in the lexicon, or otherwise dealing with text in that

language.

An object belonging to a language class is called a "language

handle"; it's typically a flyweight object.

The normal course of action is to call:

  use TkBocciBall::Localize;  # the localization project class

  $lh = TkBocciBall::Localize->get_handle();

   # Depending on the user's locale, etc., this will

   # make a language handle from among the classes available,

   # and any defaults that you declare.

  die "Couldn't make a language handle??" unless $lh;

From then on, you use the C<maketext> function to access

entries in whatever lexicon(s) belong to the language handle

you got.  So, this:

  print $lh->maketext("You won!"), "\n";

...emits the right text for this language.  If the object

in C<$lh> belongs to class "TkBocciBall::Localize::fr" and

%TkBocciBall::Localize::fr::Lexicon contains C<("You won!"

=E<gt> "Tu as gagnE<eacute>!")>, then the above

code happily tells the user "Tu as gagnE<eacute>!".

=head1 METHODS

Locale::Maketext offers a variety of methods, which fall

into three categories:

=over

=item *

Methods to do with constructing language handles.

=item *

C<maketext> and other methods to do with accessing %Lexicon data

for a given language handle.

=item *

Methods that you may find it handy to use, from routines of

yours that you put in %Lexicon entries.

=back

These are covered in the following section.

=head2 Construction Methods

These are to do with constructing a language handle:

=over

=item *

$lh = YourProjClass->get_handle( ...langtags... ) || die "lg-handle?";

This tries loading classes based on the language-tags you give (like

C<("en-US", "sk", "kon", "es-MX", "ja", "i-klingon")>, and for the first class

that succeeds, returns YourProjClass::I<language>->new().

If it runs thru the entire given list of language-tags, and finds no classes

for those exact terms, it then tries "superordinate" language classes.

So if no "en-US" class (i.e., YourProjClass::en_us)

was found, nor classes for anything else in that list, we then try

its superordinate, "en" (i.e., YourProjClass::en), and so on thru 

the other language-tags in the given list: "es".

(The other language-tags in our example list: 

happen to have no superordinates.)

If none of those language-tags leads to loadable classes, we then

try classes derived from YourProjClass->fallback_languages() and

then if nothing comes of that, we use classes named by

YourProjClass->fallback_language_classes().  Then in the (probably

quite unlikely) event that that fails, we just return undef.

=item *

$lh = YourProjClass->get_handleB<()> || die "lg-handle?";

When C<get_handle> is called with an empty parameter list, magic happens:

If C<get_handle> senses that it's running in program that was

invoked as a CGI, then it tries to get language-tags out of the

environment variable "HTTP_ACCEPT_LANGUAGE", and it pretends that

those were the languages passed as parameters to C<get_handle>.

Otherwise (i.e., if not a CGI), this tries various OS-specific ways

to get the language-tags for the current locale/language, and then

pretends that those were the value(s) passed to C<get_handle>.

Currently this OS-specific stuff consists of looking in the environment

variables "LANG" and "LANGUAGE"; and on MSWin machines (where those

variables are typically unused), this also tries using

the module Win32::Locale to get a language-tag for whatever language/locale

is currently selected in the "Regional Settings" (or "International"?)

Control Panel.  I welcome further

suggestions for making this do the Right Thing under other operating

systems that support localization.

If you're using localization in an application that keeps a configuration

file, you might consider something like this in your project class:

  sub get_handle_via_config {

    my $class = $_[0];

    my $chosen_language = $Config_settings{'language'};

    my $lh;

    if($chosen_language) {

      $lh = $class->get_handle($chosen_language)

       || die "No language handle for \"$chosen_language\""

            . " or the like";

    } else {

      # Config file missing, maybe?

      $lh = $class->get_handle()

       || die "Can't get a language handle";

    }

    return $lh;

  }

=item *

$lh = YourProjClass::langname->new();

This constructs a language handle.  You usually B<don't> call this

directly, but instead let C<get_handle> find a language class to C<use>

and to then call ->new on.

=item *

$lh->init();

This is called by ->new to initialize newly-constructed language handles.

If you define an init method in your class, remember that it's usually

considered a good idea to call $lh->SUPER::init in it (presumably at the

beginning), so that all classes get a chance to initialize a new object

however they see fit.

=item *

YourProjClass->fallback_languages()

C<get_handle> appends the return value of this to the end of

whatever list of languages you pass C<get_handle>.  Unless

you override this method, your project class

will inherit Locale::Maketext's C<fallback_languages>, which

currently returns C<('i-default', 'en', 'en-US')>.

("i-default" is defined in RFC 2277).

This method (by having it return the name

of a language-tag that has an existing language class)

can be used for making sure that

C<get_handle> will always manage to construct a language

handle (assuming your language classes are in an appropriate

@INC directory).  Or you can use the next method:

=item *

YourProjClass->fallback_language_classes()

C<get_handle> appends the return value of this to the end

of the list of classes it will try using.  Unless

you override this method, your project class

will inherit Locale::Maketext's C<fallback_language_classes>,

which currently returns an empty list, C<()>.

By setting this to some value (namely, the name of a loadable

language class), you can be sure that

C<get_handle> will always manage to construct a language

handle.

=back

=head2 The "maketext" Method

This is the most important method in Locale::Maketext:

    $text = $lh->maketext(I<key>, ...parameters for this phrase...);

This looks in the %Lexicon of the language handle

$lh and all its superclasses, looking

for an entry whose key is the string I<key>.  Assuming such

an entry is found, various things then happen, depending on the

value found:

If the value is a scalarref, the scalar is dereferenced and returned

(and any parameters are ignored).

If the value is a coderef, we return &$value($lh, ...parameters...).

If the value is a string that I<doesn't> look like it's in Bracket Notation,

we return it (after replacing it with a scalarref, in its %Lexicon).

If the value I<does> look like it's in Bracket Notation, then we compile

it into a sub, replace the string in the %Lexicon with the new coderef,

and then we return &$new_sub($lh, ...parameters...).

Bracket Notation is discussed in a later section.  Note

that trying to compile a string into Bracket Notation can throw

an exception if the string is not syntactically valid (say, by not

balancing brackets right.)

Also, calling &$coderef($lh, ...parameters...) can throw any sort of

exception (if, say, code in that sub tries to divide by zero).  But

a very common exception occurs when you have Bracket

Notation text that says to call a method "foo", but there is no such

method.  (E.g., "You have [quaB<tn>,_1,ball]." will throw an exception

on trying to call $lh->quaB<tn>($_[1],'ball') -- you presumably meant

"quant".)  C<maketext> catches these exceptions, but only to make the

error message more readable, at which point it rethrows the exception.

An exception I<may> be thrown if I<key> is not found in any

of $lh's %Lexicon hashes.  What happens if a key is not found,

is discussed in a later section, "Controlling Lookup Failure".

Note that you might find it useful in some cases to override

the C<maketext> method with an "after method", if you want to

translate encodings, or even scripts:

    package YrProj::zh_cn; # Chinese with PRC-style glyphs

    use base ('YrProj::zh_tw');  # Taiwan-style

    sub maketext {

      my $self = shift(@_);

      my $value = $self->maketext(@_);

      return Chineeze::taiwan2mainland($value);

    }

Or you may want to override it with something that traps

any exceptions, if that's critical to your program:

  sub maketext {

    my($lh, @stuff) = @_;

    my $out;

    eval { $out = $lh->SUPER::maketext(@stuff) };

    return $out unless $@;

    ...otherwise deal with the exception...

  }

Other than those two situations, I don't imagine that

it's useful to override the C<maketext> method.  (If

you run into a situation where it is useful, I'd be

interested in hearing about it.)

=over

=item $lh->fail_with I<or> $lh->fail_with(I<PARAM>)

=item $lh->failure_handler_auto

These two methods are discussed in the section "Controlling

Lookup Failure".

=item $lh->blacklist(@list)

=item $lh->whitelist(@list)

These methods are discussed in the section "Bracket Notation

Security".

=back

=head2 Utility Methods

These are methods that you may find it handy to use, generally

from %Lexicon routines of yours (whether expressed as

Bracket Notation or not).

=over

=item $language->quant($number, $singular)

=item $language->quant($number, $singular, $plural)

=item $language->quant($number, $singular, $plural, $negative)

This is generally meant to be called from inside Bracket Notation

(which is discussed later), as in 

     "Your search matched [quant,_1,document]!"

It's for I<quantifying> a noun (i.e., saying how much of it there is,

while giving the correct form of it).  The behavior of this method is

handy for English and a few other Western European languages, and you

should override it for languages where it's not suitable.  You can feel

free to read the source, but the current implementation is basically

as this pseudocode describes:

     if $number is 0 and there's a $negative,

        return $negative;

     elsif $number is 1,

        return "1 $singular";

     elsif there's a $plural,

        return "$number $plural";

     else

        return "$number " . $singular . "s";

     #

     # ...except that we actually call numf to

     #  stringify $number before returning it.

So for English (with Bracket Notation)

C<"...[quant,_1,file]..."> is fine (for 0 it returns "0 files",

for 1 it returns "1 file", and for more it returns "2 files", etc.)

But for "directory", you'd want C<"[quant,_1,directory,directories]">

so that our elementary C<quant> method doesn't think that the

plural of "directory" is "directorys".  And you might find that the

output may sound better if you specify a negative form, as in:

     "[quant,_1,file,files,No files] matched your query.\n"

Remember to keep in mind verb agreement (or adjectives too, in

other languages), as in:

     "[quant,_1,document] were matched.\n"

Because if _1 is one, you get "1 document B<were> matched".

An acceptable hack here is to do something like this:

     "[quant,_1,document was, documents were] matched.\n"

=item $language->numf($number)

This returns the given number formatted nicely according to

this language's conventions.  Maketext's default method is

mostly to just take the normal string form of the number

(applying sprintf "%G" for only very large numbers), and then

to add commas as necessary.  (Except that

we apply C if $language->{'numf_comma'} is true;

that's a bit of a hack that's useful for languages that express

two million as "2.000.000" and not as "2,000,000").

If you want anything fancier, consider overriding this with something

that uses L<Number::Format|Number::Format>, or does something else

entirely.

Note that numf is called by quant for stringifying all quantifying

numbers.

=item $language->numerate($number, $singular, $plural, $negative)

This returns the given noun form which is appropriate for the quantity

C<$number> according to this language's conventions.  C<numerate> is

used internally by C<quant> to quantify nouns.  Use it directly --

usually from bracket notation -- to avoid C<quant>'s implicit call to

C<numf> and output of a numeric quantity.

=item $language->sprintf($format, @items)

This is just a wrapper around Perl's normal C<sprintf> function.

It's provided so that you can use "sprintf" in Bracket Notation:

     "Couldn't access datanode [sprintf,%10x=~[%s~],_1,_2]!\n"

returning...

     Couldn't access datanode      Stuff=[thangamabob]!

=item $language->language_tag()

Currently this just takes the last bit of C<ref($language)>, turns

underscores to dashes, and returns it.  So if $language is

an object of class Hee::HOO::Haw::en_us, $language->language_tag()

returns "en-us".  (Yes, the usual representation for that language

tag is "en-US", but case is I<never> considered meaningful in

language-tag comparison.)

You may override this as you like; Maketext doesn't use it for

anything.

=item $language->encoding()

Currently this isn't used for anything, but it's provided

(with default value of

C<(ref($language) && $language-E<gt>{'encoding'})) or "iso-8859-1">

) as a sort of suggestion that it may be useful/necessary to

associate encodings with your language handles (whether on a

per-class or even per-handle basis.)

=back

=head2 Language Handle Attributes and Internals

A language handle is a flyweight object -- i.e., it doesn't (necessarily)

carry any data of interest, other than just being a member of

whatever class it belongs to.

A language handle is implemented as a blessed hash.  Subclasses of yours

can store whatever data you want in the hash.  Currently the only hash

entry used by any crucial Maketext method is "fail", so feel free to

use anything else as you like.

B

any point on which this documentation is unclear.>  This documentation

is vastly longer than the module source itself.

=head1 LANGUAGE CLASS HIERARCHIES

These are Locale::Maketext's assumptions about the class

hierarchy formed by all your language classes:

=over

=item *

You must have a project base class, which you load, and

which you then use as the first argument in

the call to YourProjClass->get_handle(...).  It should derive

(whether directly or indirectly) from Locale::Maketext.

It B<doesn't matter> how you name this class, although assuming this

is the localization component of your Super Mega Program,

good names for your project class might be

SuperMegaProgram::Localization, SuperMegaProgram::L10N,

SuperMegaProgram::I18N, SuperMegaProgram::International,

or even SuperMegaProgram::Languages or SuperMegaProgram::Messages.

=item *

Language classes are what YourProjClass->get_handle will try to load.

It will look for them by taking each language-tag (B<skipping> it

if it doesn't look like a language-tag or locale-tag!), turning it to

all lowercase, turning dashes to underscores, and appending it

to YourProjClass . "::".  So this:

  $lh = YourProjClass->get_handle(

    'en-US', 'fr', 'kon', 'i-klingon', 'i-klingon-romanized'

  );

will try loading the classes 

YourProjClass::en_us (note lowercase!), YourProjClass::fr, 

YourProjClass::kon,

YourProjClass::i_klingon

and YourProjClass::i_klingon_romanized.  (And it'll stop at the

first one that actually loads.)

=item *

I assume that each language class derives (directly or indirectly)

from your project class, and also defines its @ISA, its %Lexicon,

or both.  But I anticipate no dire consequences if these assumptions

do not hold.

=item *

Language classes may derive from other language classes (although they

should have "use I<Thatclassname>" or "use base qw(I<...classes...>)").

They may derive from the project

class.  They may derive from some other class altogether.  Or via

multiple inheritance, it may derive from any mixture of these.

=item *

I foresee no problems with having multiple inheritance in

your hierarchy of language classes.  (As usual, however, Perl will

complain bitterly if you have a cycle in the hierarchy: i.e., if

any class is its own ancestor.)

=back

=head1 ENTRIES IN EACH LEXICON

A typical %Lexicon entry is meant to signify a phrase,

taking some number (0 or more) of parameters.  An entry

is meant to be accessed by via

a string I<key> in $lh->maketext(I<key>, ...parameters...),

which should return a string that is generally meant for

be used for "output" to the user -- regardless of whether

this actually means printing to STDOUT, writing to a file,

or putting into a GUI widget.

While the key must be a string value (since that's a basic

restriction that Perl places on hash keys), the value in

the lexicon can currently be of several types:

a defined scalar, scalarref, or coderef.  The use of these is

explained above, in the section 'The "maketext" Method', and

Bracket Notation for strings is discussed in the next section.

While you can use arbitrary unique IDs for lexicon keys

(like "_min_larger_max_error"), it is often

useful for if an entry's key is itself a valid value, like

this example error message:

  "Minimum ([_1]) is larger than maximum ([_2])!\n",

Compare this code that uses an arbitrary ID...

  die $lh->maketext( "_min_larger_max_error", $min, $max )

   if $min > $max;

...to this code that uses a key-as-value:

  die $lh->maketext(

   "Minimum ([_1]) is larger than maximum ([_2])!\n",

   $min, $max

  ) if $min > $max;

The second is, in short, more readable.  In particular, it's obvious

that the number of parameters you're feeding to that phrase (two) is

the number of parameters that it I<wants> to be fed.  (Since you see

_1 and a _2 being used in the key there.)

Also, once a project is otherwise

complete and you start to localize it, you can scrape together

all the various keys you use, and pass it to a translator; and then

the translator's work will go faster if what he's presented is this:

 "Minimum ([_1]) is larger than maximum ([_2])!\n",

  => "",   # fill in something here, Jacques!

rather than this more cryptic mess:

 "_min_larger_max_error"

  => "",   # fill in something here, Jacques

I think that keys as lexicon values makes the completed lexicon

entries more readable:

 "Minimum ([_1]) is larger than maximum ([_2])!\n",

  => "Le minimum ([_1]) est plus grand que le maximum ([_2])!\n",

Also, having valid values as keys becomes very useful if you set

up an _AUTO lexicon.  _AUTO lexicons are discussed in a later

section.

I almost always use keys that are themselves

valid lexicon values.  One notable exception is when the value is

quite long.  For example, to get the screenful of data that

a command-line program might return when given an unknown switch,

I often just use a brief, self-explanatory key such as "_USAGE_MESSAGE".  At that point I then go

and immediately to define that lexicon entry in the

ProjectClass::L10N::en lexicon (since English is always my "project

language"):

  '_USAGE_MESSAGE' => <<'EOSTUFF',

  ...long long message...

  EOSTUFF

and then I can use it as:

  getopt('oDI', \%opts) or die $lh->maketext('_USAGE_MESSAGE');

Incidentally,

note that each class's C<%Lexicon> inherits-and-extends

the lexicons in its superclasses.  This is not because these are

special hashes I<per se>, but because you access them via the

C<maketext> method, which looks for entries across all the

C<%Lexicon> hashes in a language class I<and> all its ancestor classes.

(This is because the idea of "class data" isn't directly implemented

in Perl, but is instead left to individual class-systems to implement

as they see fit..)

Note that you may have things stored in a lexicon

besides just phrases for output:  for example, if your program

takes input from the keyboard, asking a "(Y/N)" question,

you probably need to know what the equivalent of "Y[es]/N[o]" is

in whatever language.  You probably also need to know what

the equivalents of the answers "y" and "n" are.  You can

store that information in the lexicon (say, under the keys

"~answer_y" and "~answer_n", and the long forms as

"~answer_yes" and "~answer_no", where "~" is just an ad-hoc

character meant to indicate to programmers/translators that

these are not phrases for output).

Or instead of storing this in the language class's lexicon,

you can (and, in some cases, really should) represent the same bit

of knowledge as code in a method in the language class.  (That

leaves a tidy distinction between the lexicon as the things we

know how to I<say>, and the rest of the things in the lexicon class

as things that we know how to I<do>.)  Consider

this example of a processor for responses to French "oui/non"

questions:

  sub y_or_n {

    return undef unless defined $_[1] and length $_[1];

    my $answer = lc $_[1];  # smash case

    return 1 if $answer eq 'o' or $answer eq 'oui';

    return 0 if $answer eq 'n' or $answer eq 'non';

    return undef;

  }

...which you'd then call in a construct like this:

  my $response;

  until(defined $response) {

    print $lh->maketext("Open the pod bay door (y/n)? ");

    $response = $lh->y_or_n( get_input_from_keyboard_somehow() );

  }

  if($response) { $pod_bay_door->open()         }

  else          { $pod_bay_door->leave_closed() }

Other data worth storing in a lexicon might be things like

filenames for language-targetted resources:

  ...

  "_main_splash_png"

    => "/styles/en_us/main_splash.png",

  "_main_splash_imagemap"

    => "/styles/en_us/main_splash.incl",

  "_general_graphics_path"

    => "/styles/en_us/",

  "_alert_sound"

    => "/styles/en_us/hey_there.wav",

  "_forward_icon"

   => "left_arrow.png",

  "_backward_icon"

   => "right_arrow.png",

  # In some other languages, left equals

  #  BACKwards, and right is FOREwards.

  ...

You might want to do the same thing for expressing key bindings

or the like (since hardwiring "q" as the binding for the function

that quits a screen/menu/program is useful only if your language

happens to associate "q" with "quit"!)

=head1 BRACKET NOTATION

Bracket Notation is a crucial feature of Locale::Maketext.  I mean

Bracket Notation to provide a replacement for the use of sprintf formatting.

Everything you do with Bracket Notation could be done with a sub block,

but bracket notation is meant to be much more concise.

Bracket Notation is a like a miniature "template" system (in the sense

of L<Text::Template|Text::Template>, not in the sense of C++ templates),

where normal text is passed thru basically as is, but text in special

regions is specially interpreted.  In Bracket Notation, you use square brackets ("[...]"),

not curly braces ("{...}") to note sections that are specially interpreted.

For example, here all the areas that are taken literally are underlined with

a "^", and all the in-bracket special regions are underlined with an X:

  "Minimum ([_1]) is larger than maximum ([_2])!\n",

   ^^^^^^^^^ XX ^^^^^^^^^^^^^^^^^^^^^^^^^^ XX ^^^^

When that string is compiled from bracket notation into a real Perl sub,

it's basically turned into:

  sub {

    my $lh = $_[0];

    my @params = @_;

    return join '',

      "Minimum (",

      ...some code here...

      ") is larger than maximum (",

      ...some code here...

      ")!\n",

  }

  # to be called by $lh->maketext(KEY, params...)

In other words, text outside bracket groups is turned into string

literals.  Text in brackets is rather more complex, and currently follows

these rules:

=over

=item *

Bracket groups that are empty, or which consist only of whitespace,

are ignored.  (Examples: "[]", "[    ]", or a [ and a ] with returns

and/or tabs and/or spaces between them.

Otherwise, each group is taken to be a comma-separated group of items,

and each item is interpreted as follows:

=item *

An item that is "_I<digits>" or "_-I<digits>" is interpreted as

$_[I<value>].  I.e., "_1" becomes with $_[1], and "_-3" is interpreted

as $_[-3] (in which case @_ should have at least three elements in it).

Note that $_[0] is the language handle, and is typically not named

directly.

=item *

An item "_*" is interpreted to mean "all of @_ except $_[0]".

I.e., C<@_[1..$#_]>.  Note that this is an empty list in the case

of calls like $lh->maketext(I<key>) where there are no

parameters (except $_[0], the language handle).

=item *

Otherwise, each item is interpreted as a string literal.

=back

The group as a whole is interpreted as follows:

=over

=item *

If the first item in a bracket group looks like a method name,

then that group is interpreted like this:

  $lh->that_method_name(

    ...rest of items in this group...

  ),

=item *

If the first item in a bracket group is "*", it's taken as shorthand

for the so commonly called "quant" method.  Similarly, if the first

item in a bracket group is "#", it's taken to be shorthand for

"numf".

=item *

If the first item in a bracket group is the empty-string, or "_*"

or "_I<digits>" or "_-I<digits>", then that group is interpreted

as just the interpolation of all its items:

  join('',

    ...rest of items in this group...

  ),

Examples:  "[_1]" and "[,_1]", which are synonymous; and

"C<[,ID-(,_4,-,_2,)]>", which compiles as

C<join "", "ID-(", $_[4], "-", $_[2], ")">.

=item *

Otherwise this bracket group is invalid.  For example, in the group

"[!@#,whatever]", the first item C<"!@#"> is neither the empty-string,

"_I<number>", "_-I<number>", "_*", nor a valid method name; and so

Locale::Maketext will throw an exception of you try compiling an

expression containing this bracket group.

=back

Note, incidentally, that items in each group are comma-separated,

not C</\s*,\s*/>-separated.  That is, you might expect that this

bracket group:

  "Hoohah [foo, _1 , bar ,baz]!"

would compile to this:

  sub {

    my $lh = $_[0];

    return join '',

      "Hoohah ",

      $lh->foo( $_[1], "bar", "baz"),

      "!",

  }

But it actually compiles as this:

  sub {

    my $lh = $_[0];

    return join '',

      "Hoohah ",

      $lh->foo(" _1 ", " bar ", "baz"),  # note the <space> in " bar "

      "!",

  }

In the notation discussed so far, the characters "[" and "]" are given

special meaning, for opening and closing bracket groups, and "," has

a special meaning inside bracket groups, where it separates items in the

group.  This begs the question of how you'd express a literal "[" or

"]" in a Bracket Notation string, and how you'd express a literal

comma inside a bracket group.  For this purpose I've adopted "~" (tilde)

as an escape character:  "~[" means a literal '[' character anywhere

in Bracket Notation (i.e., regardless of whether you're in a bracket

group or not), and ditto for "~]" meaning a literal ']', and "~," meaning

a literal comma.  (Altho "," means a literal comma outside of

bracket groups -- it's only inside bracket groups that commas are special.)

And on the off chance you need a literal tilde in a bracket expression,

you get it with "~~".

Currently, an unescaped "~" before a character

other than a bracket or a comma is taken to mean just a "~" and that

character.  I.e., "~X" means the same as "~~X" -- i.e., one literal tilde,

and then one literal "X".  However, by using "~X", you are assuming that

no future version of Maketext will use "~X" as a magic escape sequence.

In practice this is not a great problem, since first off you can just

write "~~X" and not worry about it; second off, I doubt I'll add lots

of new magic characters to bracket notation; and third off, you

aren't likely to want literal "~" characters in your messages anyway,

since it's not a character with wide use in natural language text.

Brackets must be balanced -- every openbracket must have

one matching closebracket, and vice versa.  So these are all B<invalid>:

  "I ate [quant,_1,rhubarb pie."

  "I ate [quant,_1,rhubarb pie[."

  "I ate quant,_1,rhubarb pie]."

  "I ate quant,_1,rhubarb pie[."

Currently, bracket groups do not nest.  That is, you B<cannot> say:

  "Foo [bar,baz,[quux,quuux]]\n";

If you need a notation that's that powerful, use normal Perl:

  %Lexicon = (

    ...

    "some_key" => sub {

      my $lh = $_[0];

      join '',

        "Foo ",

        $lh->bar('baz', $lh->quux('quuux')),

        "\n",

    },

    ...

  );

Or write the "bar" method so you don't need to pass it the

output from calling quux.

I do not anticipate that you will need (or particularly want)

to nest bracket groups, but you are welcome to email me with

convincing (real-life) arguments to the contrary.

=head1 BRACKET NOTATION SECURITY

Locale::Maketext does not use any special syntax to differentiate

bracket notation methods from normal class or object methods. This

design makes it vulnerable to format string attacks whenever it is

used to process strings provided by untrusted users.

Locale::Maketext does support blacklist and whitelist functionality

to limit which methods may be called as bracket notation methods.