locale::maketext.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

these are not phrases for output).
.PP
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 \fIsay\fR, and the rest of the things in the lexicon class
as things that we know how to \fIdo\fR.)  Consider
this example of a processor for responses to French \*(L"oui/non\*(R"
questions:
.PP
.Vb 7
\&  sub y_or_n {
\&    return undef unless defined $_[1] and length $_[1];
\&    my $answer = lc $_[1];  # smash case
\&    return 1 if $answer eq \*(Aqo\*(Aq or $answer eq \*(Aqoui\*(Aq;
\&    return 0 if $answer eq \*(Aqn\*(Aq or $answer eq \*(Aqnon\*(Aq;
\&    return undef;
\&  }
.Ve
.PP
\&...which you'd then call in a construct like this:
.PP
.Vb 7
\&  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() }
.Ve
.PP
Other data worth storing in a lexicon might be things like
filenames for language-targetted resources:
.PP
.Vb 10
\&  ...
\&  "_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.
\&  ...
.Ve
.PP
You might want to do the same thing for expressing key bindings
or the like (since hardwiring \*(L"q\*(R" as the binding for the function
that quits a screen/menu/program is useful only if your language
happens to associate \*(L"q\*(R" with \*(L"quit\*(R"!)
.SH "BRACKET NOTATION"
.IX Header "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.
.PP
Bracket Notation is a like a miniature \*(L"template\*(R" system (in the sense
of 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 (\*(L"[...]\*(R"),
not curly braces (\*(L"{...}\*(R") to note sections that are specially interpreted.
.PP
For example, here all the areas that are taken literally are underlined with
a \*(L"^\*(R", and all the in-bracket special regions are underlined with an X:
.PP
.Vb 2
\&  "Minimum ([_1]) is larger than maximum ([_2])!\en",
\&   ^^^^^^^^^ XX ^^^^^^^^^^^^^^^^^^^^^^^^^^ XX ^^^^
.Ve
.PP
When that string is compiled from bracket notation into a real Perl sub,
it's basically turned into:
.PP
.Vb 11
\&  sub {
\&    my $lh = $_[0];
\&    my @params = @_;
\&    return join \*(Aq\*(Aq,
\&      "Minimum (",
\&      ...some code here...
\&      ") is larger than maximum (",
\&      ...some code here...
\&      ")!\en",
\&  }
\&  # to be called by $lh\->maketext(KEY, params...)
.Ve
.PP
In other words, text outside bracket groups is turned into string
literals.  Text in brackets is rather more complex, and currently follows
these rules:
.IP "\(bu" 4
Bracket groups that are empty, or which consist only of whitespace,
are ignored.  (Examples: \*(L"[]\*(R", \*(L"[    ]\*(R", or a [ and a ] with returns
and/or tabs and/or spaces between them.
.Sp
Otherwise, each group is taken to be a comma-separated group of items,
and each item is interpreted as follows:
.IP "\(bu" 4
An item that is "_\fIdigits\fR\*(L" or \*(R"_\-\fIdigits\fR" is interpreted as
\&\f(CW$_\fR[\fIvalue\fR].  I.e., \*(L"_1\*(R" becomes with \f(CW$_\fR[1], and \*(L"_\-3\*(R" is interpreted
as \f(CW$_\fR[\-3] (in which case \f(CW@_\fR should have at least three elements in it).
Note that \f(CW$_\fR[0] is the language handle, and is typically not named
directly.
.IP "\(bu" 4
An item \*(L"_*\*(R" is interpreted to mean \*(L"all of \f(CW@_\fR except \f(CW$_\fR[0]\*(R".
I.e., \f(CW@_[1..$#_]\fR.  Note that this is an empty list in the case
of calls like \f(CW$lh\fR\->maketext(\fIkey\fR) where there are no
parameters (except \f(CW$_\fR[0], the language handle).
.IP "\(bu" 4
Otherwise, each item is interpreted as a string literal.
.PP
The group as a whole is interpreted as follows:
.IP "\(bu" 4
If the first item in a bracket group looks like a method name,
then that group is interpreted like this:
.Sp
.Vb 3
\&  $lh\->that_method_name(
\&    ...rest of items in this group...
\&  ),
.Ve
.IP "\(bu" 4
If the first item in a bracket group is \*(L"*\*(R", it's taken as shorthand
for the so commonly called \*(L"quant\*(R" method.  Similarly, if the first
item in a bracket group is \*(L"#\*(R", it's taken to be shorthand for
\&\*(L"numf\*(R".
.IP "\(bu" 4
If the first item in a bracket group is the empty-string, or \*(L"_*\*(R"
or "_\fIdigits\fR\*(L" or \*(R"_\-\fIdigits\fR", then that group is interpreted
as just the interpolation of all its items:
.Sp
.Vb 3
\&  join(\*(Aq\*(Aq,
\&    ...rest of items in this group...
\&  ),
.Ve
.Sp
Examples:  \*(L"[_1]\*(R" and \*(L"[,_1]\*(R", which are synonymous; and
"\f(CW\*(C`[,ID\-(,_4,\-,_2,)]\*(C'\fR", which compiles as
\&\f(CW\*(C`join "", "ID\-(", $_[4], "\-", $_[2], ")"\*(C'\fR.
.IP "\(bu" 4
Otherwise this bracket group is invalid.  For example, in the group
\&\*(L"[!@#,whatever]\*(R", the first item \f(CW"!@#"\fR is neither the empty-string,
"_\fInumber\fR\*(L", \*(R"_\-\fInumber\fR\*(L", \*(R"_*", nor a valid method name; and so
Locale::Maketext will throw an exception of you try compiling an
expression containing this bracket group.
.PP
Note, incidentally, that items in each group are comma-separated,
not \f(CW\*(C`/\es*,\es*/\*(C'\fR\-separated.  That is, you might expect that this
bracket group:
.PP
.Vb 1
\&  "Hoohah [foo, _1 , bar ,baz]!"
.Ve
.PP
would compile to this:
.PP
.Vb 7
\&  sub {
\&    my $lh = $_[0];
\&    return join \*(Aq\*(Aq,
\&      "Hoohah ",
\&      $lh\->foo( $_[1], "bar", "baz"),
\&      "!",
\&  }
.Ve
.PP
But it actually compiles as this:
.PP
.Vb 7
\&  sub {
\&    my $lh = $_[0];
\&    return join \*(Aq\*(Aq,
\&      "Hoohah ",
\&      $lh\->foo(" _1 ", " bar ", "baz"),  # note the <space> in " bar "
\&      "!",
\&  }
.Ve
.PP
In the notation discussed so far, the characters \*(L"[\*(R" and \*(L"]\*(R" are given
special meaning, for opening and closing bracket groups, and \*(L",\*(R" 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 \*(L"[\*(R" or
\&\*(L"]\*(R" in a Bracket Notation string, and how you'd express a literal
comma inside a bracket group.  For this purpose I've adopted \*(L"~\*(R" (tilde)
as an escape character:  \*(L"~[\*(R" means a literal '[' character anywhere
in Bracket Notation (i.e., regardless of whether you're in a bracket
group or not), and ditto for \*(L"~]\*(R" meaning a literal ']', and \*(L"~,\*(R" meaning
a literal comma.  (Altho \*(L",\*(R" means a literal comma outside of
bracket groups \*(-- it's only inside bracket groups that commas are special.)
.PP
And on the off chance you need a literal tilde in a bracket expression,
you get it with \*(L"~~\*(R".
.PP
Currently, an unescaped \*(L"~\*(R" before a character
other than a bracket or a comma is taken to mean just a \*(L"~\*(R" and that
character.  I.e., \*(L"~X\*(R" means the same as \*(L"~~X\*(R" \*(-- i.e., one literal tilde,
and then one literal \*(L"X\*(R".  However, by using \*(L"~X\*(R", you are assuming that
no future version of Maketext will use \*(L"~X\*(R" as a magic escape sequence.
In practice this is not a great problem, since first off you can just
write \*(L"~~X\*(R" 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 \*(L"~\*(R" characters in your messages anyway,
since it's not a character with wide use in natural language text.
.PP
Brackets must be balanced \*(-- every openbracket must have
one matching closebracket, and vice versa.  So these are all \fBinvalid\fR:
.PP
.Vb 4
\&  "I ate [quant,_1,rhubarb pie."
\&  "I ate [quant,_1,rhubarb pie[."
\&  "I ate quant,_1,rhubarb pie]."
\&  "I ate quant,_1,rhubarb pie[."
.Ve
.PP
Currently, bracket groups do not nest.  That is, you \fBcannot\fR say:
.PP
.Vb 1
\&  "Foo [bar,baz,[quux,quuux]]\en";
.Ve
.PP
If you need a notation that's that powerful, use normal Perl:
.PP
.Vb 11
\&  %Lexicon = (
\&    ...
\&    "some_key" => sub {
\&      my $lh = $_[0];
\&      join \*(Aq\*(Aq,
\&        "Foo ",
\&        $lh\->bar(\*(Aqbaz\*(Aq, $lh\->quux(\*(Aqquuux\*(Aq)),
\&        "\en",
\&    },
\&    ...
\&  );
.Ve
.PP
Or write the \*(L"bar\*(R" method so you don't need to pass it the
output from calling quux.
.PP
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.
.SH "AUTO LEXICONS"
.IX Header "AUTO LEXICONS"
If maketext goes to look in an individual \f(CW%Lexicon\fR for an entry
for \fIkey\fR (where \fIkey\fR does not start with an underscore), and
sees none, \fBbut does see\fR an entry of \*(L"_AUTO\*(R" => \fIsome_true_value\fR,
then we actually define \f(CW$Lexicon\fR{\fIkey\fR} = \fIkey\fR right then and there,
and then use that value as if it had been there all
along.  This happens before we even look in any superclass \f(CW%Lexicons\fR!
.PP
(This is meant to be somewhat like the \s-1AUTOLOAD\s0 mechanism in
Perl's function call system \*(-- or, looked at another way,
like the AutoLoader module.)
.PP
I can picture all sorts of circumstances where you just
do not want lookup to be able to fail (since failing
normally means that maketext throws a \f(CW\*(C`die\*(C'\fR, although
see the next section for greater control over that).  But
here's one circumstance where _AUTO lexicons are meant to
be \fIespecially\fR useful:
.PP
As you're writing an application, you decide as you go what messages
you need to emit.  Normally you'd go to write this:
.PP
.Vb 5
\&  if(\-e $filename) {
\&    go_process_file($filename)
\&  } else {
\&    print qq{Couldn\*(Aqt find file "$filename"!\en};
\&  }
.Ve
.PP
but since you anticipate localizing this, you write:
.PP
.Vb 10
\&  use ThisProject::I18N;
\&  my $lh = ThisProject::I18N\->get_handle();
\&   # For the moment, assume that things are set up so
\&   # that we load class ThisProject::I18N::en
\&   # and that that\*(Aqs the class that $lh belongs to.
\&  ...
\&  if(\-e $filename) {
\&    go_process_file($filename)
\&  } else {
\&    print $lh\->maketext(
\&      qq{Couldn\*(Aqt find file "[_1]"!\en}, $filename
\&    );
\&  }
.Ve
.PP
Now, right after you've just written the above lines, you'd
normally have to go open the file 
ThisProject/I18N/en.pm, and immediately add an entry:
.PP
.Vb 2
\&  "Couldn\*(Aqt find file \e"[_1]\e"!\en"
\&  => "Couldn\*(Aqt find file \e"[_1]\e"!\en",
.Ve
.PP
But I consider that somewhat of a distraction from the work
of getting the main code working \*(-- to say nothing of the fact
that I often have to play with the program a few times before
I can decide exactly what wording I want in the messages (which
in this case would require me to go changing three lines of code:
the call to maketext with that key, and then the two lines in
ThisProject/I18N/en.pm).
.PP
However, if you set \*(L"_AUTO => 1\*(R" in the \f(CW%Lexicon\fR in,
ThisProject/I18N/en.pm (assuming that English (en) is
the language that all your programmers will be using for this
project's internal message keys), then you don't ever have to
go adding lines like this
.PP
.Vb 2
\&  "Couldn\*(Aqt find file \e"[_1]\e"!\en"
\&  => "Couldn\*(Aqt find file \e"[_1]\e"!\en",
.Ve
.PP
to ThisProject/I18N/en.pm, because if _AUTO is true there,
then just looking for an entry with the key \*(L"Couldn't find
file \e\*(R"[_1]\e\*(L"!\en\*(R" in that lexicon will cause it to be added,
with that value!
.PP
Note that the reason that keys that start with \*(L"_\*(R"
are immune to _AUTO isn't anything generally magical about
the underscore character \*(-- I just wanted a way to have most
lexicon keys be autoable, except for possibly a few, and I
arbitrarily decided to use a leading underscore as a signal
to distinguish those few.
.SH "CONTROLLING LOOKUP FAILURE"
.IX Header "CONTROLLING LOOKUP FAILURE"
If you call \f(CW$lh\fR\->maketext(\fIkey\fR, ...parameters...),
and there's no entry \fIkey\fR in \f(CW$lh\fR's class's \f(CW%Lexicon\fR, nor
in the superclass \f(CW%Lexicon\fR hash, \fIand\fR if we can't auto-make
\&\fIkey\fR (because either it starts with a \*(L"_\*(R", or because none
of its lexicons have \f(CW\*(C`_AUTO => 1,\*(C'\fR), then we have
failed to find a normal way to maketext \fIkey\fR.  What then
happens in these failure conditions, depends on the \f(CW$lh\fR object's
\&\*(L"fail\*(R" attribute.
.PP
If the language handle has no \*(L"fail\*(R" attribute, maketext
will simply throw an exception (i.e., it calls \f(CW\*(C`die\*(C'\fR, mentioning
the \fIkey\fR whose lookup failed, and naming the line number where
the calling \f(CW$lh\fR\->maketext(\fIkey\fR,...) was.
.PP
If the language handle has a \*(L"fail\*(R" attribute whose value is a
coderef, then \f(CW$lh\fR\->maketext(\fIkey\fR,...params...) gives up and calls:
.PP
.Vb 1
\&  return $that_subref\->($lh, $key, @params);
.Ve
.PP
Otherwise, the \*(L"fail\*(R" attribute's value should be a string denoting
a method name, so that \f(CW$lh\fR\->maketext(\fIkey\fR,...params...) can