locale::maketext.3

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

.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Locale::Maketext 3"
.TH Locale::Maketext 3 "2007-12-18" "perl v5.10.0" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Locale::Maketext \- framework for localization
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 9
\&  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\*(Aqt open file [_1]: [_2]\en", $f, $! );
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
It is a common feature of applications (whether run directly,
or via the Web) for them to be \*(L"localized\*(R" \*(-- 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.
.PP
In order to make sense of Maketext and how all its
components fit together, you should probably
go read Locale::Maketext::TPJ13, and
\&\fIthen\fR read the following documentation.
.PP
You may also want to read over the source for \f(CW\*(C`File::Findgrep\*(C'\fR
and its constituent modules \*(-- they are a complete (if small)
example application that uses Maketext.
.SH "QUICK OVERVIEW"
.IX Header "QUICK OVERVIEW"
The basic design of Locale::Maketext is object-oriented, and
Locale::Maketext is an abstract base class, from which you
derive a \*(L"project class\*(R".
The project class (with a name like \*(L"TkBocciBall::Localize\*(R",
which you then use in your module) is in turn the base class
for all the \*(L"language classes\*(R" for your project
(with names \*(L"TkBocciBall::Localize::it\*(R", 
\&\*(L"TkBocciBall::Localize::en\*(R",
\&\*(L"TkBocciBall::Localize::fr\*(R", etc.).
.PP
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.
.PP
An object belonging to a language class is called a \*(L"language
handle\*(R"; it's typically a flyweight object.
.PP
The normal course of action is to call:
.PP
.Vb 6
\&  use TkBocciBall::Localize;  # the localization project class
\&  $lh = TkBocciBall::Localize\->get_handle();
\&   # Depending on the user\*(Aqs locale, etc., this will
\&   # make a language handle from among the classes available,
\&   # and any defaults that you declare.
\&  die "Couldn\*(Aqt make a language handle??" unless $lh;
.Ve
.PP
From then on, you use the \f(CW\*(C`maketext\*(C'\fR function to access
entries in whatever lexicon(s) belong to the language handle
you got.  So, this:
.PP
.Vb 1
\&  print $lh\->maketext("You won!"), "\en";
.Ve
.PP
\&...emits the right text for this language.  If the object
in \f(CW$lh\fR belongs to class \*(L"TkBocciBall::Localize::fr\*(R" and
\&\f(CW%TkBocciBall::Localize::fr::Lexicon\fR contains \f(CW\*(C`("You won!"
=> "Tu as gagne\*'!")\*(C'\fR, then the above
code happily tells the user \*(L"Tu as gagne\*'!\*(R".
.SH "METHODS"
.IX Header "METHODS"
Locale::Maketext offers a variety of methods, which fall
into three categories:
.IP "\(bu" 4
Methods to do with constructing language handles.
.IP "\(bu" 4
\&\f(CW\*(C`maketext\*(C'\fR and other methods to do with accessing \f(CW%Lexicon\fR data
for a given language handle.
.IP "\(bu" 4
Methods that you may find it handy to use, from routines of
yours that you put in \f(CW%Lexicon\fR entries.
.PP
These are covered in the following section.
.Sh "Construction Methods"
.IX Subsection "Construction Methods"
These are to do with constructing a language handle:
.IP "\(bu" 4
\&\f(CW$lh\fR = YourProjClass\->get_handle( ...langtags... ) || die \*(L"lg-handle?\*(R";
.Sp
This tries loading classes based on the language-tags you give (like
\&\f(CW\*(C`("en\-US", "sk", "kon", "es\-MX", "ja", "i\-klingon")\*(C'\fR, and for the first class
that succeeds, returns YourProjClass::\fIlanguage\fR\->\fInew()\fR.
.Sp
If it runs thru the entire given list of language-tags, and finds no classes
for those exact terms, it then tries \*(L"superordinate\*(R" language classes.
So if no \*(L"en-US\*(R" class (i.e., YourProjClass::en_us)
was found, nor classes for anything else in that list, we then try
its superordinate, \*(L"en\*(R" (i.e., YourProjClass::en), and so on thru 
the other language-tags in the given list: \*(L"es\*(R".
(The other language-tags in our example list: 
happen to have no superordinates.)
.Sp
If none of those language-tags leads to loadable classes, we then
try classes derived from YourProjClass\->\fIfallback_languages()\fR and
then if nothing comes of that, we use classes named by
YourProjClass\->\fIfallback_language_classes()\fR.  Then in the (probably
quite unlikely) event that that fails, we just return undef.
.IP "\(bu" 4
\&\f(CW$lh\fR = YourProjClass\->get_handle\fB()\fR || die \*(L"lg-handle?\*(R";
.Sp
When \f(CW\*(C`get_handle\*(C'\fR is called with an empty parameter list, magic happens:
.Sp
If \f(CW\*(C`get_handle\*(C'\fR senses that it's running in program that was
invoked as a \s-1CGI\s0, then it tries to get language-tags out of the
environment variable \*(L"\s-1HTTP_ACCEPT_LANGUAGE\s0\*(R", and it pretends that
those were the languages passed as parameters to \f(CW\*(C`get_handle\*(C'\fR.
.Sp
Otherwise (i.e., if not a \s-1CGI\s0), 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 \f(CW\*(C`get_handle\*(C'\fR.
.Sp
Currently this OS-specific stuff consists of looking in the environment
variables \*(L"\s-1LANG\s0\*(R" and \*(L"\s-1LANGUAGE\s0\*(R"; 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 \*(L"Regional Settings\*(R" (or \*(L"International\*(R"?)
Control Panel.  I welcome further
suggestions for making this do the Right Thing under other operating
systems that support localization.
.Sp
If you're using localization in an application that keeps a configuration
file, you might consider something like this in your project class:
.Sp
.Vb 10
\&  sub get_handle_via_config {
\&    my $class = $_[0];
\&    my $chosen_language = $Config_settings{\*(Aqlanguage\*(Aq};
\&    my $lh;
\&    if($chosen_language) {
\&      $lh = $class\->get_handle($chosen_language)
\&       || die "No language handle for \e"$chosen_language\e" or the like";
\&    } else {
\&      # Config file missing, maybe?
\&      $lh = $class\->get_handle()
\&       || die "Can\*(Aqt get a language handle";
\&    }
\&    return $lh;
\&  }
.Ve
.IP "\(bu" 4
\&\f(CW$lh\fR = YourProjClass::langname\->\fInew()\fR;
.Sp
This constructs a language handle.  You usually \fBdon't\fR call this
directly, but instead let \f(CW\*(C`get_handle\*(C'\fR find a language class to \f(CW\*(C`use\*(C'\fR
and to then call \->new on.
.IP "\(bu" 4
\&\f(CW$lh\fR\->\fIinit()\fR;
.Sp
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 \f(CW$lh\fR\->SUPER::init in it (presumably at the
beginning), so that all classes get a chance to initialize a new object
however they see fit.
.IP "\(bu" 4
YourProjClass\->\fIfallback_languages()\fR
.Sp
\&\f(CW\*(C`get_handle\*(C'\fR appends the return value of this to the end of
whatever list of languages you pass \f(CW\*(C`get_handle\*(C'\fR.  Unless
you override this method, your project class
will inherit Locale::Maketext's \f(CW\*(C`fallback_languages\*(C'\fR, which
currently returns \f(CW\*(C`(\*(Aqi\-default\*(Aq, \*(Aqen\*(Aq, \*(Aqen\-US\*(Aq)\*(C'\fR.
(\*(L"i\-default\*(R" is defined in \s-1RFC\s0 2277).
.Sp
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
\&\f(CW\*(C`get_handle\*(C'\fR will always manage to construct a language
handle (assuming your language classes are in an appropriate
\&\f(CW@INC\fR directory).  Or you can use the next method:
.IP "\(bu" 4
YourProjClass\->\fIfallback_language_classes()\fR
.Sp
\&\f(CW\*(C`get_handle\*(C'\fR 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 \f(CW\*(C`fallback_language_classes\*(C'\fR,
which currently returns an empty list, \f(CW\*(C`()\*(C'\fR.
By setting this to some value (namely, the name of a loadable
language class), you can be sure that
\&\f(CW\*(C`get_handle\*(C'\fR will always manage to construct a language
handle.
.ie n .Sh "The ""maketext"" Method"
.el .Sh "The ``maketext'' Method"
.IX Subsection "The maketext Method"
This is the most important method in Locale::Maketext:
.PP
.Vb 1
\&    $text = $lh\->maketext(I<key>, ...parameters for this phrase...);
.Ve
.PP
This looks in the \f(CW%Lexicon\fR of the language handle
\&\f(CW$lh\fR and all its superclasses, looking
for an entry whose key is the string \fIkey\fR.  Assuming such
an entry is found, various things then happen, depending on the
value found:
.PP
If the value is a scalarref, the scalar is dereferenced and returned
(and any parameters are ignored).
.PP
If the value is a coderef, we return &$value($lh, ...parameters...).
.PP
If the value is a string that \fIdoesn't\fR look like it's in Bracket Notation,
we return it (after replacing it with a scalarref, in its \f(CW%Lexicon\fR).
.PP
If the value \fIdoes\fR look like it's in Bracket Notation, then we compile
it into a sub, replace the string in the \f(CW%Lexicon\fR with the new coderef,
and then we return &$new_sub($lh, ...parameters...).