File Coverage

blib/lib/I22r/Translate/Filter.pm
Criterion Covered Total %
statement 3 3 100.0
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 4 4 100.0


line stmt bran cond sub pod time code
1             package I22r::Translate::Filter;
2 4     4   4075 use Moose::Role;
  4         9152  
  4         37  
3             our $VERSION = '0.96';
4             requires 'apply';
5             requires 'unapply';
6             1;
7              
8             =head1 NAME
9              
10             I22r::Translate::Filter - Role for translation I<filters>.
11              
12             =head1 SYNOPSIS
13              
14             To use a Filter on all translations
15              
16             I22r::Translate->config(
17             filter => [ filter1, filter2, ... ],
18             ... other config ...
19             )
20              
21             To use a Filter with a specific backend
22              
23             I22r::Translate->config(
24             'My::Backend' => {
25             filter => [ filter3, ... ],
26             ... other backend config ...
27             }
28             ... other global config ...
29             }
30              
31             To use a Filter on a specific translation request
32              
33             I22r::Translate->translate_string(
34             src => ..., dest => ..., text => ...,
35             filter => [ filter4, ... ] );
36              
37             (the C<filter> option is also recognized with the
38             C<< I22r::Translate->translate_list >> or
39             C<< I22r::Translate->translate_hash >> methods.
40              
41             =head1 DESCRIPTION
42              
43             Sometimes you do not want to pass a piece of text directly to
44             a translation engine. The text might contain HTML tags or
45             other markup. It might contain proper nouns or other words that
46             you don't intend to translate. Classes that implement the
47             C<I22r::Translate::Filter> role can be used to adjust the
48             text before it is passed to a translation engine, and to
49             unadjust the translator's output.
50              
51             =head1 METHODS
52              
53             =head2 apply
54              
55             =head2 $filter->apply( $request, $key )
56              
57             Accepts a L<I22r::Translate::Request> object and a key from
58             the input. Sanitizes C<< $req->text->{$key} >> for use in a
59             translation backend and keeps a record of what modifications
60             were made, so they can be unmade in the L<"unapply"> method
61             on the translator output.
62              
63             =head2 unapply
64              
65             =head2 $filter->unapply( $request, $key )
66              
67             Modifies backend output in C<< $req->results->{$key}->text >>
68             to restore whatever changes were made to the backend input
69             in the L<"apply"> method.
70              
71             =head1 DEVELOPMENT GUIDE
72              
73             A new filter must implement the C<apply> and C<unapply>
74             methods. The filter must track the modifications made
75             to input in the C<apply> method, including the correct
76             order of modifications, so that those modifications
77             may be undone in the correct order in the C<unapply>
78             method.
79              
80             The source code for the L<I22r::Translate::Filter::Literal>
81             and L<I22r::Translate::Filter::HTML> filters are currently
82             the best places to look for examples of how this can be
83             done.
84              
85             =head1 SEE ALSO
86              
87             L<I22r::Translate>, L<I22r::Translate::Filter::Literal>,
88             L<I22r::Translate::Filter::HTML>
89              
90             =cut