| Current Path : /proc/3/task/3/cwd/usr/local/Locale-MakePhrase-0.5/blib/man3/ |
| Current File : //proc/3/task/3/cwd/usr/local/Locale-MakePhrase-0.5/blib/man3/Locale::MakePhrase::RuleManager.3pm |
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" 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" ''
'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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "Locale::MakePhrase::RuleManager 3"
.TH Locale::MakePhrase::RuleManager 3 "2006-03-20" "perl v5.10.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"
Locale::MakePhrase::RuleManager \- Language rule sort and evaluation
object.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
The Locale::MakePhrase module uses this plugin module, to implement
the evaluation and sorting phases of text selection. It explains the
rule expression syntax and evaluation procedure.
.PP
It sorts the language rules into a suitable order so that we can
figure out which rule to select, ie. the aim is to sort the rules into
an order so that we can select the first rule.
.PP
It evaluates the program arguments against the expressions in the rule.
.SH "PHRASE SYNTAX"
.IX Header "PHRASE SYNTAX"
To allow an argument to be placed within the middle of a string, we
use square brackets as the notation, plus an underscore, then the
argument number, as in:
.PP
.Vb 1
\& "Please select [_1] files"
.Ve
.PP
where \fI[_1]\fR refers to the first program variable supplied as an
argument with the text to be translated.
.PP
To display square brackets within the text string, you will need to
escape the square bracket by using the \fB~\fR (tilde) character, as in:
.PP
.Vb 1
\& "This is ~[ bracketed text ~]"
.Ve
.PP
this will print:
.PP
.Vb 1
\& This is [ bracketed text ]
.Ve
.PP
Of course, if you need to display the \fB~\fR character, you will need to
use two of them, as in:
.PP
.Vb 1
\& "Tilde needs escaping as in ~~"
.Ve
.PP
which ends up printing:
.PP
.Vb 1
\& Tilde needs escaping as in ~
.Ve
.SH "LINGUISTIC RULES"
.IX Header "LINGUISTIC RULES"
We have coined the term \fIlinguistic rules\fR as a means to describe the
technique which decides which piece of text is displayed, for a given
input text phrase and any/all program arguments.
.PP
To understand why we need to generate linguistic rules, consider the
\&'singular vs. plural' example shown in the \*(L"\s-1REQUIREMENTS\s0\*(R" in Locale::MakePhrase
section.
.PP
In this example, we needed four different text strings, for the
trivial case of what to display for a given program value.
.PP
For other examples, the \s-1URL\s0's mentioned in that section describe why
there is a need for applying rules on a per-language basis (they also
describe why most current language translation systems fail).
.SS "What is a linguistic rule?"
.IX Subsection "What is a linguistic rule?"
A linguistic rule is the evaluation of the context of a phrase by
using program arguments, for a given program string. The arguments
are evaluated left-to-right and top-to-bottom. The first rule to
succeed has its corresponding translated text applied in-place of the
input text.
.PP
Note that if a program string takes no arguments, the rule becomes
rather simplistic (in that no arguments need to be evaluated).
.PP
Rules can be tested in a number of ways. The 'Operators' and
\&'Functions' sections list the available rule expression conjigates
available for use within each rule expression.
.PP
Previously we mentioned that the language translation system used
syntax with the form \fB[_1]\fR. You will notice that we use an
underscore in the placeholder. This may appear to be meaningless, but
as we will see, we use this rule property to help understand how rules
are evaluated.
.SS "Numeric evaluation"
.IX Subsection "Numeric evaluation"
Let's show an example of a simple expression:
.PP
.Vb 1
\& _1 == 0
.Ve
.PP
The use of the underscore signifies that this value is to be
classified as an argument number and is not to be treated literally.
This expression says, 'Does the first argument have a value equal to
zero?'
.PP
[Note that we use double-equals; the double-equals operator will use
a numeric context in the equality test.]
.SS "String evaluation"
.IX Subsection "String evaluation"
Since an argument can also be a string, we could define an expression
to be:
.PP
.Vb 1
\& _1 eq "some text"
.Ve
.PP
Notice that we use a different operator depending on whether the
argument is numeric or a string. This is because we need to be able
to figure out what context the argument needs to be evaluated in.
.PP
[In this case we use 'eq' as the text context equality operator.]
.SS "Alternate argument representation"
.IX Subsection "Alternate argument representation"
In some cases we need to be able to specify the translated string,
based on an alternate representation of the argument. This is handled
by using a function. For example, you may use the term 'houses',
which is the main keyword within your application.
.PP
To handle alternations of the word 'houses' (such as 'house') we can
define an expression of:
.PP
.Vb 1
\& left(_1,5) eq \*(Aqhouse\*(Aq
.Ve
.PP
However, in some cases we will use the terms 'apartments' or 'flats'.
In these cases, we only care if the value is in the plural or singular
case:
.PP
.Vb 1
\& right(_1,1) eq "s"
.Ve
.PP
Thus, we are provided with a set of functions which allow some
manipulation of the argument value, prior to evaluation.
.SS "Multiple arguments"
.IX Subsection "Multiple arguments"
In many cases, more than one argument is supplied (as well as the text
to translate) to Locale::MakePhrase. In those cases, an expression
can be created which tests each argument, as in:
.PP
.Vb 1
\& _1 == 0 && _2 != 1
.Ve
.PP
As we can see here, by using \fB&&\fR, we combine multiple expression
evaluations, into a single rule expression. In this case the
expression is effectively saying \*(L"if argument one is equal to zero \s-1AND\s0
argument two is not equal to one\*(R".
.PP
We support an unlimited number of arguments within the expression
evaluation capability.
.SS "Multiple rule expressions"
.IX Subsection "Multiple rule expressions"
Consider the following exresssions:
.PP
.Vb 3
\& _1 > 0 produces the output "Lots of files"
\& _1 == 0 produces "No files"
\& _1 == 1 produces "One file"
.Ve
.PP
Each expression is a valid, but if we evaluate this set of expressions
in the wrong order, we will never be able to produce the text \*(L"One
file\*(R" as the \fB_1 > 0\fR expression would evaluate to true, before
we try to evaluate the \fB_1 == 1\fR expression.
.PP
To counter this problem, whenever we define a rule expression
(including when there is no rule expression as would be the case when
no arguments are supplied), we must also define a rule priority (where
a larger number gives higher priority).
.PP
Knowing this, let's re-consider the previous set of expressions, this
time adding a suitable priority of evaluation for each expression:
.PP
.Vb 4
\& expression: priority:
\& _1 > 1 1
\& _1 == 0 2
\& _1 == 1 2
.Ve
.PP
Now that we have a rule priority, we can see that the \fB_1 == 0\fR
expression and the \fB_1 == 1\fR expression will get evaluated before the
\&\fB_1 > 1\fR expression.
.PP
You will notice that two rules have the same priority (i.e. we can
have any number of rules having the same priority); in this case, the
rules are evaluated in a non-deterministic (first found, first
evaluated) manner. Thus it is important to make sure that a given
rule expression, has a valid rule priority, for the rule set.
.SS "Rule Syntax"
.IX Subsection "Rule Syntax"
Now that we know what a linguistic rule is, we need to explain some
minor but important points.
.PP
Each symbol in a rule expression needs to be separated with a space,
i.e. this works:
.PP
.Vb 2
\& _1 > 4
\& left(_2,1) eq "f"
.Ve
.PP
this doesn't:
.PP
.Vb 2
\& _1>4
\& left(_2,1)eq"f"
.Ve
.PP
Whenever we are using a string operator, we must enquote the value
that we are testing, i.e. this works:
.PP
.Vb 1
\& _1 eq "fred"
.Ve
.PP
this doesn't:
.PP
.Vb 1
\& _1 eq fred
.Ve
.PP
We support single and double quote characters, including mixed quoting
(for simplistic cases), i.e. these work:
.PP
.Vb 4
\& _1 eq "some text"
\& _1 eq \*(Aqsome text\*(Aq
\& _1 eq "someone\*(Aqs dog"
\& _1 eq \*(Aq"john spoke"\*(Aq
.Ve
.PP
this doesn't (i.e. there is no quote 'escape' capability):
.PP
.Vb 1
\& _1 eq "\e"something\e""
.Ve
.PP
Note that expressions are not unary, as in (this checks if the
first argument has any length):
.PP
.Vb 1
\& length(_1)
.Ve
.PP
rather, they should look like:
.PP
.Vb 1
\& length(_1) > 0
.Ve
.SH "APPLYING RULES TO LANGUAGES"
.IX Header "APPLYING RULES TO LANGUAGES"
.IP "\s-1CAVEAT:\s0" 8
.IX Item "CAVEAT:"
The following description of rule evaluation is correct at the time of
writing. However, as this module evolves, we may alter the
implementation as we get feedback. If you have used this module and
found that the rule evaluation order is not what you expect, please
contact the maintainer.
.PP
So far we have discussed the concept that, a translation exists for a
language/dialect combination. However, the application may not be
translated into the specific language requested by the user. In
these cases, Locale::MakePhrase tries to use fallback languages as
the source language for this translation request. This allows
languages derived from other base languages (eg Spanish and Mexican
share common words) and dialect specific variations of languages (such
as variations of English), to use the parent language as a source for
possible translations.
.PP
Thus whenever a phrase cannot be translated directly into the requested
localisation, Locale::MakePhrase will use a fallback mechanisn for
the input phrase.
.PP
Also, to support variations in output text which can exist in
locale-specific translations, non-expression rules should be evaluated
after rules which have an expression.
.PP
The implementation of which rule to select, has been abstracted into a
seperate module so that you can implement your own process of which
rule is selected based on the available rules. The default
implementation is defined in Locale::MakePhrase::RuleManager. It
contains a description of the current implementation.
.SS "Overview of steps to rule evaluation"
.IX Subsection "Overview of steps to rule evaluation"
.IP "1." 3
Locale::MakePhrase generates a list of rules which are applicable for
required languages (plus any fallback languages).
.IP "2." 3
The rules are sorted by the Locale::MakePhrase::RuleManager module.
.IP "3." 3
Each expression from the sorted rules are evaluated. If the rule
succeeds, the corresponding text is returned. If not, the next rule
is evaluated.
.IP "4." 3
If finally no match is found, the input string is used as the output
string.
.IP "5." 3
Any arguments are then applied to the output string.
.SS "Example rule definitions"
.IX Subsection "Example rule definitions"
Shown below are examples of various rules; some rules have no
expressions and/or arguments; all rules must have at least a priority
of zero or more.
.IP "Rule 1:" 2
.IX Item "Rule 1:"
.Vb 5
\& Language: en_US
\& Input text: Please select some colours.
\& Expression: (none)
\& Priority: 0
\& Output text: Please select some colors.
.Ve
.IP "Rule 2:" 2
.IX Item "Rule 2:"
.Vb 5
\& Language: en
\& Input text: Please select some colours.
\& Expression: (none)
\& Priority: 0
\& Output text: Please select colours.
.Ve
.IP "Rule 3:" 2
.IX Item "Rule 3:"
.Vb 5
\& Language: en_AU
\& Input text: Please select [_1] colours.
\& Expression: (none)
\& Priority: 0
\& Output text: Please select [_1] colours.
.Ve
.IP "Rule 4:" 2
.IX Item "Rule 4:"
.Vb 5
\& Language: en
\& Input text: Please select [_1] colours.
\& Expression: _1 > 0
\& Priority: 0
\& Output text: Select [_1] colours.
.Ve
.IP "An example:" 2
.IX Item "An example:"
Given that the preferred language is 'en_US', if you compare rule 1 vs
rule 2, the linguistic rule evaluation mechanism will be applied to
rule 1 before being applied to rule 2, as it has a higher language-order.
.IP "A further example:" 2
.IX Item "A further example:"
Compare rule 3 vs rule 4. Given that there is no expression associated
with rule 3, but that the 'en' version does have an expression, rule 4
will be evaluated (and found to be true in some cases) before example
3 is evaluated.
.PP
These examples show that it is important to consider the interactions
of the linguistic rules, as they are applied to the current localisation.
.SH "APPLYING ARGUMENTS TO TEXT"
.IX Header "APPLYING ARGUMENTS TO TEXT"
With any text translation system, there comes a time when it is
necessary to apply the values of the arguments 'in situ', replacing the
square-bracket argument number, with the corresponding argument value,
so that the output will say something useful. This happens after all
rules have been applied (if there were any), and after the output text
string has been chosen.
.PP
For example:
.PP
.Vb 2
\& Input text: "Selected [_2] files, [_1] directories"
\& Arguments: 3 21
.Ve
.PP
Apply rules...
.PP
.Vb 2
\& Rule text: "Selected [_2] files, [_1] directories"
\& Output text: "Selected 21 files, 3 directories"
.Ve
.SH "OPERATORS"
.IX Header "OPERATORS"
This is a list of all operators:
.PP
.Vb 10
\& Operator Context Meaning Example
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& == Numeric Equal to _1 == 4
\& != Numeric Not equal to _1 != 2
\& > Numeric Greater than _2 > 1
\& < Numeric Less than _1 < 7
\& >= Numeric Less than or equal to _4 >= 21
\& <= Numeric Greater than or equal to _3 <= 12
\& eq String Equal to _1 eq "some text"
\& ne String Not equal to _2 ne "something else"
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
This is a list of available functions:
.PP
.Vb 10
\& Function Context Meaning Example
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& defined(x) \- Is the argument defined/not\-null, defined(_1)
\& returns 0 or 1
\& length(x) \- Length of value of the argument, length(_1)
\& returns an integer >= 0
\& abs(n) Number Numerical absolute of argument abs(_3)
\& lc(s) String Lowercase version lc(_1)
\& uc(s) String Uppercase version uc(_2)
\& left(s,n) String LHS of argument from start left(_3,4)
\& right(s,n) String RHS of argument from end right(_1,2)
\& substr(s,n) String RHS of argument from start substr(_2,7)
\& substr(s,n,l) String Sub\-part of argument from \*(Aqn\*(Aq, substr(_2,7,4)
\& up to \*(Aql\*(Aq characters
.Ve
.SH "API"
.IX Header "API"
The following functions are used by the Locale::MakePhrase class.
By sub-classing this module, then overloading these functions,
Locale::MakePhrase can use yor custom RuleManager module.
.SS "\fInew()\fP"
.IX Subsection "new()"
Construct a new instance of Locale::MakePhrase::RuleManager object;
arguments are passed to the \fIinit()\fR method.
.ie n .SS "$self init([..])"
.el .SS "\f(CW$self\fP init([..])"
.IX Subsection "$self init([..])"
Allow sub-class a chance to control construction of the object. You
must return a reference to \f(CW$self\fR, to 'allow' the construction to
complete (should you decide to derive from it).
.SS "boolean evaluate($expression,@arguments)"
.IX Subsection "boolean evaluate($expression,@arguments)"
This is the expression evaluation engine. It takes an expression as
described above (for example \fB_1 == 4 && _2 eq 'fred'\fR). It then
takes any program arguments, applying them in-place of the \fB_X\fR
place holders. Finally returning true / false, based on the result
of the evaluation of the expression.
.SS "\e@rules sort(\e@rule_objects,\e@languages)"
.IX Subsection "@rules sort(@rule_objects,@languages)"
The guts of the sorter; by subclassing this module, you can implement
your own sorting routine.
.PP
This module implements the following rules for deciding the sorted
order of the rules. The aim is to return a list which can be
evaluated in-order.
.IP "1." 3
Rules are sorted histest to lowest priority, for the primary language,
for rules which have expressions.
.IP "2." 3
The next available fallback language is chosen as the language to use;
step 1 is repeated.
.IP "3." 3
This process continues until no further fallback languages are available.
.IP "4." 3
The non-expression rules are then evaluated according to the preferred
language.
.IP "5." 3
If that fails, the fallback languages are tried. This continues for
each fallback language.
.ie n .SS "$string apply_arguments($makephrase,$translation,@arguments)"
.el .SS "\f(CW$string\fP apply_arguments($makephrase,$translation,@arguments)"
.IX Subsection "$string apply_arguments($makephrase,$translation,@arguments)"
This applies any/all arguments, to the outgoing text phrase; if the
argument is text, it (optionally) undergoes the translation process;
if the argument is numeric, it is formatted by the Locale::MakePhrase
\&\f(CW\*(C`format_number\*(C'\fR method.
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 758:" 4
.IX Item "Around line 758:"
=cut found outside a pod block. Skipping to next block.
Copyright 2K16 - 2K18 Indonesian Hacker Rulez
;?>)