blib/lib/WebService/MyGengo/Job.pm untested

filter: Statementstmt 0.0% 0 / 84 Branchbran 0.0% 0 / 2 Conditioncond 0.0% 0 / 5 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 0.0% 0 / 20 Podpod 0.0% 0 / 16 totaltotal 0.0% 0 / 130 CC 1 SCAR 6.9
CC
1
Cov
0%
BEGIN
2.0
id
2.0
_set_comments
2.0
CRAP 2.0
1 package WebService::MyGengo::Job;
2  
3 use Moose;
4 use namespace::autoclean;
5  
6 BEGIN { extends 'WebService::MyGengo::Base' };
7  
8 use Scalar::Util qw(blessed);
9 use DateTime::Format::Strptime;
10  
11 =head1 NAME
12  
13 WebService::MyGengo::Job - A translation Job in the myGengo system.
14  
15 =head1 SYNOPSIS
16  
17 my $job = WebService::MyGengo::Job->new( { lc_src => 'en', lc_tgt => 'ja'... } );
18  
19 my $client = WebService::MyGengo::Client->new( $params );
20 $job = $client->get_job( 123 );
21  
22 =head1 ATTRIBUTES
23  
24 See L<http://mygengo.com/api/developer-docs/payloads/> for more information,
25 as well as the various tests in t/*.t.
26  
27 =head2 job_id|id (Int)
28  
29 A unique identifier for the Job.
30  
31 =head2 group_id (Int)
32  
33 A unique identifier for a group of Jobs.
34  
35 See L<WebService::MyGengo::Client>'s `submit_jobs` method.
36  
37 =head2 slug (Str)
38  
39 Undocumented. Appears to act as a 'title' for the Job.
40  
41 =head2 body_src (Str)
42  
43 The text to be translated in UTF-8 encoding.
44  
45 =head2 body_tgt (Str)
46  
47 The translation result text in UTF-8 encoding.
48  
49 If the Job has not been completed, this will be en empty string.
50  
51 =head2 lc_src (Str)
52  
53 2-character ISO code for the source language.
54  
55 =head2 lc_tgt (Str)
56  
57 2-character ISO code for the target language.
58  
59 =head2 custom_data (Str)
60  
61 Up to 1024 bytes of arbitrary text describing the Job in UTF-8 encoding.
62  
63 =head2 unit_count (Int)
64  
65 The number of units (words or characters) in the body_src.
66  
67 =head2 tier (Str)
68  
69 The tier under which this Job is being translated: machine, standard, pro, ultra, ultra_pro
70  
71 =head2 credits (Num)
72  
73 A decimal figure representing how many credits this Job will cost.
74  
75 =head2 status (Str)
76  
77 The Job's status: unpaid, available, pending, reviewable, revising, approved, rejected, cancelled, held
78  
79 =head2 eta (DateTime::Duration)
80  
81 A L<DateTime::Duration> object representing an estimate of when the Job will be
82 completed.
83  
84 Usually used as `$job->eta->seconds`.
85  
86 =head2 ctime (DateTime)
87  
88 A L<DateTime> representing the Job's creation date and time.
89  
90 =head2 force (Bool)
91  
92 Whether to force a Job to be translated, even if a Job with the same body_src
93 already exists.
94  
95 =head2 use_preferred (Bool)
96  
97 Whether to only allow a "preferred translator" to work this Job.
98  
99 =head2 auto_approve (Bool)
100  
101 Whether to automatically approve this Job once the translation is completed.
102  
103 =head2 mt (Bool)
104  
105 Whether the body_tgt was translated via machine translation.
106  
107 =head2 callback_url (Str)
108  
109 A URL to which events related to this Job should be posted.
110  
111 =head2 captcha_url (Str)
112  
113 A URL pointing to a captcha image.
114  
115 This will be set on Jobs in 'reviewable' status and must be submitted when
116 rejecting a Job.
117  
118 See L<WebService::MyGengo::Client>'s `reject_job` method.
119  
120 =head2 preview_url (Str)
121  
122 A URL pointing to a graphical representation of the translated text.
123  
124 =cut
125 sub id { shift->job_id }
126 has [qw/job_id group_id/] => ( is => 'ro' , isa => 'Int' );
127 has 'slug' => ( is => 'ro' , isa => 'Str', default => 0 );
128 has 'body_src' => ( is => 'ro' , isa => 'Str', required => 1 );
129 has 'body_tgt' => ( is => 'ro' , isa => 'WebService::MyGengo::body_tgt' );
130 has [qw/lc_src lc_tgt/] => (
131 is => 'ro'
132 , isa => 'WebService::MyGengo::LanguageCode'
133 , required => 1
134 );
135 has 'custom_data' => ( is => 'ro', isa => 'Str' );
136 has 'unit_count' => ( is => 'ro' , isa => 'Int' );
137 has 'tier' => ( is => 'ro' , isa => 'WebService::MyGengo::Tier', required => 1 );
138 has 'credits' => ( is => 'ro' , isa => 'WebService::MyGengo::Num' );
139 has 'status' => (
140 is => 'ro'
141 , isa => 'WebService::MyGengo::Job::Status'
142 , default => 'available'
143 );
144 has 'eta' => (
145 is => 'ro'
146 , isa => 'WebService::MyGengo::DateTime::Duration'
147 , coerce => 1
148 );
149 has 'ctime' => (
150 is => 'ro'
151 , isa => 'WebService::MyGengo::DateTime'
152 , coerce => 1
153 , trigger => sub {
154 shift->ctime->set_formatter(
155 DateTime::Format::Strptime->new( pattern => '%F %H:%M:%S %Z' )
156 );
157 }
158 );
159 has [qw/force use_preferred auto_approve mt/] => (
160 is => 'ro'
161 , isa => 'Bool'
162 , default => 0
163 );
164 has [qw/callback_url captcha_url preview_url/] => (
165 is => 'ro'
166 , isa => 'Maybe[Str]' # todo URI constraint/coercion
167 );
168  
169 =head2 comment (WebService::MyGengo::Comment|Undef)
170  
171 This is only here to support the 'comment' option for the constructor.
172  
173 Returns the most recently-added comment.
174  
175 =cut
176 has comment => (
177 is => 'ro'
178 , isa => 'WebService::MyGengo::Comment|Undef'
179 # todo Results in coercion errors
180 # , isa => 'Maybe[WebService::MyGengo::Comment]'
181 , coerce => 1
182 , lazy => 1
183 , clearer => '_clear_comment'
184 , default => sub {
185 my ( $self ) = ( shift );
186 my $c = $self->get_comment( $self->comment_count - 1 );
187 return blessed($c) ? $c->body : undef;
188 }
189 , trigger => sub {
190 my ( $self ) = ( shift );
191 @_ or next;
192 $self->_add_comment( @_ );
193 $self->_clear_comment; # Refresh comment on every call
194 }
195 );
196  
197 =head2 comments (Array)
198  
199 A list of L<WebService::MyGengo::Comment> objects for this Job.
200  
201 Provides:
202  
203 =over
204  
205 =item fetched_comments - Returns true if comments have been fetched from the API
206  
207 =item has_comments - Returns the number of comments in the list
208  
209 =item comment_count - Returns the number of comments in the list
210  
211 =item get_comment($id) - Returns a specific comment by list index
212  
213 =back
214  
215 =cut
216 has '_comments' => (
217 traits => ['Array']
218 , is => 'ro'
219 , isa => 'WebService::MyGengo::CommentThread'
220 , coerce => 1
221 , default => sub { [] }
222 , trigger => sub { shift->_set_fetched_comments(1) }
223 , handles => {
224 comments => 'elements'
225 , comment_count => 'count'
226 , has_comments => 'count' # See fetched_comments
227 , get_comment => 'get'
228 , _add_comment => 'push' # todo immutable object
229 , _clear_comments => 'clear'
230 }
231 );
232 has fetched_comments => (
233 is => 'rw'
234 , isa => 'Bool'
235 , init_arg => undef
236 , lazy => 1
237 , default => 0
238 , writer => '_set_fetched_comments'
239 );
240  
241 #=head2 _set_comments( ArrayRef[WebService::MyGengo::Comment] )
242 #
243 #Replace the existing comment collection with a new one.
244 #
245 #Returns the new comment list.
246 #
247 #todo It would be nice to have an immutable object...
248 #
249 #=cut
250 sub _set_comments {
251 my ( $self, $comments ) = ( shift, @_ );
252  
253 $self->_clear_comments;
254 $self->_add_comment( $_ ) foreach ( @$comments );
255  
256 return $self->comments;
257 }
258  
259 =head2 revisions (Array)
260  
261 A list of L<WebService::MyGengo::Revision> objects for this Job.
262  
263 Provides:
264  
265 =over
266  
267 =item fetched_revisions - Returns true if revisions have been fetched from the API
268  
269 =item has_revisions - Returns the number of revisions in the list
270  
271 =item revision_count - Returns the number of revisions in the list
272  
273 =item get_revision($id) - Returns a specific revision by list index
274  
275 =back
276  
277 =cut
278 has '_revisions' => (
279 traits => ['Array']
280 , is => 'ro'
281 , isa => 'ArrayRef[WebService::MyGengo::Revision]'
282 , default => sub { [] }
283 , trigger => sub { shift->_set_fetched_revisions(1) }
284 , handles => {
285 revisions => 'elements'
286 , revision_count => 'count'
287 , has_revisions => 'count' # See fetched_revisions
288 , get_revision => 'get'
289 , _add_revision => 'push' # todo immutable object
290 , _clear_revisions => 'clear'
291 }
292 );
293 has fetched_revisions => (
294 is => 'rw'
295 , isa => 'Bool'
296 , init_arg => undef
297 , lazy => 1
298 , default => 0
299 , writer => '_set_fetched_revisions'
300 );
301  
302 #=head2 _set_revisions( ArrayRef[WebService::MyGengo::Comment] )
303 #
304 #Replace the existing revision collection with a new one.
305 #
306 #Returns the new revision list.
307 #
308 #todo It would be nice to have an immutable object...
309 #
310 #=cut
311 sub _set_revisions {
312 my ( $self, $revs ) = ( shift, @_ );
313  
314 $self->_clear_revisions;
315 $self->_add_revision( $_ ) foreach ( @$revs );
316  
317 return $self->revisions;
318 }
319  
320 =head2 feedback (WebService::MyGengo::Feedback|Undef)
321  
322 A L<WebService::MyGengo::Feedback> object for this Job.
323  
324 Provides:
325  
326 =over
327  
328 =item fetched_feedback - Returns true if feedback has been fetched from the API
329  
330 =item has_feedback - Returns true if feedback is defined
331  
332 =back
333  
334 =cut
335 has 'feedback' => (
336 is => 'rw'
337 , isa => 'Maybe[WebService::MyGengo::Feedback]'
338 , lazy => 1
339 , default => undef
340 , trigger => sub { shift->_set_fetched_feedback(1) }
341 , predicate => 'has_feedback'
342 , writer => '_set_feedback'
343 );
344 has fetched_feedback => (
345 is => 'rw'
346 , isa => 'Bool'
347 , init_arg => undef
348 , lazy => 1
349 , default => 0
350 , writer => '_set_fetched_feedback'
351 );
352  
353 =head1 METHODS
354  
355 =head2 is_(unpaid|available|pending|reviewable|revising|approved|rejected|cancell?ed|held)
356  
357 Returns true if the Job is of the given status, false otherwise
358  
359 =cut
360 sub _is_status { shift->status eq shift }
361 sub is_unpaid { shift->_is_status('unpaid') }
362 sub is_available { shift->_is_status('available') }
363 sub is_pending { shift->_is_status('pending') }
364 sub is_reviewable { shift->_is_status('reviewable') }
365 sub is_revising { shift->_is_status('revising') }
366 sub is_approved { shift->_is_status('approved') }
367 sub is_rejected { shift->_is_status('rejected') }
368 sub is_canceled { shift->_is_status('cancelled') }
369 sub is_cancelled { shift->is_canceled }
370 sub is_held { shift->_is_status('held') }
371  
372 #=head2 _build_attributes_to_serialize
373 #
374 #The list of attributes to serialize via the `to_hash` method.
375 #
376 #See: L<WebService::MyGengo::Base>
377 #
378 #todo Use traits
379 #
380 #=cut
381 sub _build_attributes_to_serialize {
382 return [qw/
383 body_src lc_src lc_tgt tier force comment use_preferred
384 callback_url auto_approve custom_data
385 /];
386 }
387  
388 =head2 around to_hash
389  
390 HACKS: The eta value (a L<DateTime::Duration>) does not stringify to a
391 meaningful value, so we convert it to seconds here.
392  
393 We also remove the feedback entry.
394  
395 See: L<WebService::MyGengo::Base>
396  
397 =cut
398 #todo Use traits for serialization
399 around to_hash => sub {
400 my ( $orig, $self ) = ( shift, shift );
401  
402 my $hash = $self->$orig( @_ );
403  
404 # todo This assumes the duration object was built from seconds,
405 # which ours always are. Using a DateTime::Format::Duration
406 # with a '%s' is safer.
407 defined $hash->{eta} and $hash->{eta} = $self->eta->seconds;
408  
409 delete $hash->{feedback};
410  
411 return $hash;
412 };
413  
414  
415 __PACKAGE__->meta->make_immutable();
416 1;
417  
418 =head1 TODO
419  
420 * We really need to make a decision in the immutability of this object.
421 Is it just pedantic to try and attempt it? We could save time using
422 mutability. This could affect caching, though.
423  
424 =head1 SEE ALSO
425  
426 L<http://mygengo.com/api/developer-docs/methods/translate-job-id-get/>
427  
428 =head1 AUTHOR
429  
430 Nathaniel Heinrichs
431  
432 =head1 LICENSE
433  
434 Copyright (c) 2011, Nathaniel Heinrichs <nheinric-at-cpan.org>.
435 All rights reserved.
436  
437 This library is free software. You can redistribute it and/or modify
438 it under the same terms as Perl itself.
439  
440 =cut