| 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; |