README
1NAME
2
3 Data::Object::Try
4
5ABSTRACT
6
7 Try Class for Perl 5
8
9SYNOPSIS
10
11 use strict;
12 use warnings;
13 use routines;
14
15 use Data::Object::Try;
16
17 my $try = Data::Object::Try->new;
18
19 $try->call(fun (@args) {
20 # try something
21
22 return time;
23 });
24
25 $try->catch('Example::Exception', fun ($caught) {
26 # caught an exception
27
28 return;
29 });
30
31 $try->default(fun ($caught) {
32 # catch the uncaught
33
34 return;
35 });
36
37 $try->finally(fun (@args) {
38 # always run after try/catch
39
40 return;
41 });
42
43 my @args;
44
45 my $result = $try->result(@args);
46
47DESCRIPTION
48
49 This package provides an object-oriented interface for performing
50 complex try/catch operations.
51
52ATTRIBUTES
53
54 This package has the following attributes:
55
56 arguments
57
58 arguments(ArrayRef)
59
60 This attribute is read-only, accepts (ArrayRef) values, and is
61 optional.
62
63 invocant
64
65 invocant(Object)
66
67 This attribute is read-only, accepts (Object) values, and is optional.
68
69 on_catch
70
71 on_catch(ArrayRef[CodeRef])
72
73 This attribute is read-write, accepts (ArrayRef[CodeRef]) values, and
74 is optional.
75
76 on_default
77
78 on_default(CodeRef)
79
80 This attribute is read-write, accepts (CodeRef) values, and is
81 optional.
82
83 on_finally
84
85 on_finally(CodeRef)
86
87 This attribute is read-write, accepts (CodeRef) values, and is
88 optional.
89
90 on_try
91
92 on_try(CodeRef)
93
94 This attribute is read-write, accepts (CodeRef) values, and is
95 optional.
96
97METHODS
98
99 This package implements the following methods:
100
101 call
102
103 call(Str | CodeRef $arg) : Object
104
105 The call method takes a method name or coderef, registers it as the
106 tryable routine, and returns the object. When invoked, the callback
107 will received an invocant if one was provided to the constructor, the
108 default arguments if any were provided to the constructor, and whatever
109 arguments were provided by the invocant.
110
111 call example #1
112
113 use routines;
114
115 my $try = Data::Object::Try->new;
116
117 $try->call(fun (@args) {
118
119 return [@args];
120 });
121
122 callback
123
124 callback(Str | CodeRef $arg) : CodeRef
125
126 The callback method takes a method name or coderef, and returns a
127 coderef for registration. If a coderef is provided this method is
128 mostly a passthrough.
129
130 callback example #1
131
132 use routines;
133
134 my $try = Data::Object::Try->new;
135
136 $try->callback(fun (@args) {
137
138 return [@args];
139 });
140
141 callback example #2
142
143 package Example;
144
145 use Moo;
146 use routines;
147
148 fun test(@args) {
149
150 return [@args];
151 }
152
153 package main;
154
155 my $try = Data::Object::Try->new(
156 invocant => Example->new
157 );
158
159 $try->callback('test');
160
161 catch
162
163 catch(Str $isa, Str | CodeRef $arg) : Any
164
165 The catch method takes a package or ref name, and when triggered checks
166 whether the captured exception is of the type specified and if so
167 executes the given callback.
168
169 catch example #1
170
171 use routines;
172
173 my $try = Data::Object::Try->new;
174
175 $try->call(fun (@args) {
176
177 die $try;
178 });
179
180 $try->catch('Data::Object::Try', fun (@args) {
181
182 return [@args];
183 });
184
185 default
186
187 default(Str | CodeRef $arg) : Object
188
189 The default method takes a method name or coderef and is triggered if
190 no catch conditions match the exception thrown.
191
192 default example #1
193
194 use routines;
195
196 my $try = Data::Object::Try->new;
197
198 $try->call(fun (@args) {
199
200 die $try;
201 });
202
203 $try->default(fun (@args) {
204
205 return [@args];
206 });
207
208 execute
209
210 execute(CodeRef $arg, Any @args) : Any
211
212 The execute method takes a coderef and executes it with any given
213 arguments. When invoked, the callback will received an invocant if one
214 was provided to the constructor, the default arguments if any were
215 provided to the constructor, and whatever arguments were passed
216 directly to this method.
217
218 execute example #1
219
220 use routines;
221
222 my $try = Data::Object::Try->new(
223 invocant => Example->new,
224 arguments => [1,2,3]
225 );
226
227 $try->execute(fun (@args) {
228
229 return [@args];
230 });
231
232 finally
233
234 finally(Str | CodeRef $arg) : Object
235
236 The finally method takes a package or ref name and always executes the
237 callback after a try/catch operation. The return value is ignored. When
238 invoked, the callback will received an invocant if one was provided to
239 the constructor, the default arguments if any were provided to the
240 constructor, and whatever arguments were provided by the invocant.
241
242 finally example #1
243
244 use routines;
245
246 my $try = Data::Object::Try->new(
247 invocant => Example->new,
248 arguments => [1,2,3]
249 );
250
251 $try->call(fun (@args) {
252
253 return $try;
254 });
255
256 $try->finally(fun (@args) {
257
258 $try->{'$finally'} = [@args];
259 });
260
261 maybe
262
263 maybe() : Object
264
265 The maybe method registers a default catch condition that returns
266 falsy, i.e. an empty string, if an exception is encountered.
267
268 maybe example #1
269
270 use routines;
271
272 my $try = Data::Object::Try->new;
273
274 $try->call(fun (@args) {
275
276 die $try;
277 });
278
279 $try->maybe;
280
281 no_catch
282
283 no_catch() : Object
284
285 The no_catch method removes any configured catch conditions and returns
286 the object.
287
288 no_catch example #1
289
290 use routines;
291
292 my $try = Data::Object::Try->new;
293
294 $try->call(fun (@args) {
295
296 die $try;
297 });
298
299 $try->catch('Data::Object::Try', fun (@args) {
300
301 return [@args];
302 });
303
304 $try->no_catch;
305
306 no_default
307
308 no_default() : Object
309
310 The no_default method removes any configured default condition and
311 returns the object.
312
313 no_default example #1
314
315 use routines;
316
317 my $try = Data::Object::Try->new;
318
319 $try->call(fun (@args) {
320
321 die $try;
322 });
323
324 $try->default(fun (@args) {
325
326 return [@args];
327 });
328
329 $try->no_default;
330
331 no_finally
332
333 no_finally() : Object
334
335 The no_finally method removes any configured finally condition and
336 returns the object.
337
338 no_finally example #1
339
340 use routines;
341
342 my $try = Data::Object::Try->new(
343 invocant => Example->new,
344 arguments => [1,2,3]
345 );
346
347 $try->call(fun (@args) {
348
349 return $try;
350 });
351
352 $try->finally(fun (@args) {
353
354 $try->{'$finally'} = [@args];
355 });
356
357 $try->no_finally;
358
359 no_try
360
361 no_try() : Object
362
363 The no_try method removes any configured try operation and returns the
364 object.
365
366 no_try example #1
367
368 use routines;
369
370 my $try = Data::Object::Try->new;
371
372 $try->call(fun (@args) {
373
374 return [@args];
375 });
376
377 $try->no_try;
378
379 result
380
381 result(Any @args) : Any
382
383 The result method executes the try/catch/default/finally logic and
384 returns either 1) the return value from the successfully tried
385 operation 2) the return value from the successfully matched catch
386 condition if an exception was thrown 3) the return value from the
387 default catch condition if an exception was thrown and no catch
388 condition matched. When invoked, the try and finally callbacks will
389 received an invocant if one was provided to the constructor, the
390 default arguments if any were provided to the constructor, and whatever
391 arguments were passed directly to this method.
392
393 result example #1
394
395 use routines;
396
397 my $try = Data::Object::Try->new;
398
399 $try->call(fun (@args) {
400
401 return [@args];
402 });
403
404 $try->result;
405
406 result example #2
407
408 use routines;
409
410 my $try = Data::Object::Try->new;
411
412 $try->call(fun (@args) {
413
414 return [@args];
415 });
416
417 $try->result(1..5);
418
419AUTHOR
420
421 Al Newkirk, awncorp@cpan.org
422
423LICENSE
424
425 Copyright (C) 2011-2019, Al Newkirk, et al.
426
427 This is free software; you can redistribute it and/or modify it under
428 the terms of the The Apache License, Version 2.0, as elucidated in the
429 "license file"
430 <https://github.com/iamalnewkirk/data-object-try/blob/master/LICENSE>.
431
432PROJECT
433
434 Wiki <https://github.com/iamalnewkirk/data-object-try/wiki>
435
436 Project <https://github.com/iamalnewkirk/data-object-try>
437
438 Initiatives <https://github.com/iamalnewkirk/data-object-try/projects>
439
440 Milestones <https://github.com/iamalnewkirk/data-object-try/milestones>
441
442 Contributing
443 <https://github.com/iamalnewkirk/data-object-try/blob/master/CONTRIBUTE.md>
444
445 Issues <https://github.com/iamalnewkirk/data-object-try/issues>
446
447
README.md
1# NAME
2
3Data::Object::Try
4
5# ABSTRACT
6
7Try Class for Perl 5
8
9# SYNOPSIS
10
11 use strict;
12 use warnings;
13 use routines;
14
15 use Data::Object::Try;
16
17 my $try = Data::Object::Try->new;
18
19 $try->call(fun (@args) {
20 # try something
21
22 return time;
23 });
24
25 $try->catch('Example::Exception', fun ($caught) {
26 # caught an exception
27
28 return;
29 });
30
31 $try->default(fun ($caught) {
32 # catch the uncaught
33
34 return;
35 });
36
37 $try->finally(fun (@args) {
38 # always run after try/catch
39
40 return;
41 });
42
43 my @args;
44
45 my $result = $try->result(@args);
46
47# DESCRIPTION
48
49This package provides an object-oriented interface for performing complex try/catch operations.
50
51# ATTRIBUTES
52
53This package has the following attributes:
54
55## arguments
56
57 arguments(ArrayRef)
58
59This attribute is read-only, accepts `(ArrayRef)` values, and is optional.
60
61## invocant
62
63 invocant(Object)
64
65This attribute is read-only, accepts `(Object)` values, and is optional.
66
67## on\_catch
68
69 on_catch(ArrayRef[CodeRef])
70
71This attribute is read-write, accepts `(ArrayRef[CodeRef])` values, and is optional.
72
73## on\_default
74
75 on_default(CodeRef)
76
77This attribute is read-write, accepts `(CodeRef)` values, and is optional.
78
79## on\_finally
80
81 on_finally(CodeRef)
82
83This attribute is read-write, accepts `(CodeRef)` values, and is optional.
84
85## on\_try
86
87 on_try(CodeRef)
88
89This attribute is read-write, accepts `(CodeRef)` values, and is optional.
90
91# METHODS
92
93This package implements the following methods:
94
95## call
96
97 call(Str | CodeRef $arg) : Object
98
99The call method takes a method name or coderef, registers it as the tryable
100routine, and returns the object. When invoked, the callback will received an
101`invocant` if one was provided to the constructor, the default `arguments` if
102any were provided to the constructor, and whatever arguments were provided by
103the invocant.
104
105- call example #1
106
107 use routines;
108
109 my $try = Data::Object::Try->new;
110
111 $try->call(fun (@args) {
112
113 return [@args];
114 });
115
116## callback
117
118 callback(Str | CodeRef $arg) : CodeRef
119
120The callback method takes a method name or coderef, and returns a coderef for
121registration. If a coderef is provided this method is mostly a passthrough.
122
123- callback example #1
124
125 use routines;
126
127 my $try = Data::Object::Try->new;
128
129 $try->callback(fun (@args) {
130
131 return [@args];
132 });
133
134- callback example #2
135
136 package Example;
137
138 use Moo;
139 use routines;
140
141 fun test(@args) {
142
143 return [@args];
144 }
145
146 package main;
147
148 my $try = Data::Object::Try->new(
149 invocant => Example->new
150 );
151
152 $try->callback('test');
153
154## catch
155
156 catch(Str $isa, Str | CodeRef $arg) : Any
157
158The catch method takes a package or ref name, and when triggered checks whether
159the captured exception is of the type specified and if so executes the given
160callback.
161
162- catch example #1
163
164 use routines;
165
166 my $try = Data::Object::Try->new;
167
168 $try->call(fun (@args) {
169
170 die $try;
171 });
172
173 $try->catch('Data::Object::Try', fun (@args) {
174
175 return [@args];
176 });
177
178## default
179
180 default(Str | CodeRef $arg) : Object
181
182The default method takes a method name or coderef and is triggered if no
183`catch` conditions match the exception thrown.
184
185- default example #1
186
187 use routines;
188
189 my $try = Data::Object::Try->new;
190
191 $try->call(fun (@args) {
192
193 die $try;
194 });
195
196 $try->default(fun (@args) {
197
198 return [@args];
199 });
200
201## execute
202
203 execute(CodeRef $arg, Any @args) : Any
204
205The execute method takes a coderef and executes it with any given arguments.
206When invoked, the callback will received an `invocant` if one was provided to
207the constructor, the default `arguments` if any were provided to the
208constructor, and whatever arguments were passed directly to this method.
209
210- execute example #1
211
212 use routines;
213
214 my $try = Data::Object::Try->new(
215 invocant => Example->new,
216 arguments => [1,2,3]
217 );
218
219 $try->execute(fun (@args) {
220
221 return [@args];
222 });
223
224## finally
225
226 finally(Str | CodeRef $arg) : Object
227
228The finally method takes a package or ref name and always executes the callback
229after a try/catch operation. The return value is ignored. When invoked, the
230callback will received an `invocant` if one was provided to the constructor,
231the default `arguments` if any were provided to the constructor, and whatever
232arguments were provided by the invocant.
233
234- finally example #1
235
236 use routines;
237
238 my $try = Data::Object::Try->new(
239 invocant => Example->new,
240 arguments => [1,2,3]
241 );
242
243 $try->call(fun (@args) {
244
245 return $try;
246 });
247
248 $try->finally(fun (@args) {
249
250 $try->{'$finally'} = [@args];
251 });
252
253## maybe
254
255 maybe() : Object
256
257The maybe method registers a default `catch` condition that returns falsy,
258i.e. an empty string, if an exception is encountered.
259
260- maybe example #1
261
262 use routines;
263
264 my $try = Data::Object::Try->new;
265
266 $try->call(fun (@args) {
267
268 die $try;
269 });
270
271 $try->maybe;
272
273## no\_catch
274
275 no_catch() : Object
276
277The no\_catch method removes any configured catch conditions and returns the
278object.
279
280- no\_catch example #1
281
282 use routines;
283
284 my $try = Data::Object::Try->new;
285
286 $try->call(fun (@args) {
287
288 die $try;
289 });
290
291 $try->catch('Data::Object::Try', fun (@args) {
292
293 return [@args];
294 });
295
296 $try->no_catch;
297
298## no\_default
299
300 no_default() : Object
301
302The no\_default method removes any configured default condition and returns the
303object.
304
305- no\_default example #1
306
307 use routines;
308
309 my $try = Data::Object::Try->new;
310
311 $try->call(fun (@args) {
312
313 die $try;
314 });
315
316 $try->default(fun (@args) {
317
318 return [@args];
319 });
320
321 $try->no_default;
322
323## no\_finally
324
325 no_finally() : Object
326
327The no\_finally method removes any configured finally condition and returns the
328object.
329
330- no\_finally example #1
331
332 use routines;
333
334 my $try = Data::Object::Try->new(
335 invocant => Example->new,
336 arguments => [1,2,3]
337 );
338
339 $try->call(fun (@args) {
340
341 return $try;
342 });
343
344 $try->finally(fun (@args) {
345
346 $try->{'$finally'} = [@args];
347 });
348
349 $try->no_finally;
350
351## no\_try
352
353 no_try() : Object
354
355The no\_try method removes any configured `try` operation and returns the
356object.
357
358- no\_try example #1
359
360 use routines;
361
362 my $try = Data::Object::Try->new;
363
364 $try->call(fun (@args) {
365
366 return [@args];
367 });
368
369 $try->no_try;
370
371## result
372
373 result(Any @args) : Any
374
375The result method executes the try/catch/default/finally logic and returns
376either 1) the return value from the successfully tried operation 2) the return
377value from the successfully matched catch condition if an exception was thrown
3783) the return value from the default catch condition if an exception was thrown
379and no catch condition matched. When invoked, the `try` and `finally`
380callbacks will received an `invocant` if one was provided to the constructor,
381the default `arguments` if any were provided to the constructor, and whatever
382arguments were passed directly to this method.
383
384- result example #1
385
386 use routines;
387
388 my $try = Data::Object::Try->new;
389
390 $try->call(fun (@args) {
391
392 return [@args];
393 });
394
395 $try->result;
396
397- result example #2
398
399 use routines;
400
401 my $try = Data::Object::Try->new;
402
403 $try->call(fun (@args) {
404
405 return [@args];
406 });
407
408 $try->result(1..5);
409
410# AUTHOR
411
412Al Newkirk, `awncorp@cpan.org`
413
414# LICENSE
415
416Copyright (C) 2011-2019, Al Newkirk, et al.
417
418This is free software; you can redistribute it and/or modify it under the terms
419of the The Apache License, Version 2.0, as elucidated in the ["license
420file"](https://github.com/iamalnewkirk/data-object-try/blob/master/LICENSE).
421
422# PROJECT
423
424[Wiki](https://github.com/iamalnewkirk/data-object-try/wiki)
425
426[Project](https://github.com/iamalnewkirk/data-object-try)
427
428[Initiatives](https://github.com/iamalnewkirk/data-object-try/projects)
429
430[Milestones](https://github.com/iamalnewkirk/data-object-try/milestones)
431
432[Contributing](https://github.com/iamalnewkirk/data-object-try/blob/master/CONTRIBUTE.md)
433
434[Issues](https://github.com/iamalnewkirk/data-object-try/issues)
435