.\" 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
.\" ========================================================================
.\"
.IX Title "Locale::Maketext::Utils::Phrase::Norm 3"
.TH Locale::Maketext::Utils::Phrase::Norm 3 "2014-11-18" "perl v5.16.3" "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::Maketext::Utils::Phrase::Norm \- Normalize and perform lint\-like analysis of phrases
.SH "VERSION"
.IX Header "VERSION"
This document describes Locale::Maketext::Utils::Phrase::Norm version 0.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Locale::Maketext::Utils::Phrase::Norm;
\&
\&    my $norm = Locale::Maketext::Utils::Phrase::Norm\->new_source() || die;
\&
\&    my $result = $norm\->normalize(\*(AqThis office has worked [quant,_1,day,days,zero days] without an “accident”.\*(Aq);
\&
\&    # process $result
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Analyze, report, and normalize a maketext style phrase based on rules organized into filter modules.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "Main object"
.IX Subsection "Main object"
\fI\fInew_source()\fI\fR
.IX Subsection "new_source()"
.PP
A “source phrase” is a phrase (suitable for a call to \fImaketext()\fR) in the main locale’s language that we intend to be localizable.
.PP
Typically this is the key of a lexicon’s hash but it can be the value if the main locale lexicon’s key is an “Arbitrary Key”, that is, if the value is different from the key in the main locale’s lexicon.
.PP
\&\fInew_source()\fR creates a new object with all the filters initialized for source phrases.
.PP
Giving no arguments means it will employ all of the default filter modules (documented in \*(L"\s-1DEFAULT FILTERS\*(R"\s0).
.PP
Otherwise the optional arguments are:
.IP "A list of filter module name spaces to run after the default filter modules." 4
.IX Item "A list of filter module name spaces to run after the default filter modules."
If the given module name does not contain any package seperators it will be treated as if it needs prepended with 'Locale::Maketext::Utils::Phrase::Norm::'.
.Sp
e.g. Given 'Locale::Maketext::Utils::Phrase::Norm::MyCoolFilter' you can pass the name 'MyCoolFilter'.
.IP "The last argument can be a hashref of options:" 4
.IX Item "The last argument can be a hashref of options:"
.Vb 1
\&    my $norm = Locale::Maketext::Utils::Phrase::Norm\->new_source(\*(AqMy::Filter::XYZ\*(Aq); # all default filters followed by the My::Filter::XYZ filter
\&
\&    my $norm = Locale::Maketext::Utils::Phrase::Norm\->new_source(\*(AqMy::Filter::XYZ\*(Aq, { \*(Aqskip_defaults_when_given_filters\*(Aq => 1 }); # only do My::Filter::XYZ the filter
.Ve
.Sp
The options are outlined below and are all optional:
.RS 4
.IP "'skip_defaults_when_given_filters'" 4
.IX Item "'skip_defaults_when_given_filters'"
Boolean.
.Sp
When false (default) your filters are appended to the list of default filters.
.Sp
When true the default list of filters is not used.
.IP "'maketext_object'" 4
.IX Item "'maketext_object'"
An object that can be used by filters should they need one to perform their task. Currently, it must have a \fImakethis()\fR method.
.Sp
The main object and filter each have a \fIget_maketext_object()\fR method to fetch this when needed.
.Sp
If you did not specify an argument here \fIget_maketext_object()\fR returns a Locale::Maketext::Utils::Mock object. That means all the cool stuff in your locale object that you might want to use in your filter will not be available.
.IP "'run_extra_filters'" 4
.IX Item "'run_extra_filters'"
Boolean.
.Sp
When false (default) \*(L"extra filters\*(R" are not executed.
.Sp
When true the \*(L"extra filters\*(R" are executed.
.IP "'exclude_filters'" 4
.IX Item "'exclude_filters'"
A hashref of filters to exclude from the object regardless of the list in effect.
.Sp
The key can be the long or short name space of the filter modules and the value must be true for the entry to take effect.
.RE
.RS 4
.RE
.PP
\&\fInew_source()\fR \fIcarp()\fRs and returns false if there is some sort of failure (documented in \*(L"\s-1DIAGNOSTICS\*(R"\s0).
.PP
\fI\fInew_target()\fI\fR
.IX Subsection "new_target()"
.PP
A “target phrase” is the translated version of a given source phrase. This is the value of a non-main-locale lexicon’s hash.
.PP
\&\fInew_target()\fR is just like \fInew_source()\fR but uses a subset of the \*(L"\s-1DEFAULT FILTERS\*(R"\s0 that apply to translations.
.PP
Currently the exclusion of BeginUpper and EndPunc from the \*(L"\s-1DEFAULT FILTERS\*(R"\s0 is what makes up this object.
.PP
\fI\fInormalize()\fI\fR
.IX Subsection "normalize()"
.PP
Takes a phrase as the only argument and returns a result object (documented in \*(L"Result Object\*(R").
.PP
\fI\fIdelete_cache()\fI\fR
.IX Subsection "delete_cache()"
.PP
The result of \fInormalize()\fR is cached internally so calling it subsequent times with the same string won’t result in it being reprocessed.
.PP
This method deletes the internal cache. Returns the hashref that was removed.
.PP
\fI\fIget_maketext_object()\fI\fR
.IX Subsection "get_maketext_object()"
.PP
Returns the object you instantiated the \*(L"Main object\*(R" with.
.PP
If you did not specify an argument a Locale::Maketext::Utils::Mock object is used. That means all the cool stuff in your locale object that you might want to use in your filter will not be available.
.PP
\fI\fIset_maketext_object()\fI\fR
.IX Subsection "set_maketext_object()"
.PP
Takes the same object you’d pass to the constructor method via ‘maketext_object’.
.PP
This is what will be used on subsequent calls to \fInormalize()\fR.
.PP
\fI\fIrun_extra_filters()\fI\fR
.IX Subsection "run_extra_filters()"
.PP
Boolean return value of if we are running \*(L"extra filters\*(R" or not.
.PP
\fI\fIenable_extra_filters()\fI\fR
.IX Subsection "enable_extra_filters()"
.PP
No arguments, enables the running of any \*(L"extra filters\*(R" on subsequent calls to \fInormalize()\fR.
.PP
\fI\fIdisable_extra_filters()\fI\fR
.IX Subsection "disable_extra_filters()"
.PP
No arguments, disables the running of any \*(L"extra filters\*(R" on subsequent calls to \fInormalize()\fR.
.SS "Result Object"
.IX Subsection "Result Object"
\fI\fIget_status()\fI\fR
.IX Subsection "get_status()"
.PP
Returns the status of all the filters:
.IP "True means no violations" 4
.IX Item "True means no violations"
.PD 0
.IP "\-1 (i.e. still true) means there were warnings but no violations." 4
.IX Item "-1 (i.e. still true) means there were warnings but no violations."
.IP "False means there was at least one violation and possibly warnings." 4
.IX Item "False means there was at least one violation and possibly warnings."
.PD
.PP
\fI\fIget_warning_count()\fI\fR
.IX Subsection "get_warning_count()"
.PP
Return the number of warnings from all filters combined.
.PP
\fI\fIget_violation_count()\fI\fR
.IX Subsection "get_violation_count()"
.PP
Return the number of violations from all filters combined.
.PP
\fI\fIget_filter_results()\fI\fR
.IX Subsection "get_filter_results()"
.PP
Return an array ref of filter result objects (documented in \*(L"Filter Result Object\*(R").
.PP
\fI\fIget_orig_str()\fI\fR
.IX Subsection "get_orig_str()"
.PP
Get the phrase as passed in before any modifications by filters.
.PP
\fI\fIget_aggregate_result()\fI\fR
.IX Subsection "get_aggregate_result()"
.PP
Get the phrase after all filters had a chance to modify it.
.PP
\fI\fIfilters_modify_string()\fI\fR
.IX Subsection "filters_modify_string()"
.PP
Returns true if any of the filters resulted in a string different from what you passed it. False otherwise.
.SS "Filter Result Object"
.IX Subsection "Filter Result Object"
\fIIntended for use in a filter module.\fR
.IX Subsection "Intended for use in a filter module."
.PP
See \*(L"\s-1ANATOMY OF A FILTER MODULE\*(R"\s0 for more info.
.PP
\fIadd_violation()\fR
.IX Subsection "add_violation()"
.PP
Add a violation.
.PP
\fIadd_warning()\fR
.IX Subsection "add_warning()"
.PP
Add a warning.
.PP
\fIget_string_sr()\fR
.IX Subsection "get_string_sr()"
.PP
Returns a \s-1SCALAR\s0 reference to the modified version of the string that the filter can use to modify the string.
.PP
\fIreturn_value()\fR
.IX Subsection "return_value()"
.PP
returns an array of the status, violation count, warning count, and \fIfilter_modifies_string()\fR.
.PP
It is what the filter’s \fInormalize_maketext_string()\fR should return;
.PP
\fIget_maketext_object()\fR
.IX Subsection "get_maketext_object()"
.PP
Returns the object you instantiated the \*(L"Main object\*(R" with.
.PP
If you did not specify an argument a Locale::Maketext::Utils::Mock object is used. That means all the cool stuff in your locale object that you might want to use in your filter will not be available.
.PP
\fIrun_extra_filters()\fR
.IX Subsection "run_extra_filters()"
.PP
Returns a boolean value of if we are running extra filters or not.
.PP
.Vb 3
\&    if ( $filter\->run_extra_filters() ) {
\&        # do extra check for violations/warnings here
\&    }
.Ve
.PP
You can use this to check if the filter should run certain tests or not. You can even skip an entire filter by use of \fIreturn_value_noop()\fR.
.PP
\fIreturn_value_noop()\fR
.IX Subsection "return_value_noop()"
.PP
Get an appropriate \fIreturn_value()\fR for when the entire filter falls under the category of \*(L"extra filters\*(R".
.PP
.Vb 1
\&    return $filter\->return_value_noop() if !$filter\->run_extra_filters();
.Ve
.PP
\fIIntended for use when processing results.\fR
.IX Subsection "Intended for use when processing results."
.PP
These can be used in a filter module’s filter code if you find use for them there. See \*(L"\s-1ANATOMY OF A FILTER MODULE\*(R"\s0 for more info.
.PP
\fIget_status()\fR
.IX Subsection "get_status()"
.PP
Returns the status of the filter:
.IP "True means no violations" 4
.IX Item "True means no violations"
.PD 0
.IP "\-1 (i.e. still true) means there were warnings but no violations." 4
.IX Item "-1 (i.e. still true) means there were warnings but no violations."
.IP "False means there was at least one violation and possibly warnings." 4
.IX Item "False means there was at least one violation and possibly warnings."
.PD
.PP
\fIget_package()\fR
.IX Subsection "get_package()"
.PP
Get the current filter’s package.
.PP
\fIget_orig_str()\fR
.IX Subsection "get_orig_str()"
.PP
Get the phrase as passed in before any modifications by the filter.
.PP
\fIget_new_str()\fR
.IX Subsection "get_new_str()"
.PP
Get the phrase after the filter had a chance to modify it.
.PP
\fIget_violations()\fR
.IX Subsection "get_violations()"
.PP
Return an array ref of violations added via \fIadd_violation()\fR.
.PP
If there are no violations it returns false.
.PP
\fIget_warnings()\fR
.IX Subsection "get_warnings()"
.PP
Return an array ref of violations added via \fIadd_warning()\fR.
.PP
If there are no warnings it returns false.
.PP
\fIget_warning_count()\fR
.IX Subsection "get_warning_count()"
.PP
Returns the number of warnings the filter resulted in.
.PP
\fIget_violation_count()\fR
.IX Subsection "get_violation_count()"
.PP
Returns the number of violations the filter resulted in.
.PP
\fIfilter_modifies_string()\fR
.IX Subsection "filter_modifies_string()"
.PP
Returns true if the filter resulted in a string different from what you passed it. False otherwise.
.SH "DEFAULT FILTERS"
.IX Header "DEFAULT FILTERS"
The included default filters are listed below in the order they are executed by default.
.IP "NonBytesStr" 4
.IX Item "NonBytesStr"
.PD 0
.IP "WhiteSpace" 4
.IX Item "WhiteSpace"
.IP "Grapheme" 4
.IX Item "Grapheme"
.IP "Ampersand" 4
.IX Item "Ampersand"
.IP "Markup" 4
.IX Item "Markup"
.IP "Ellipsis" 4
.IX Item "Ellipsis"
.IP "BeginUpper" 4
.IX Item "BeginUpper"
.IP "EndPunc" 4
.IX Item "EndPunc"
.IP "Consider" 4
.IX Item "Consider"
.IP "Escapes" 4
.IX Item "Escapes"
.IP "Compiles" 4
.IX Item "Compiles"
.PD
.SS "extra filters"
.IX Subsection "extra filters"
It may be desireable for some filters to not run by default but still be easily applied when needed.
.PP
The extra filter mechanism allows for this as documented specifically throught this \s-1POD.\s0
.PP
No filters fall under \*(L"extra filters\*(R" currently.
.SH "ANATOMY OF A FILTER MODULE"
.IX Header "ANATOMY OF A FILTER MODULE"
A filter module is simply a package that defines a function that does the filtering of the phrase.
.SS "\fInormalize_maketext_string()\fP"
.IX Subsection "normalize_maketext_string()"
This gets passed a single argument: the \*(L"Filter Result Object\*(R" that defines data about the phrase.
.PP
That object can be used to do the actual checks, modifications if any, and return the expected info back (via \f(CW$filter\fR\->return_value).
.PP
.Vb 1
\&    package My::Phrase::Filter::X;
\&
\&    sub normalize_maketext_string {
\&        my ($filter) = @_;
\&
\&        my $string_sr = $filter\->get_string_sr();
\&
\&        if (${$string_sr} =~ s/X/[comment,unexpected X]/g) {
\&              $filter\->add_warning(\*(AqX might be invalid might wanna check that\*(Aq);
\&        #         or
\&        #      $filter\->add_violation(\*(AqText of violation here\*(Aq);
\&        }
\&
\&        return $filter\->return_value;
\&    }
\&
\&    1;
.Ve
.PP
It’s a good idea to explain the filter in it’s \s-1POD.\s0 Check out _Stub for some boilerplate.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """%s does not implement normalize_maketext_string()""" 4
.el .IP "\f(CW%s does not implement normalize_maketext_string()\fR" 4
.IX Item "%s does not implement normalize_maketext_string()"
The constructor method was able to load the filter \f(CW%s\fR but that class does not have a \fInormalize_maketext_string()\fR method.
.ie n .IP """Can\*(Aqt locate %s.pm in @INC …""" 4
.el .IP "\f(CWCan\*(Aqt locate %s.pm in @INC …\fR" 4
.IX Item "Cant locate %s.pm in @INC …"
The constructor method was not able to load the filter \f(CW%s\fR, the actual error comes from perl via $@ from Module::Want
.ie n .IP """Filter list is empty!""" 4
.el .IP "\f(CWFilter list is empty!\fR" 4
.IX Item "Filter list is empty!"
After all initialization and no other errors the list of filters is somehow empty.
.ie n .IP """Given maketext object does not have a makethis() method.""" 4
.el .IP "\f(CWGiven maketext object does not have a makethis() method.\fR" 4
.IX Item "Given maketext object does not have a makethis() method."
The value of the maketext_object key you passed to the constructor method or the value passed to \fIset_maketext_object()\fR does not define a \fImakethis()\fR method.
.ie n .IP """Given maketext object is not a reference.""" 4
.el .IP "\f(CWGiven maketext object is not a reference.\fR" 4
.IX Item "Given maketext object is not a reference."
The value of the maketext_object key you passed to the constructor method or the value passed to \fIset_maketext_object()\fR is not an object.
.ie n .IP """new() is deprecated, use new_source() instead""" 4
.el .IP "\f(CWnew() is deprecated, use new_source() instead\fR" 4
.IX Item "new() is deprecated, use new_source() instead"
Your code uses the deprecated constructor and needs to be updated.
.ie n .IP """You must pass a value to normalize()""" 4
.el .IP "\f(CWYou must pass a value to normalize()\fR" 4
.IX Item "You must pass a value to normalize()"
Your code called \fInormalize()\fR without giving it a value to, well, normalize.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Locale::Maketext::Utils::Phrase::Norm requires no configuration files or environment variables.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
Module::Want, Encode (for the WhiteSpace filter)
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.PP
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-locale\-maketext\-utils@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Locale::Maketext::Utils::Phrase::cPanel
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel Muey  \f(CW\*(C`<http://drmuey.com/cpan_contact.pl>\*(C'\fR
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2012 cPanel, Inc. \f(CW\*(C`<copyright@cpanel.net>>\*(C'\fR. All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself, either Perl version 5.10.1 or, at your option,
any later version of Perl 5 you may have available.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE \*(L"AS IS\*(R" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.\s0
.PP
\&\s-1IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE \s0(\s-1INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE\s0), \s-1EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.\s0