The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Locale-Maketext-Utils-0.22
River stage one • 2 direct dependents • 3 total dependents
1 ++
/ Locale::Maketext::Utils::Phrase::Norm

NAME

Locale::Maketext::Utils::Phrase::Norm - Normalize and perform lint-like analysis of phrases

VERSION

This document describes Locale::Maketext::Utils::Phrase::Norm version 0.1

SYNOPSIS

    use Locale::Maketext::Utils::Phrase::Norm;

    my $norm = Locale::Maketext::Utils::Phrase::Norm->new() || die;
    
    my $result = $norm->normalize('This office has worked [quant,_1,day,days,zero days] without an “accident”.');
    
    # process $result

DESCRIPTION

Analysis, report, and normalize a maketext style phrase based on rules organized into filter modules.

INTERFACE

Main object

new()

Create a new object with all the filters initialized.

Giving no arguments means it will employ all of the default filter modules (documented in "DEFAULT FILTERS").

Otherwise the optional arguments are:

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::'.

e.g. Given 'Locale::Maketext::Utils::Phrase::Norm::MyCoolFilter' you can pass the name 'MyCoolFilter'.

The last argument can be a hashref of options:
    my $norm = Locale::Maketext::Utils::Phrase::Norm->new('My::Filter::XYZ'); # all default filters followed by the My::Filter::XYZ filter
    
    my $norm = Locale::Maketext::Utils::Phrase::Norm->new('My::Filter::XYZ', { 'skip_defaults_when_given_filters' => 1 }); # only do My::Filter::XYZ the filter

Currently there is only the one option as in the example above. The key’s name and example above outline what it is for and how to use it.

carp()s and returns false if there is some sort of failure (documented in "DIAGNOSTICS").

normalize()

Takes a phrase as the only argument and returns a result object (documented in "Result Object").

clear_cache()

The result of normalize() is cached internally so calling it subsequent times with the same string won’t result in it being reprocessed.

This methods clears that cache.

Result Object

get_status()

Returns the status of all the filters:

True means no violations
-1 (i.e. still true) means there were warnings but no violations.
False means there was at least one violation and possibly wanrings.

get_warning_count()

Return the number of warnings from all filters combined.

get_violation_count()

Return the number of violations from all filters combined.

get_filter_results()

Return an array ref of filter result objects (documented in "Filter Result Object").

get_orig_str()

Get the phrase as passed in before any modifications by filters.

get_aggregate_result()

Get the phrase after all filters had a chance to modify it.

filters_modify_string()

Returns true if any of the filters resulted in a string different from what you passed it. False otherwise.

Filter Result Object

Intended for use in a filter module.

See "ANATOMY OF A FILTER MODULE" for more info.

add_violation()

Add a violation.

add_warning()

Add a warning.

get_string_sr()

Returns a SCALAR reference to the modified version of the string that the filter can use to modify the string.

return_value()

returns an array of the status, violation count, warning count, and filter_modifies_string().

It is what the filter’s normalize_maketext_string() should return;

Intended for use when processing results.

Can of course be used in a filter module. See "ANATOMY OF A FILTER MODULE" for more info.

get_status()

Returns the status of the filter:

True means no violations
-1 (i.e. still true) means there were warnings but no violations.
False means there was at least one violation and possibly wanrings.

get_package()

Get the current filter’s package.

get_orig_str()

Get the phrase as passed in before any modifications by the filter.

get_new_str()

Get the phrase after the filter had a chance to modify it.

get_violations()

Return an array ref of violations added via add_violation().

If there are no violations it returns false.

get_warnings()

Return an array ref of violations added via add_warning().

If there are no warnings it returns false.

get_warning_count()

Returns the number of warnings the filter resulted in.

get_violation_count()

Returns the number of violations the filter resulted in.

filter_modifies_string()

Returns true if the filter resulted in a string different from what you passed it. False otherwise.

DEFAULT FILTERS

The included default filters are listed below in the order they are executed by default.

NonBytesStr
WhiteSpace
Grapheme
Ampersand
Markup
Ellipsis
BeginUpper
EndPunc
Consider

ANATOMY OF A FILTER MODULE

A filter module is simply a package that defines a function that does the filtering of the phrase.

normalize_maketext_string()

This gets a single argument the "Filter Result Object" that defines data about the phrase.

That abject can be used to do the actual checks, modifications if any, and return the expected info back (via $filter->return_value).

    package My::Phrase::Filter::X;
    
    sub normalize_maketext_string {
        my ($filter) = @_;

        my $string_sr = $filter->get_string_sr();

        if (${$string_sr} =~ s/X/Y/g) {
              $filter->add_warning('X might be invalid might wanna check that');
        #         or
        #      $filter->add_violation('Text of violation here');
        }

        return $filter->return_value;
    }
    
    1;

It’s a good idea to explain the filter in it’s POD.

DIAGNOSTICS

%s does not implement normalize_maketext_string()

new() was able to load the filter %s but that class does not have a normalize_maketext_string() method.

Can't locate %s.pm in @INC …

new() was not able to load the filter %s, the actual error comes from perl via $@ from Module::Want

Filter list is empty!

After all initialization and no other errors the list of filters is somehow empty.

CONFIGURATION AND ENVIRONMENT

Locale::Maketext::Utils::Phrase::Norm requires no configuration files or environment variables.

DEPENDENCIES

Module::Want, Encode (for the WhiteSpace filter)

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-locale-maketext-utils@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Daniel Muey <http://drmuey.com/cpan_contact.pl>

LICENCE AND COPYRIGHT

Copyright (c) 2012 cPanel, Inc. <copyright@cpanel.net>>. All rights reserved.

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.

DISCLAIMER OF WARRANTY

BECAUSE 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 "AS IS" 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.

IN 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 (INCLUDING 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), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.