locale::maketext.3

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

.PP
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.)
.PP
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 \*(L"foo\*(R", but there is no such
method.  (E.g., "You have [qua\fBtn\fR,_1,ball]." will throw an exception
on trying to call \f(CW$lh\fR\->qua\fBtn\fR($_[1],'ball') \*(-- you presumably meant
\&\*(L"quant\*(R".)  \f(CW\*(C`maketext\*(C'\fR catches these exceptions, but only to make the
error message more readable, at which point it rethrows the exception.
.PP
An exception \fImay\fR be thrown if \fIkey\fR is not found in any
of \f(CW$lh\fR's \f(CW%Lexicon\fR hashes.  What happens if a key is not found,
is discussed in a later section, \*(L"Controlling Lookup Failure\*(R".
.PP
Note that you might find it useful in some cases to override
the \f(CW\*(C`maketext\*(C'\fR method with an \*(L"after method\*(R", if you want to
translate encodings, or even scripts:
.PP
.Vb 7
\&    package YrProj::zh_cn; # Chinese with PRC\-style glyphs
\&    use base (\*(AqYrProj::zh_tw\*(Aq);  # Taiwan\-style
\&    sub maketext {
\&      my $self = shift(@_);
\&      my $value = $self\->maketext(@_);
\&      return Chineeze::taiwan2mainland($value);
\&    }
.Ve
.PP
Or you may want to override it with something that traps
any exceptions, if that's critical to your program:
.PP
.Vb 7
\&  sub maketext {
\&    my($lh, @stuff) = @_;
\&    my $out;
\&    eval { $out = $lh\->SUPER::maketext(@stuff) };
\&    return $out unless $@;
\&    ...otherwise deal with the exception...
\&  }
.Ve
.PP
Other than those two situations, I don't imagine that
it's useful to override the \f(CW\*(C`maketext\*(C'\fR method.  (If
you run into a situation where it is useful, I'd be
interested in hearing about it.)
.ie n .IP "$lh\fR\->fail_with \fIor\fR \f(CW$lh\fR\->fail_with(\fI\s-1PARAM\s0)" 4
.el .IP "\f(CW$lh\fR\->fail_with \fIor\fR \f(CW$lh\fR\->fail_with(\fI\s-1PARAM\s0\fR)" 4
.IX Item "$lh->fail_with or $lh->fail_with(PARAM)"
.PD 0
.ie n .IP "$lh\->failure_handler_auto" 4
.el .IP "\f(CW$lh\fR\->failure_handler_auto" 4
.IX Item "$lh->failure_handler_auto"
.PD
These two methods are discussed in the section \*(L"Controlling
Lookup Failure\*(R".
.Sh "Utility Methods"
.IX Subsection "Utility Methods"
These are methods that you may find it handy to use, generally
from \f(CW%Lexicon\fR routines of yours (whether expressed as
Bracket Notation or not).
.ie n .IP "$language\fR\->quant($number, \f(CW$singular)" 4
.el .IP "\f(CW$language\fR\->quant($number, \f(CW$singular\fR)" 4
.IX Item "$language->quant($number, $singular)"
.PD 0
.ie n .IP "$language\fR\->quant($number, \f(CW$singular\fR, \f(CW$plural)" 4
.el .IP "\f(CW$language\fR\->quant($number, \f(CW$singular\fR, \f(CW$plural\fR)" 4
.IX Item "$language->quant($number, $singular, $plural)"
.ie n .IP "$language\fR\->quant($number, \f(CW$singular\fR, \f(CW$plural\fR, \f(CW$negative)" 4
.el .IP "\f(CW$language\fR\->quant($number, \f(CW$singular\fR, \f(CW$plural\fR, \f(CW$negative\fR)" 4
.IX Item "$language->quant($number, $singular, $plural, $negative)"
.PD
This is generally meant to be called from inside Bracket Notation
(which is discussed later), as in
.Sp
.Vb 1
\&     "Your search matched [quant,_1,document]!"
.Ve
.Sp
It's for \fIquantifying\fR 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:
.Sp
.Vb 11
\&     if $number is 0 and there\*(Aqs a $negative,
\&        return $negative;
\&     elsif $number is 1,
\&        return "1 $singular";
\&     elsif there\*(Aqs a $plural,
\&        return "$number $plural";
\&     else
\&        return "$number " . $singular . "s";
\&     #
\&     # ...except that we actually call numf to
\&     #  stringify $number before returning it.
.Ve
.Sp
So for English (with Bracket Notation)
\&\f(CW"...[quant,_1,file]..."\fR is fine (for 0 it returns \*(L"0 files\*(R",
for 1 it returns \*(L"1 file\*(R", and for more it returns \*(L"2 files\*(R", etc.)
.Sp
But for \*(L"directory\*(R", you'd want \f(CW"[quant,_1,directory,directories]"\fR
so that our elementary \f(CW\*(C`quant\*(C'\fR method doesn't think that the
plural of \*(L"directory\*(R" is \*(L"directorys\*(R".  And you might find that the
output may sound better if you specify a negative form, as in:
.Sp
.Vb 1
\&     "[quant,_1,file,files,No files] matched your query.\en"
.Ve
.Sp
Remember to keep in mind verb agreement (or adjectives too, in
other languages), as in:
.Sp
.Vb 1
\&     "[quant,_1,document] were matched.\en"
.Ve
.Sp
Because if _1 is one, you get "1 document \fBwere\fR matched".
An acceptable hack here is to do something like this:
.Sp
.Vb 1
\&     "[quant,_1,document was, documents were] matched.\en"
.Ve
.ie n .IP "$language\->numf($number)" 4
.el .IP "\f(CW$language\fR\->numf($number)" 4
.IX 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 \*(L"%G\*(R" for only very large numbers), and then
to add commas as necessary.  (Except that
we apply \f(CW\*(C`tr/,./.,/\*(C'\fR if \f(CW$language\fR\->{'numf_comma'} is true;
that's a bit of a hack that's useful for languages that express
two million as \*(L"2.000.000\*(R" and not as \*(L"2,000,000\*(R").
.Sp
If you want anything fancier, consider overriding this with something
that uses Number::Format, or does something else
entirely.
.Sp
Note that numf is called by quant for stringifying all quantifying
numbers.
.ie n .IP "$language\fR\->sprintf($format, \f(CW@items)" 4
.el .IP "\f(CW$language\fR\->sprintf($format, \f(CW@items\fR)" 4
.IX Item "$language->sprintf($format, @items)"
This is just a wrapper around Perl's normal \f(CW\*(C`sprintf\*(C'\fR function.
It's provided so that you can use \*(L"sprintf\*(R" in Bracket Notation:
.Sp
.Vb 1
\&     "Couldn\*(Aqt access datanode [sprintf,%10x=~[%s~],_1,_2]!\en"
.Ve
.Sp
returning...
.Sp
.Vb 1
\&     Couldn\*(Aqt access datanode      Stuff=[thangamabob]!
.Ve
.ie n .IP "$language\fR\->\fIlanguage_tag()" 4
.el .IP "\f(CW$language\fR\->\fIlanguage_tag()\fR" 4
.IX Item "$language->language_tag()"
Currently this just takes the last bit of \f(CW\*(C`ref($language)\*(C'\fR, turns
underscores to dashes, and returns it.  So if \f(CW$language\fR is
an object of class Hee::HOO::Haw::en_us, \f(CW$language\fR\->\fIlanguage_tag()\fR
returns \*(L"en-us\*(R".  (Yes, the usual representation for that language
tag is \*(L"en-US\*(R", but case is \fInever\fR considered meaningful in
language-tag comparison.)
.Sp
You may override this as you like; Maketext doesn't use it for
anything.
.ie n .IP "$language\fR\->\fIencoding()" 4
.el .IP "\f(CW$language\fR\->\fIencoding()\fR" 4
.IX Item "$language->encoding()"
Currently this isn't used for anything, but it's provided
(with default value of
\&\f(CW\*(C`(ref($language) && $language\->{\*(Aqencoding\*(Aq})) or "iso\-8859\-1"\*(C'\fR
) 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.)
.Sh "Language Handle Attributes and Internals"
.IX Subsection "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.
.PP
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 \*(L"fail\*(R", so feel free to
use anything else as you like.
.PP
\&\fBRemember: Don't be afraid to read the Maketext source if there's
any point on which this documentation is unclear.\fR  This documentation
is vastly longer than the module source itself.
.SH "LANGUAGE CLASS HIERARCHIES"
.IX Header "LANGUAGE CLASS HIERARCHIES"
These are Locale::Maketext's assumptions about the class
hierarchy formed by all your language classes:
.IP "\(bu" 4
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 \fBdoesn't matter\fR 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.
.IP "\(bu" 4
Language classes are what YourProjClass\->get_handle will try to load.
It will look for them by taking each language-tag (\fBskipping\fR 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 . \*(L"::\*(R".  So this:
.Sp
.Vb 3
\&  $lh = YourProjClass\->get_handle(
\&    \*(Aqen\-US\*(Aq, \*(Aqfr\*(Aq, \*(Aqkon\*(Aq, \*(Aqi\-klingon\*(Aq, \*(Aqi\-klingon\-romanized\*(Aq
\&  );
.Ve
.Sp
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.)
.IP "\(bu" 4
I assume that each language class derives (directly or indirectly)
from your project class, and also defines its \f(CW@ISA\fR, its \f(CW%Lexicon\fR,
or both.  But I anticipate no dire consequences if these assumptions
do not hold.
.IP "\(bu" 4
Language classes may derive from other language classes (although they
should have "use \fIThatclassname\fR\*(L" or \*(R"use base qw(\fI...classes...\fR)").
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.
.IP "\(bu" 4
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.)
.SH "ENTRIES IN EACH LEXICON"
.IX Header "ENTRIES IN EACH LEXICON"
A typical \f(CW%Lexicon\fR 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 \fIkey\fR in \f(CW$lh\fR\->maketext(\fIkey\fR, ...parameters...),
which should return a string that is generally meant for
be used for \*(L"output\*(R" to the user \*(-- regardless of whether
this actually means printing to \s-1STDOUT\s0, writing to a file,
or putting into a \s-1GUI\s0 widget.
.PP
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 \*(L"maketext\*(R" Method', and
Bracket Notation for strings is discussed in the next section.
.PP
While you can use arbitrary unique IDs for lexicon keys
(like \*(L"_min_larger_max_error\*(R"), it is often
useful for if an entry's key is itself a valid value, like
this example error message:
.PP
.Vb 1
\&  "Minimum ([_1]) is larger than maximum ([_2])!\en",
.Ve
.PP
Compare this code that uses an arbitrary \s-1ID\s0...
.PP
.Vb 2
\&  die $lh\->maketext( "_min_larger_max_error", $min, $max )
\&   if $min > $max;
.Ve
.PP
\&...to this code that uses a key-as-value:
.PP
.Vb 4
\&  die $lh\->maketext(
\&   "Minimum ([_1]) is larger than maximum ([_2])!\en",
\&   $min, $max
\&  ) if $min > $max;
.Ve
.PP
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 \fIwants\fR to be fed.  (Since you see
_1 and a _2 being used in the key there.)
.PP
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:
.PP
.Vb 2
\& "Minimum ([_1]) is larger than maximum ([_2])!\en",
\&  => "",   # fill in something here, Jacques!
.Ve
.PP
rather than this more cryptic mess:
.PP
.Vb 2
\& "_min_larger_max_error"
\&  => "",   # fill in something here, Jacques
.Ve
.PP
I think that keys as lexicon values makes the completed lexicon
entries more readable:
.PP
.Vb 2
\& "Minimum ([_1]) is larger than maximum ([_2])!\en",
\&  => "Le minimum ([_1]) est plus grand que le maximum ([_2])!\en",
.Ve
.PP
Also, having valid values as keys becomes very useful if you set
up an _AUTO lexicon.  _AUTO lexicons are discussed in a later
section.
.PP
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 \*(L"_USAGE_MESSAGE\*(R".  At that point I then go
and immediately to define that lexicon entry in the
ProjectClass::L10N::en lexicon (since English is always my \*(L"project
language\*(R"):
.PP
.Vb 3
\&  \*(Aq_USAGE_MESSAGE\*(Aq => <<\*(AqEOSTUFF\*(Aq,
\&  ...long long message...
\&  EOSTUFF
.Ve
.PP
and then I can use it as:
.PP
.Vb 1
\&  getopt(\*(AqoDI\*(Aq, \e%opts) or die $lh\->maketext(\*(Aq_USAGE_MESSAGE\*(Aq);
.Ve
.PP
Incidentally,
note that each class's \f(CW%Lexicon\fR inherits-and-extends
the lexicons in its superclasses.  This is not because these are
special hashes \fIper se\fR, but because you access them via the
\&\f(CW\*(C`maketext\*(C'\fR method, which looks for entries across all the
\&\f(CW%Lexicon\fR hashes in a language class \fIand\fR all its ancestor classes.
(This is because the idea of \*(L"class data\*(R" isn't directly implemented
in Perl, but is instead left to individual class-systems to implement
as they see fit..)
.PP
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 \*(L"(Y/N)\*(R" question,
you probably need to know what the equivalent of \*(L"Y[es]/N[o]\*(R" is
in whatever language.  You probably also need to know what
the equivalents of the answers \*(L"y\*(R" and \*(L"n\*(R" are.  You can
store that information in the lexicon (say, under the keys
\&\*(L"~answer_y\*(R" and \*(L"~answer_n\*(R", and the long forms as
\&\*(L"~answer_yes\*(R" and \*(L"~answer_no\*(R", where \*(L"~\*(R" is just an ad-hoc
character meant to indicate to programmers/translators that