.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.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" ''
.    ds C`
.    ds C'
'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 (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "Preferred 3pm"
.TH Preferred 3pm "2003-12-14" "perl v5.18.1" "User Contributed Perl Documentation"
.\" 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"
Lingua::Preferred \- Perl extension to choose a language
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Lingua::Preferred qw(which_lang acceptable_lang);
\&  my @wanted = qw(en de fr it de_CH);
\&  my @available = qw(fr it de);
\&
\&  my $which = which_lang(\e@wanted, \e@available);
\&  print "language $which is the best of those available\en";
\&
\&  foreach (qw(en_US fr nl de_DE)) {
\&      print "language $_ is acceptable\en"
\&        if acceptable_lang(\e@wanted, $_);
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Often human-readable information is available in more than one
language.  Which should you use?  This module provides a way for the
user to specify possible languages in order of preference, and then to
pick the best language of those available.  Different 'dialects' given
by the 'territory' part of the language specifier (such as en, en_GB,
and en_US) are also supported.
.PP
The routine \f(CW\*(C`which_lang()\*(C'\fR picks the best language from a list of
alternatives.  The arguments are:
.IP "\(bu" 4
a reference to a list of preferred languages (first is best).  Here, a
language is a string like \f(CW\*(Aqen\*(Aq\fR or \f(CW\*(Aqfr_CA\*(Aq\fR.  (\f(CW\*(Aqfr_*\*(Aq\fR can also
be given \- see below.)  \f(CW\*(AqC\*(Aq\fR (named for the Unix 'C' locale) matches
any language.
.IP "\(bu" 4
a reference to non-empty list of available languages.  Here, a
language can be like \f(CW\*(Aqen\*(Aq\fR, \f(CW\*(Aqen_CA\*(Aq\fR, or \f(CW\*(C`undef\*(C'\fR meaning 'unknown'.
.PP
The return code is which language to use.  This will always be an
element of the available languages list.
.PP
The cleverness of this module (if you can call it that) comes from
inferring implicit language preferences based on the explicit list
passed in.  For example, if you say that en is acceptable, then en_IE
and en_DK will presumably be acceptable too (but not as good as just
plain en).  If you give your language as en_US, then en is almost as
good, with the other dialects of en following soon afterwards.
.PP
If there is a tie between two choices, as when two dialects of the
same language are available and neither is explicitly preferred, or
when none of the available languages appears in the user's list,
then the choice appearing earlier in the available list is preferred.
.PP
Sometimes, the automatic inferring of related dialects is not what you
want, because a language dialect may be very different to the 'main'
language, for example Swiss German or some forms of English.  For this
case, the special form 'XX_*' is available. If you dislike Mexican
Spanish (as a completely arbitrary example), then \f(CW\*(C`[ \*(Aqes\*(Aq, \*(Aqes_*\*(Aq,
\&\*(Aqes_MX\*(Aq ]\*(C'\fR would rank this dialect below any other dialect of es (but
still acceptable).  You don't have to explicitly list every other
dialect of Spanish before es_MX.
.PP
So for example, supposing \f(CW@avail\fR contains the languages available:
.IP "\(bu" 4
You know English and prefer \s-1US\s0 English:
.Sp
.Vb 1
\&    $which = which_lang([ \*(Aqen_US\*(Aq ], \e@avail);
.Ve
.IP "\(bu" 4
You know English and German, German/Germany is preferred:
.Sp
.Vb 1
\&    $which = which_lang([ \*(Aqen\*(Aq, \*(Aqde_DE\*(Aq ], \e@avail);
.Ve
.IP "\(bu" 4
You know English and German, but preferably not Swiss German:
.Sp
.Vb 1
\&    $which = which_lang([ \*(Aqen\*(Aq, \*(Aqde\*(Aq, \*(Aqde_*\*(Aq, \*(Aqde_CH\*(Aq ], \e@avail);
.Ve
.Sp
Here any dialect of German (eg de_DE, de_AT) is preferable to de_CH.
.Sp
Whereas \f(CW\*(C`which_lang()\*(C'\fR picks the best language from a list of
alternatives, \f(CW\*(C`acceptable_lang()\*(C'\fR answers whether a single
language is included (explicitly or implicitly) in the list of wanted
languages.  It adds the implicit dialects in the same way.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ed Avis, ed@membled.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1).
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 258:" 4
.IX Item "Around line 258:"
You forgot a '=back' before '=head1'