Doxy/DocGenerator.pm untested

filter: Statementstmt 0.0% 0 / 260 Branchbran 0.0% 0 / 76 Conditioncond 0.0% 0 / 21 MC/DCmcdc 0.0% 0 / 14 Subroutinesub 0.0% 0 / 27 Podpod 0.0% 0 / 16 totaltotal 0.0% 0 / 414 CC 39 SCAR 34.7
CC
39
Cov
0%
_determine_method_attributes
110.0
_store_info
42.0
_insert_method_data
42.0
CRAP 32.1
1 ## @file
2 # (Enter your file info here)
3 #
4 # @copy 2007 MailerMailer LLC
5 # $Id: DocGenerator.pm 353 2007-08-14 17:46:43Z damjan $
6  
7 ## @class RWDE::Doxy::DocGenerator
8 # Note: This class is abstract.
9 # It makes calls to fields that do not exist.
10 # Please do not instantiate.
11  
12 package RWDE::Doxy::DocGenerator;
13  
14 use strict;
15 use warnings;
16  
17 use Error qw(:try);
18  
19 use RWDE::Exceptions;
20 use RWDE::Doxy::MethodData;
21  
22 use constant COMMENT => '#'; #Comments start with this character
23 use constant COMMAND_PREFIX => '@'; #Prefix of the command
24  
25 use constant CHARACTER_SIZE => 1; #Size of one character
26 use constant PARAM_SIZE => 9; #Size of '$$params{'
27 use constant RETURN_SIZE => 6; #Size of 'return'
28  
29 use vars qw($VERSION);
30 $VERSION = sprintf "%d", q$Revision: 518 $ =~ /(\d+)/;
31  
32 ## @method void doxygenate()
33 # Write/save the content to file. if you give a filename overwrites the original saves backup into the filename given
34 # this function takes the filename gets the contents and creates all the tags we know how returns the marked up contents
35 sub doxygenate() {
36 my ($self, $params) = @_;
37  
38 #Process the file, placing all non_doxy lines into file_content_out
39 #also populate MethodData and class data with the necessary info.
40 $self->_create_intermediate_data();
41  
42 #We now have intemediate data in file_content_out
43 #We want to read from the file_content_out and write the complete doxygenated file
44 #So place the file_content_out into the file_content_in.
45 #Reset the file and class cursors.
46 #Reset file content out
47 $self->file_content_in($self->file_content_out);
48 $self->reset_file_index();
49 $self->reset_file_content_out();
50 $self->reset_file_current_class();
51  
52 #Insert initial info on top of page
53 $self->_insert_file_data();
54  
55 #Insert all other command and info
56 $self->_insert_document_data();
57  
58 return ();
59 }
60  
61 ## @method protected void _create_intermediate_data()
62 # Form an array of intermediate data. This will consist of all lines in file_content_in that are not doxy_lines
63 # Also populate class and method data so we can preserve doxy comments.
64 # (We can then add them back in somewhere else)
65 sub _create_intermediate_data() {
66 my ($self, $params) = @_;
67  
68 #Loop through every line of the file and parse/analyze it.
69 while ($self->current_line()) {
70  
71 #if it is a doxy command tag
72  
73 #enter if the current line is a doxy tag command
74 if ($self->current_line() =~ /^\s*## @(\S+)\s?(.*)(\n)/) {
75 my $command_name = $1;
76 my $command_info = $2;
77  
78 #Already saw the command. We will not need it again so increment the file index
79 #We will regenerate this line when we remake the doxy tags so this will not be added to file_content_out
80 $self->next_line();
81  
82 if ($command_name eq 'file') {
83 $self->_store_file_info();
84 }
85 elsif ($command_name eq 'class') {
86  
87 #Command info consists of the class name
88 #Ex:
89 #@class <class_name>
90 #@class is the $command_name, whicle the class name is the $command_info,
91 $self->_store_class_info({ command_info => $command_info });
92  
93 #Methods will need to know what class they belong to
94 #We will keep the name of this class handy so we can store the methods' method_data in the correct class_data
95 $self->file_current_class($command_info);
96 }
97 elsif ($command_name eq 'method' or $command_name eq 'cmethod') {
98 $self->_store_method_info({ command_info => $command_info });
99 }
100 else {
101  
102 #This tag could be a todo, enum, etc. So just echo it to file_out
103 $self->add_to_file_out({ content => $self->current_line() });
104 $self->next_line();
105 }
106 }
107  
108 #This is not a tag so just add the line to the end of file_content_intermediate
109 else {
110 $self->add_to_file_out({ content => $self->current_line() });
111 $self->next_line();
112 }
113 }
114 }
115  
116 ## @method protected void _store_file_info()
117 # Store all \@file-related doxy info lines (no command present) for later use.
118 # All \@file info is placed at the top of the perl document file.
119 sub _store_file_info() {
120 my ($self, $params) = @_;
121  
122 $self->_store_info({ data => $self });
123 }
124  
125 ## @method protected void _store_class_info($command_info, $command_info})
126 # Store all \@class-related doxy info lines (no command present) for later use.
127 # @param command_info (Enter explanation for param here)
128 sub _store_class_info() {
129 my ($self, $params) = @_;
130  
131 throw RWDE::DataMissingException({ info => 'No class_name specified' })
132 unless defined($$params{command_info});
133  
134 $self->_store_info({ data => $self->get_class({ class_name => $$params{command_info} }) });
135  
136 return ();
137 }
138  
139 ## @method protected void _store_method_info($command_info)
140 # Store all \@method-related doxy info lines (no command present) for later use.
141 # @param command_info (Enter explanation for param here)
142 sub _store_method_info() {
143 my ($self, $params) = @_;
144  
145 throw RWDE::DataMissingException({ info => 'No class_name specified' })
146 unless defined($$params{command_info});
147  
148 my $class_data = $self->get_class({ class_name => $self->file_current_class });
149  
150 $$params{command_info} =~ /(\S+)\(.*\)\s*$/;
151  
152 my $method_data = $class_data->get_method({ method_name => $1 });
153  
154 $self->_store_info({ data => $method_data, sub_info => 1 });
155  
156 return ();
157 }
158  
159 ## @method protected void _store_info($data)
160 # Checks to see if a class info exists
161 # If a ClassData entry exists then tell it to store the info lines
162 # If it does not exist then create a new ClassData object and populate the info
163 # @param data (Enter explanation for param here)
164 sub _store_info() {
165 my ($self, $params) = @_;
166  
167 throw RWDE::DataMissingException({ info => 'No data specified' })
168 unless defined($$params{data});
169  
170 my $data = $$params{data};
171  
172 #While we are looking at a "block" of doxy tags (every line until we do not start a line with "# ")
173 while ($self->current_line() =~ /^\s*#\s(.*)\n/) {
174  
175 #@ implies that a tag exists so ignore anything that is not an info line
176 #However, we will need to store params, etc.
177 if ($self->current_line() !~ /^\s*#\s\@(\S+)\s*(.*)/) {
178 $data->add_info({ info_line => $1 });
179 }
180 else {
181  
182 #Files and classes do not have params and returns.
183 #But methods do
184 #This area will only be intered if sub_info param is defined.
185 if (defined($$params{sub_info})) {
186 if ($1 eq 'param') {
187 my $param_info = $2;
188  
189 $param_info =~ /(\S+)\s*(.*)/;
190  
191 $data->add_param_info({ param_name => $1, param_info => $2 });
192 }
193 elsif ($1 eq 'return') {
194 $data->set_return_info({ return_info => $2 });
195 }
196 }
197 }
198  
199 $self->next_line();
200 }
201  
202 return ();
203 }
204  
205 ## @method protected void _insert_file_data()
206 #Insert \@file template info at the top of the file
207 #Four lines, where filename is the file_name of the file.
208 # ## \@file
209 # # (Enter your file info here)
210 # #
211 # # \@copy 2007 MailerMailer LLC
212 # # Subversion ID tag
213 sub _insert_file_data() {
214 my ($self, $params) = @_;
215  
216 my $info_lines = $self->file_info();
217  
218 #Create the entire tag for this command
219 $self->add_to_file_out({ content => $self->_command({ command => 'file' }) });
220  
221 #Want to check if we store any @file lines
222 if (scalar @{$info_lines} > 0) {
223  
224 #We have some lines stored. Add them in
225 $self->_insert_info_lines({ info_lines => $info_lines });
226 }
227 else {
228  
229 #No lines were found so generate the default stuff.
230 $self->add_to_file_out({ content => $self->_info({ info => '(Enter your file info here)' }) });
231 $self->add_to_file_out({ content => $self->_info() });
232 $self->add_to_file_out({ content => $self->_sub_command({ command => 'copy', info => '2007 MailerMailer LLC' }) });
233 $self->add_to_file_out({ content => $self->_info({ info => '$Id$' }) });
234 $self->add_to_file_out({ content => "\n" });
235 }
236  
237 return ();
238 }
239  
240 ## @method protected void _insert_document_data()
241 #Insert method and sub tag data into new updated_file_data
242 #The methods inside the 'if' will increment the line_index and return it.
243 sub _insert_document_data() {
244 my ($self, $params) = @_;
245  
246 #Loop through every line of the file and parse/analyze it.
247 while ($self->current_line()) {
248  
249 #Does this line contain the start of a valid package/class?
250 if ($self->current_line() =~ /^\s*package\s+(\S+);/) {
251  
252 #Update the current package name
253 $self->file_current_class($1);
254  
255 #Insert class/package data before 'package <package_name> ...'
256 $self->_insert_class_data({ class_name => $self->file_current_class });
257  
258 $self->add_to_file_out({ content => $self->current_line() });
259  
260 $self->next_line();
261 }
262  
263 #Does this line contain a valid method.
264 elsif ($self->current_line() =~ /^\s*sub\s+(\w+)/) {
265  
266 #Store current line index. we will need it later to copy lines to updated_file_content
267 my $initial_line_index = $self->file_index;
268  
269 #Get the method data object or create a new one.
270 my $class_data = $self->get_current_class();
271 my $method_data = $class_data->get_method({ method_name => $1 });
272  
273 #Find method information (such as params, return info)
274  
275 #This method will increment $self->file_index so we will need it after the method is finished.
276 $self->_determine_method_attributes({ method_data => $method_data });
277  
278 #Insert method/sub data before 'sub <sub_name> ...'
279 $self->_insert_method_data({ method_data => $method_data });
280  
281 #Because the tag/comments occur on top of the method, we had to hold off until after that stuff was
282 #taken care of. Now we can copy over the method, itself.
283 #We subtract one off file_index because it is pointing to the line after the method, which
284 #this loop will take care of on the next iteration.
285 $self->add_range_to_file_out({ start_index => $initial_line_index, end_index => $self->file_index - 1 });
286 }
287  
288 #Nothing special about the line, just copy it over
289 else {
290 $self->add_to_file_out({ content => $self->current_line() });
291 $self->next_line();
292 }
293  
294 }
295  
296 return ();
297 }
298  
299 ## @method protected void _insert_class_data($class_name})
300 # Insert \@class template info above the "package <package_name>"
301 # Two lines:
302 # ## @class
303 # # (Enter your class info here)
304 # @param class_name (Enter explanation for param here)
305 sub _insert_class_data() {
306 my ($self, $params) = @_;
307  
308 throw RWDE::DataMissingException({ info => 'No class_name specified' })
309 unless defined($$params{class_name});
310  
311 $self->add_to_file_out({ content => $self->_command({ command => 'class', info => $$params{class_name} }) });
312  
313 my $info_lines = $self->get_class($params)->class_info();
314  
315 #If we saved some info lines from before...add them in.
316 if (scalar @{$info_lines} > 0) {
317 $self->_insert_info_lines({ info_lines => $info_lines });
318 }
319 else {
320  
321 #We have no lines to add so just generate an info line
322 $self->add_to_file_out({ content => $self->_info({ info => '(Enter ' . $$params{class_name} . ' info here)' }) });
323 }
324  
325 return ();
326 }
327  
328 ## @method protected object _insert_method_data($method_data)
329 # Insert method or cmethod template info above the "sub <sub_name> ..."
330 # @param method_data (Enter explanation for param here)
331 sub _insert_method_data() {
332 my ($self, $params) = @_;
333  
334 throw RWDE::DataMissingException({ info => 'No method_data specified' })
335 unless defined($$params{method_data});
336  
337 my $method_data = $$params{method_data};
338  
339 #Combine the method info
340 $self->add_to_file_out({ content => $self->_command({ command => $method_data->method_type, info => $method_data->method_description() }) });
341  
342 if (scalar @{ $method_data->method_info } > 0) {
343 $self->_insert_info_lines({ info_lines => $method_data->method_info });
344 }
345 else {
346  
347 #We have no lines to add so just generate an info line
348 $self->add_to_file_out({ content => $self->_info({ info => '(Enter ' . $method_data->method_name . ' info here)' }) });
349 }
350  
351 foreach my $param_name (keys %{ $method_data->method_params() }) {
352  
353 #Get param info for this param name. It will return undef if one does not exist.
354 my $param_info = $method_data->get_param_info({ param_name => $param_name });
355  
356 #Use the param info if it exists or generate a generic info string if it does not
357 $param_info = ($param_info ne undef) ? $param_info : '(Enter explanation for param here)';
358  
359 $self->add_to_file_out({ content => $self->_sub_command({ command => 'param', info => "$param_name $param_info" }) });
360 }
361  
362 if ($method_data->method_return_type ne "void") {
363 my $return_info = ($method_data->method_return_info ne undef and $method_data->method_return_info ne '')
364 ? $method_data->method_return_info() : '(Enter explanation for return value here)';
365  
366 $self->add_to_file_out({ content => $self->_sub_command({ command => 'return', info => $return_info }) });
367 }
368  
369 return ();
370 }
371  
372 ## @method protected void _insert_info_lines($info_lines)
373 # (Enter _insert_info_lines info here)
374 sub _insert_info_lines() {
375 my ($self, $params) = @_;
376  
377 throw RWDE::DataMissingException({ info => 'No info_lines specified' })
378 unless defined($$params{info_lines});
379  
380 foreach my $info_line (@{ $$params{info_lines} }) {
381 $self->add_to_file_out({ content => $self->_info({ info => $info_line }) });
382 }
383  
384 return ();
385 }
386  
387 ## @method protected object _determine_method_attributes($method_data)
388 # Add the new tag lines to the updated_file_content
389 # @param method_data (Enter explanation for param here)
390 sub _determine_method_attributes() {
391 my ($self, $params) = @_;
392  
393 throw RWDE::DataMissingException({ info => 'No method_data specified' })
394 unless defined($$params{method_data});
395  
396 my $method_data = $$params{method_data};
397  
398 #We always need to go into the while loop once
399 my $initial_loop = 1;
400  
401 #For every { we will increment the bracket count by 1. For every } we will decrement the bracket count by 1.
402 #Once the bracker count reaches zero, then we have found the end of the method.
403 #Start by incrementing here if necessary because one { could be on the same line as the method declaration: "sub my_name() {"
404 #But we only want to do that if one is there.
405 if ($self->current_line() =~ /\{/) {
406 $method_data->increment_brackets_count();
407 }
408  
409 #Go to the next line and start pulling information from the method
410 $self->next_line;
411  
412 #Loop through the entire line (which is a string) and look for certain properties.
413 while (($self->current_line() and ($method_data->method_brackets_count != 0)) or $initial_loop) {
414 $initial_loop = undef;
415  
416 #The character index for this line's string
417 my $line = $self->current_line();
418 my $char_index = 0;
419 my $no_comment_found = 1; #True as long as we do not find a comment
420  
421 while ($char_index < length($line) and $no_comment_found) {
422  
423 #If this character is a comment then the rest of the lines should not be analyzed.
424 if (substr($line, $char_index, CHARACTER_SIZE) eq COMMENT) {
425 $no_comment_found = 0;
426 }
427  
428 #Is this character a {. If so then increment the bracket counter
429 elsif (substr($line, $char_index, CHARACTER_SIZE) eq "{") {
430 $method_data->increment_brackets_count();
431 $char_index++;
432 }
433  
434 #If this character is a } then decrement the bracket counter
435 elsif (substr($line, $char_index, CHARACTER_SIZE) eq "}") {
436 $method_data->decrement_brackets_count();
437 $char_index++;
438 }
439  
440 #Do the next 9 characters show '$$params{'. If so, then we have found a param (unless a compile problem exists).
441 #There is one case where we do not want to count $$params{<something>} as a parameter
442 #-Lets say the we assign a value to a param key, such as $$params{something} = 4;
443 #-This param was not passed in, so we do not want to count it
444 #-However, if the param was passed in and it is reassigned (as above), it will still get picked up as a param
445 #because it will appear at least twice.
446 #-The regex takes care of this.
447 elsif (substr($line, $char_index, PARAM_SIZE) eq '$$params{' and $line !~ /\$\$params\{\s*\S+\s*}\s*=/) {
448 my $param_name;
449 my $rest_of_line = substr($line, $char_index + PARAM_SIZE, length($line) - $char_index + PARAM_SIZE);
450  
451 if ($rest_of_line =~ /^\s*(\w+)/) {
452 $param_name = $1;
453 $method_data->add_param({ param_name => $param_name });
454 $char_index += (PARAM_SIZE + length($param_name) + 1); #The +1 is for the '}'
455 }
456 else {
457 throw RWDE::DataBadException({ info => 'Malformed param File will probably not compile. On line ' . $self->file_index });
458 }
459 }
460 elsif (substr($line, $char_index, RETURN_SIZE) eq 'return') {
461 my $rest_of_line = substr($line, $char_index + RETURN_SIZE, length($line) - $char_index + RETURN_SIZE);
462  
463 #If not "return;" and not "return();" then it is an object. Otherwise leave it at the default void.
464 if ($rest_of_line !~ /^\s*\(?\s*\)?;/){
465 $method_data->method_return_type('object');
466 }
467  
468 $char_index += RETURN_SIZE;
469 }
470 else {
471 $char_index++;
472 }
473 }
474  
475 $self->next_line();
476 }
477  
478 return ();
479 }
480  
481 ## @method protected object _command($command)
482 # This returns a one-line command string.
483 # Example: command param is 'file', info param is "info"
484 # will return '## @file info'
485 # @param command (Enter explanation for param here)
486 # @return (Enter explanation for return value here)
487 sub _command() {
488 my ($self, $params) = @_;
489  
490 throw RWDE::DataMissingException({ info => 'Command not specified' })
491 unless defined($$params{command});
492  
493 #Use two comment characters for the major command.
494 $$params{prefix} = COMMENT . COMMENT;
495  
496 return $self->_line($params);
497 }
498  
499 ## @method protected object _sub_command($command)
500 #This returns a one-line sub command string.
501 #Example: command param is 'file', info param is 'info"
502 # will return '# @file info'
503 # @param command (Enter explanation for param here)
504 # @return (Enter explanation for return value here)
505 sub _sub_command() {
506 my ($self, $params) = @_;
507  
508 throw RWDE::DataMissingException({ info => 'Command not specified' })
509 unless defined($$params{command});
510  
511 $$params{prefix} = COMMENT;
512  
513 return $self->_line($params);
514 }
515  
516 ## @method protected object _info($command)
517 # This returns a one-line info string.
518 # Example: info param is 'file'
519 # will return '# file'
520 # Note that commands are not allowed in info strings. Please see _command and _sub_command for that
521 # @param command (Enter explanation for param here)
522 # @return (Enter explanation for return value here)
523 sub _info() {
524 my ($self, $params) = @_;
525  
526 #info does not have a command. So passing in a command is illegal.
527 throw RWDE::DataMissingException({ info => 'Command specified' })
528 unless not defined($$params{command});
529  
530 $$params{prefix} = COMMENT;
531  
532 return $self->_line($params);
533 }
534  
535 ## @method protected object _line($command, $info, $prefix)
536 # This returns a one-line sub command string.
537 # Example: info param is 'file'
538 # will return '# file'
539 # Note that commands are not allowed in info strings. Please see _command and _sub_command for that
540 # @param info (Enter explanation for param here)
541 # @param command (Enter explanation for param here)
542 # @param prefix (Enter explanation for param here)
543 # @return (Enter explanation for return value here)
544 sub _line() {
545 my ($self, $params) = @_;
546  
547 throw RWDE::DataMissingException({ info => 'No tag prefix specified' })
548 unless defined($$params{prefix});
549  
550 my $tag = ''; #We just want an empty line for some reason.;
551  
552 if (defined($$params{info}) and defined($$params{command})) {
553 $tag = COMMAND_PREFIX . $$params{command} . ' ' . $$params{info};
554 }
555 elsif (defined($$params{command})) {
556 $tag = COMMAND_PREFIX . $$params{command};
557 }
558 elsif (defined($$params{info})) {
559 $tag = $$params{info};
560 }
561  
562 return $$params{prefix} . ' ' . $tag . "\n";
563 }
564  
565 1;