File Coverage

blib/lib/McBain/Directly.pm
Criterion Covered Total %
statement 18 18 100.0
branch 1 2 50.0
condition n/a
subroutine 7 7 100.0
pod 4 4 100.0
total 30 31 96.7


line stmt bran cond sub pod time code
1             package McBain::Directly;
2              
3 3     3   12 use warnings;
  3         2  
  3         89  
4 3     3   12 use strict;
  3         4  
  3         72  
5              
6 3     3   11 use Carp;
  3         5  
  3         837  
7              
8             =head1 NAME
9            
10             McBain::Directly - Use a McBain API directly from Perl code.
11              
12             =head1 SYNOPSIS
13              
14             # if the API is object oriented
15             use MyAPI;
16              
17             my $api = MyAPI->new;
18              
19             $two_times_five = $api->call('GET:/math/multiply', { one => 2, two => 5 });
20              
21             # if the API is not object oriented
22             use MyAPI;
23              
24             $two_times_five = MyAPI->call('GET:/math/multiply', { one => 2, two => 5 });
25              
26             =head1 DESCRIPTION
27              
28             The C module is the default, and simplest L
29             available. It allows using APIs written with L directly from Perl code.
30              
31             When used directly, C APIs behave like so:
32              
33             =over
34              
35             =item * Return values from the API's methods are returned to the caller as is, with no
36             formatting or processing whatsoever.
37              
38             =item * Exceptions are returned as is as well, in C's L
39             format. This means the C method Cs when errors are encountered, so
40             you should check for exceptions with C, or use something like L.
41              
42             =back
43              
44             =head1 METHODS EXPORTED TO YOUR API
45              
46             None.
47              
48             =head1 METHODS REQUIRED BY MCBAIN
49              
50             This runner module implements the following methods required by C:
51              
52             =head2 init( )
53              
54             Does nothing here.
55              
56             =cut
57              
58 3     3 1 85 sub init { 1 }
59              
60             =head2 generate_env( $namespace, $payload )
61              
62             Accepts the arguments to the C method and creates C's
63             standard C<$env> hash-ref.
64              
65             =cut
66              
67             sub generate_env {
68 30     30 1 42 my $class = shift;
69              
70 30 50       208 confess { code => 400, error => "Namespace must match : where METHOD is one of GET, POST, PUT, DELETE or OPTIONS" }
71             unless $_[0] =~ m/^(GET|POST|PUT|DELETE|OPTIONS):[^:]+$/;
72              
73 30         98 my ($method, $route) = split(/:/, $_[0]);
74              
75             return {
76 30         146 METHOD => $method,
77             ROUTE => $route,
78             PAYLOAD => $_[1]
79             };
80             }
81              
82             =head2 generate_res( $env, $res )
83              
84             Simply returns the results as-is.
85              
86             =cut
87              
88             sub generate_res {
89 19     19 1 32 my ($class, $env, $res) = @_;
90              
91 19         90 return $res;
92             }
93              
94             =head2 handle_exception( $err )
95              
96             Simply rethrows the exception.
97              
98             =cut
99              
100             sub handle_exception {
101 11     11 1 14 my ($class, $err) = @_;
102              
103 11         96 confess $err;
104             }
105              
106             =head1 BUGS AND LIMITATIONS
107              
108             Please report any bugs or feature requests to
109             C, or through the web interface at
110             L.
111              
112             =head1 SUPPORT
113              
114             You can find documentation for this module with the perldoc command.
115              
116             perldoc McBain::Directly
117              
118             You can also look for information at:
119              
120             =over 4
121            
122             =item * RT: CPAN's request tracker
123            
124             L
125            
126             =item * AnnoCPAN: Annotated CPAN documentation
127            
128             L
129            
130             =item * CPAN Ratings
131            
132             L
133            
134             =item * Search CPAN
135            
136             L
137            
138             =back
139            
140             =head1 AUTHOR
141            
142             Ido Perlmuter
143            
144             =head1 LICENSE AND COPYRIGHT
145            
146             Copyright (c) 2013-2014, Ido Perlmuter C<< ido@ido50.net >>.
147            
148             This module is free software; you can redistribute it and/or
149             modify it under the same terms as Perl itself, either version
150             5.8.1 or any later version. See L
151             and L.
152            
153             The full text of the license can be found in the
154             LICENSE file included with this module.
155            
156             =head1 DISCLAIMER OF WARRANTY
157            
158             BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
159             FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
160             OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
161             PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
162             EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
163             WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
164             ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
165             YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
166             NECESSARY SERVICING, REPAIR, OR CORRECTION.
167            
168             IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
169             WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
170             REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
171             LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
172             OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
173             THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
174             RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
175             FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
176             SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
177             SUCH DAMAGES.
178            
179             =cut
180              
181             1;
182             __END__