| 1 | ## @file | ||
| 2 | # (Enter your file info here) | ||
| 3 | # | ||
| 4 | # @copy 2007 MailerMailer LLC | ||
| 5 | # $Id: MethodData.pm 432 2008-05-02 19:17:09Z damjan $ | ||
| 6 | |||
| 7 | ## @class RWDE::Doxy::MethodData | ||
| 8 | # This class stores an intermediate representation of a method for a class. | ||
| 9 | # method_params stores a list of param name located within the method | ||
| 10 | # method_brackets_count is used to tally { and }. It will be incremented for every { and decremented for every }. | ||
| 11 | # method_return_type stores the return type of the method. It will be either object or void. | ||
| 12 | package RWDE::Doxy::MethodData; | ||
| 13 | |||
| 14 | use strict; | ||
| 15 | use warnings; | ||
| 16 | |||
| 17 | use Error qw(:try); | ||
| 18 | use RWDE::Exceptions; | ||
| 19 | |||
| 20 | use base qw(RWDE::RObject); | ||
| 21 | |||
| 22 | use constant PUBLIC_METHOD => "public"; | ||
| 23 | use constant PROTECTED_METHOD => "protected"; | ||
| 24 | |||
| 25 | our (@fieldnames, %fields, %static_fields, %modifiable_fields, @static_fieldnames, @modifiable_fieldnames); | ||
| 26 | |||
| 27 | use vars qw($VERSION); | ||
| 28 | $VERSION = sprintf "%d", q$Revision: 518 $ =~ /(\d+)/; | ||
| 29 | |||
| 30 | BEGIN { | ||
| 31 | |||
| 32 | #all of the static fields present in the list table | ||
| 33 | %static_fields = ( | ||
| 34 | |||
| 35 | # Field => [Type, Descr] | ||
| 36 | ); | ||
| 37 | |||
| 38 | #all of the fields allowed to be modified in the list table | ||
| 39 | %modifiable_fields = ( | ||
| 40 | |||
| 41 | # Field => [Type, Descr] | ||
| 42 | method_name => [ 'char', 'Name of the method' ], | ||
| 43 | |||
| 44 | #Use a hash for method_params because we want a set. | ||
| 45 | method_params => [ 'hash', 'Array of param names' ], | ||
| 46 | method_brackets_count => [ 'int', 'State of bracket matches' ], | ||
| 47 | method_return_type => [ 'char', 'Bracket return type' ], | ||
| 48 | method_type => [ 'char', 'method or cmethod (new/constructor)' ], | ||
| 49 | method_privileges => [ 'char', 'public or protected' ], | ||
| 50 | |||
| 51 | #Array is used for method_info because we need to preserver order. | ||
| 52 | method_info => [ 'array', 'list of all of the doxygen info lines that existed in the source file_content' ], | ||
| 53 | method_param_info => [ 'hash', 'info text displayed after the @param' ], | ||
| 54 | method_return_info => [ 'char', 'info text displayed after the @return' ] | ||
| 55 | ); | ||
| 56 | |||
| 57 | %fields = (%static_fields, %modifiable_fields); | ||
| 58 | |||
| 59 | @static_fieldnames = sort keys %static_fields; | ||
| 60 | @modifiable_fieldnames = sort keys %modifiable_fields; | ||
| 61 | @fieldnames = sort keys %fields; | ||
| 62 | } | ||
| 63 | |||
| 64 | ## @method object initialize($method_name) | ||
| 65 | # Create a new Object with the given method name | ||
| 66 | # @param method_name (Enter explanation for param here) | ||
| 67 | # @return | ||
| 68 | sub initialize() { | ||
| 69 | my ($self, $params) = @_; | ||
| 70 | |||
| 71 | $self->method_params({}); | ||
| 72 | $self->method_brackets_count(0); | ||
| 73 | $self->method_return_type('void'); | ||
| 74 | $self->method_name($$params{method_name}); | ||
| 75 | $self->method_info([]); | ||
| 76 | $self->method_param_info({}); | ||
| 77 | |||
| 78 | #'new'/constructor object are represented by 'cmethod' command. | ||
| 79 | #Any class method is also represented by cmethod other methods are represented by 'method' command | ||
| 80 | $self->method_type(($self->method_name eq 'new' or $self->method_name =~ /^[A-Z]/) ? "cmethod" : "method"); | ||
| 81 | |||
| 82 | #We are only going to use protected and public for our perl methods. | ||
| 83 | #Methods beginning with an underscore will be considered protected (Denoted by 'protected') | ||
| 84 | #Methods otherwise will be considered public (Denoted by nothing) | ||
| 85 | $self->method_privileges(($self->method_name =~ /^_/) ? PROTECTED_METHOD : PUBLIC_METHOD); | ||
| 86 | |||
| 87 | return (); | ||
| 88 | } | ||
| 89 | |||
| 90 | ## @method object increment_brackets_count() | ||
| 91 | # Increment the bracket level count | ||
| 92 | # @return (Enter explanation for return value--(Enter explanation for return value--(Enter explanation for return value here)--here)--here) | ||
| 93 | sub increment_brackets_count() { | ||
| 94 | my ($self, $params) = @_; | ||
| 95 | |||
| 96 | $self->method_brackets_count($self->method_brackets_count + 1); | ||
| 97 | |||
| 98 | return $self->method_brackets_count; | ||
| 99 | } | ||
| 100 | |||
| 101 | ## @method object decrement_brackets_count() | ||
| 102 | # Decrement the bracket level count | ||
| 103 | # @return (Enter explanation for return value--(Enter explanation for return value--(Enter explanation for return value here)--here)--here) | ||
| 104 | sub decrement_brackets_count() { | ||
| 105 | my ($self, $params) = @_; | ||
| 106 | |||
| 107 | #We do not want a negative number here. If we do then the parsed method has more } then { | ||
| 108 | throw RWDE::DevelException({ info => 'Trying to set increment_brackets_count to negative number. Does the file compile?' }) | ||
| 109 | unless ($self->method_brackets_count - 1 >= 0); | ||
| 110 | |||
| 111 | $self->method_brackets_count($self->method_brackets_count - 1); | ||
| 112 | |||
| 113 | return $self->method_brackets_count; | ||
| 114 | } | ||
| 115 | |||
| 116 | ## @method void add_param($param_name) | ||
| 117 | # Add a param to the parameter list | ||
| 118 | # @param param_name The name of the parameter we are adding | ||
| 119 | sub add_param() { | ||
| 120 | my ($self, $params) = @_; | ||
| 121 | |||
| 122 | throw RWDE::DataMissingException({ info => 'No param to add to param list' }) | ||
| 123 | unless defined($$params{param_name}); | ||
| 124 | |||
| 125 | #We only want a hash because we want a set. | ||
| 126 | #The '1' serves as a dummy value and has no true meaning. | ||
| 127 | $self->method_params->{ $$params{param_name} } = 1; | ||
| 128 | |||
| 129 | return (); | ||
| 130 | } | ||
| 131 | |||
| 132 | ## @method void add_info($info_line) | ||
| 133 | # Add an info | ||
| 134 | # @param info_line (Enter explanation for param here) | ||
| 135 | sub add_info() { | ||
| 136 | my ($self, $params) = @_; | ||
| 137 | |||
| 138 | throw RWDE::DataMissingException({ info => 'No info line to add to info_list' }) | ||
| 139 | unless defined($$params{info_line}); | ||
| 140 | |||
| 141 | my $method_info = $self->method_info; | ||
| 142 | |||
| 143 | push(@{$method_info}, $$params{info_line}); | ||
| 144 | |||
| 145 | return (); | ||
| 146 | } | ||
| 147 | |||
| 148 | ## @method void add_param_info($param_info, $param_name) | ||
| 149 | # Store param info: everything after @param | ||
| 150 | # @param param_info (Enter explanation for param here) | ||
| 151 | # @param param_name (Enter explanation for param here) | ||
| 152 | sub add_param_info() { | ||
| 153 | my ($self, $params) = @_; | ||
| 154 | |||
| 155 | throw RWDE::DataMissingException({ info => 'No param_name specified' }) | ||
| 156 | unless defined($$params{param_name}); | ||
| 157 | throw RWDE::DataMissingException({ info => 'No param_info specified' }) | ||
| 158 | unless defined($$params{param_info}); | ||
| 159 | |||
| 160 | $self->method_param_info->{ $$params{param_name} } = $$params{param_info}; | ||
| 161 | |||
| 162 | return (); | ||
| 163 | } | ||
| 164 | |||
| 165 | ## @method object get_param_info($param_name) | ||
| 166 | # (Enter get_param_info info here) | ||
| 167 | # @param param_name (Enter explanation for param here) | ||
| 168 | # @return (Enter explanation for return value--(Enter explanation for return value--(Enter explanation for return value here)--here)--here) | ||
| 169 | sub get_param_info() { | ||
| 170 | my ($self, $params) = @_; | ||
| 171 | |||
| 172 | throw RWDE::DataMissingException({ info => 'No param_specified' }) | ||
| 173 | unless defined($$params{param_name}); | ||
| 174 | |||
| 175 | return $self->method_param_info()->{ $$params{param_name} }; | ||
| 176 | } | ||
| 177 | |||
| 178 | ## @method object set_return_info($return_info) | ||
| 179 | # Store return info: everything after @return | ||
| 180 | # @param return_info (Enter explanation for param here) | ||
| 181 | # @return (Enter explanation for return value--(Enter explanation for return value--(Enter explanation for return value here)--here)--here) | ||
| 182 | sub set_return_info() { | ||
| 183 | my ($self, $params) = @_; | ||
| 184 | |||
| 185 | throw RWDE::DataMissingException({ info => 'No return_info specified' }) | ||
| 186 | unless defined($$params{return_info}); | ||
| 187 | |||
| 188 | $self->method_return_info($$params{return_info}); | ||
| 189 | |||
| 190 | return (); | ||
| 191 | } | ||
| 192 | |||
| 193 | ## @method object param_list() | ||
| 194 | # This is a convenience method to simply print out an array of keys. This is what we wanted anyway. | ||
| 195 | # A hash was used simply because a set was needed. | ||
| 196 | # @return (Enter explanation for return value--(Enter explanation for return value--(Enter explanation for return value here)--here)--here) | ||
| 197 | sub param_list() { | ||
| 198 | my ($self, $params) = @_; | ||
| 199 | |||
| 200 | return sort keys %{ $self->method_params }; | ||
| 201 | } | ||
| 202 | |||
| 203 | ## @method object param_list_as_string() | ||
| 204 | # Return the params as a string, delim by ", " | ||
| 205 | # Ex: "$param1, $param2, $param3" | ||
| 206 | # @return (Enter explanation for return value--(Enter explanation for return value--(Enter explanation for return value here)--here)--here) | ||
| 207 | sub param_list_as_string() { | ||
| 208 | my ($self, $params) = @_; | ||
| 209 | |||
| 210 | my @param_list = $self->param_list(); | ||
| 211 | my $param_string; | ||
| 212 | |||
| 213 | #Join everything together as a string. Prepend every element with a '$' because they are all references. | ||
| 214 | if (scalar @param_list > 0) { | ||
| 215 | $param_string = join(', $', @param_list); | ||
| 216 | |||
| 217 | #Need to prepend the string so that the initial param will begin with '$' | ||
| 218 | $param_string = '$' . $param_string; | ||
| 219 | } | ||
| 220 | else { | ||
| 221 | $param_string = ''; | ||
| 222 | } | ||
| 223 | |||
| 224 | return $param_string; | ||
| 225 | } | ||
| 226 | |||
| 227 | ## @method object method_description() | ||
| 228 | # Print out the title of the method | ||
| 229 | # Ex. 'object new_from_file($file1, $file2)' | ||
| 230 | # @return (Enter explanation for return value--(Enter explanation for return value--(Enter explanation for return value here)--here)--here) | ||
| 231 | sub method_description() { | ||
| 232 | my ($self, $params) = @_; | ||
| 233 | |||
| 234 | #Only print out protected | ||
| 235 | my $privileges = (($self->method_privileges eq PUBLIC_METHOD) ? '' : (PROTECTED_METHOD . ' ')); | ||
| 236 | |||
| 237 | return $privileges . $self->method_return_type . ' ' . $self->method_name . '(' . $self->param_list_as_string() . ')'; | ||
| 238 | } | ||
| 239 | |||
| 240 | 1; |