File Coverage

lib/Web/DataService/IDocument.pm
Criterion Covered Total %
statement 6 85 7.0
branch 0 22 0.0
condition 0 32 0.0
subroutine 2 20 10.0
pod 0 18 0.0
total 8 177 4.5


line stmt bran cond sub pod time code
1             #
2             # Web::DataService::IDocument
3             #
4             # This is a role that provides access to dataservice documentation. It is
5             # designed to be composed into the classes used for documenting dataservice
6             # nodes.
7              
8              
9 2     2   15 use strict;
  2         6  
  2         84  
10              
11             package Web::DataService::IDocument;
12              
13 2     2   13 use Moo::Role;
  2         4  
  2         12  
14              
15              
16             # document_node ( )
17             #
18             # Return the documentation string for this node, if one was defined. If an
19             # "extended_doc" string was also defined for this node, return it as well.
20              
21             sub document_node {
22            
23 0     0 0   my ($request) = @_;
24            
25 0           my $ds = $request->ds;
26 0           my $path = $request->node_path;
27 0           my $extended = $ds->{extdoc_node}{$path};
28            
29 0 0         if ( ref $extended eq 'HASH' )
30             {
31 0           my $disp = $extended->{disp};
32            
33 0 0         if ( $disp eq 'replace' )
34             {
35 0           return $extended->{doc_string};
36             }
37            
38 0   0       my $doc_string = $ds->node_attr($path, 'doc_string') // '';
39            
40 0 0 0       $doc_string .= "\n\n" if $disp eq 'para' && $doc_string ne '';
41            
42 0           return $doc_string . $extended->{doc_string};
43             }
44            
45             else
46             {
47 0           return $ds->node_attr($path, 'doc_string');
48             }
49             }
50              
51              
52             # list_navtrail ( )
53             #
54             # Return a list of navigation trail components for the current request, in POD
55             # format. This is derived component-by-component from the request path.
56              
57             sub list_navtrail {
58            
59 0     0 0   my ($request, $base_label) = @_;
60            
61 0   0       my $path = $request->node_path || '/';
62 0           my $ds = $request->ds;
63            
64 0   0       $base_label ||= $ds->node_attr($path, 'title') || '';
      0        
65            
66             # If there are no path components, return just the base label.
67            
68 0 0         return $base_label if $path eq '/';
69            
70             # Otherwise, split the path into components and go through them one by one.
71            
72 0           my @trail = $ds->node_link('/', $base_label);
73 0           my @path = split qr{/}, $path;
74 0           my $node = "";
75 0           my $count = $#path;
76            
77 0           foreach my $component (@path)
78             {
79 0 0         $node .= '/' if $node;
80 0           $node .= $component;
81              
82 0 0         if ( $count-- == 0 )
83             {
84 0   0       push @trail, $ds->node_attr($node, 'title') || $component;
85             }
86            
87             else
88             {
89 0           push @trail, $ds->node_link($node);
90             }
91             }
92            
93 0           return @trail;
94             }
95              
96              
97             # list_http_methods ( )
98             #
99             # Return a list of the HTTP methods that are allowed for this request path.
100              
101             sub list_http_methods {
102              
103 0     0 0   my ($request) = @_;
104            
105 0           my $methods = $request->{ds}->node_attr($request, 'allow_method');
106 0 0         return @Web::DataService::DEFAULT_METHODS unless ref $methods eq 'HASH';
107 0           return grep { $methods->{$_} } @Web::DataService::HTTP_METHOD_LIST;
  0            
108             }
109              
110              
111             # document_http_methods ( )
112             #
113             # Return a string documenting the HTTP methods that are allowed for this
114             # request path.
115              
116             sub document_http_methods {
117            
118 0     0 0   my ($request) = @_;
119            
120 0           my $doc = join(', ', map { "C<$_>" } $request->list_http_methods);
  0            
121 0   0       return $doc || '';
122             }
123              
124              
125             # list_subnodes
126             #
127             # Return a list of sub-nodes of the current one. This will include all
128             # sub-nodes with a value for the node attribute 'place', in order by the value
129             # of that attribute.
130              
131             sub list_subnodes {
132            
133 0     0 0   my ($request) = @_;
134            
135 0           my $ds = $request->ds;
136 0           my $path = $request->node_path;
137            
138 0           return $ds->list_subnodes($path);
139             }
140              
141              
142             # document_subnodes ( options )
143             #
144             # Return a documentation string in Pod format listing the subnodes (if any)
145             # given for this node. See &list_subnodes above.
146              
147             sub document_nodelist {
148              
149 0     0 0   my ($request, $options) = @_;
150            
151 0   0       $options ||= {};
152            
153 0           my $ds = $request->ds;
154 0   0       my $path = $options->{list} || $request->node_path;
155 0           $options->{base} = $request->base_url;
156            
157 0           return $ds->document_nodelist($path, $options);
158             }
159              
160              
161             # document_usage
162             #
163             # Return a documentation string in Pod format describing the usage examples of
164             # the node corresponding to this request.
165              
166             sub document_usage {
167              
168 0     0 0   my ($request, $options) = @_;
169            
170 0           my $ds = $request->ds;
171 0           my $path = $request->node_path;
172            
173 0           return $ds->document_usage($path, $options);
174             }
175              
176              
177             # document_params ( )
178             #
179             # Return a documentation string in POD format describing the parameters
180             # available for this request.
181              
182             sub document_params {
183            
184 0     0 0   my ($request, $ruleset_name) = @_;
185            
186 0           my $ds = $request->{ds};
187            
188 0   0       $ruleset_name ||= $ds->determine_ruleset($request->node_path);
189            
190             # Generate documentation about the parameters, using the appropriate
191             # method from the validator class (HTTP::Validate). If no ruleset is
192             # selected for this request, then state that no parameters are accepted.
193            
194 0 0         if ( $ruleset_name )
195             {
196 0           return $ds->document_ruleset($ruleset_name);
197             }
198            
199             else
200             {
201 0           return '';
202             }
203             }
204              
205              
206             # output_label ( )
207             #
208             # Return the output label for the node corresponding to this request.
209              
210             sub output_label {
211            
212 0     0 0   my ($request) = @_;
213            
214 0   0       return $request->{ds}->node_attr($request, 'output_label') || 'basic';
215             }
216              
217              
218             # optional_output ( )
219             #
220             # Return the name of the optional output map, if any.
221              
222             sub optional_output {
223            
224 0     0 0   my ($request) = @_;
225            
226 0           return $request->{ds}->node_attr($request, 'optional_output');
227             }
228              
229              
230             # document_response ( )
231             #
232             # Return a documentation string in POD format describing the fields that can
233             # be included in the result.
234              
235             sub document_response {
236            
237 0     0 0   my ($request, $options) = @_;
238            
239 0           my $ds = $request->{ds};
240            
241 0           return $ds->document_response($request->node_path, $options);
242             }
243              
244              
245             # document_summary ( )
246             #
247             # Return a documentation string in POD format describing the fields that can
248             # be included in the summary block. If no summary block was specified for
249             # this operation, return the empty string.
250              
251             sub document_summary {
252              
253 0     0 0   my ($request, $options) = @_;
254            
255 0           my $ds = $request->{ds};
256            
257 0           return $ds->document_summary($request->node_path, $options);
258             }
259              
260              
261             # document_formats ( extended )
262             #
263             # Return a string in POD format documenting the formats allowed for the path
264             # associated with this request. If $extended is true, then include a text
265             # description of each format.
266              
267             sub document_formats {
268              
269 0     0 0   my ($request, $options) = @_;
270            
271 0   0       $options ||= {};
272 0 0 0       my ($path) = $options->{all} ? ('/') : ($options->{path} || $request->node_path);
273            
274 0           return $request->ds->document_formats($path, $options);
275             }
276              
277              
278             # defualt_format ( )
279             #
280             # Return the name of the default format (if any) for this request's path.
281              
282             sub default_format {
283            
284 0     0 0   $_[0]->ds->node_attr($_[0], 'default_format');
285             }
286              
287              
288             # document_vocabs ( extended )
289             #
290             # Return a string in POD format documenting the vocabularies allowed for the
291             # path associated with this request. If $extended is true, then include a
292             # text description of each vocabulary.
293              
294             sub document_vocabs {
295            
296 0     0 0   my ($request, $options) = @_;
297            
298 0 0         $options = {} unless ref $options;
299 0 0         my $path = $options->{all} ? '/' : $request->node_path;
300            
301 0           return $request->ds->document_vocabs($path, $options);
302             }
303              
304              
305             # pod_B, pod_I, pod_C
306             #
307             # These functions are intended for use as filters. They take a list of
308             # arguments and return a string consisting of the list items joined by commas
309             # and surrounded by the appropriate formatting code.
310              
311             sub pod_B {
312 0     0 0   return "B<" . join(', ', @_) . ">";
313             }
314              
315              
316             sub pod_C {
317 0     0 0   return "C<" . join(', ', @_) . ">";
318             }
319              
320              
321             sub pod_I {
322 0     0 0   return "I<" . join(', ', @_) . ">";
323             }
324              
325              
326              
327             1;