GPL_bin_fullset/NaturalDocs/Modules/NaturalDocs/SymbolTable/Symbol.pm

   1 ###############################################################################
   2 #
   3 #   Package: NaturalDocs::SymbolTable::Symbol
   4 #
   5 ###############################################################################
   6 #
   7 #   A class representing a symbol or a potential symbol.
   8 #
   9 ###############################################################################
  10
  11 # This file is part of Natural Docs, which is Copyright © 2003-2010 Greg Valure
  12 # Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL)
  13 # Refer to License.txt for the complete details
  14
  15 use strict;
  16 use integer;
  17
  18 package NaturalDocs::SymbolTable::Symbol;
  19
  20
  21 ###############################################################################
  22 # Group: Implementation
  23
  24 #
  25 #   Constants: Members
  26 #
  27 #   The class is implemented as a blessed arrayref.  The following constants are its members.
  28 #
  29 #       DEFINITIONS             - A hashref of all the files which define this symbol.  The keys are the <FileNames>, and the values are
  30 #                                         <NaturalDocs::SymbolTable::SymbolDefinition> objects.  If no files define this symbol, this item will
  31 #                                          be undef.
  32 #       GLOBAL_DEFINITION  - The <FileName> which defines the global version of the symbol, which is what is used if
  33 #                                          a file references the symbol but does not have its own definition.  If there are no definitions, this
  34 #                                          item will be undef.
  35 #       REFERENCES              - A hashref of the references that can be interpreted as this symbol.  This doesn't mean these
  36 #                                          references necessarily are.  The keys are the reference strings, and the values are the scores of
  37 #                                          the interpretations.  If no references can be interpreted as this symbol, this item will be undef.
  38 #
  39 use constant DEFINITIONS => 0;
  40 use constant GLOBAL_DEFINITION => 1;
  41 use constant REFERENCES => 2;
  42
  43
  44 ###############################################################################
  45 # Group: Modification Functions
  46
  47 #
  48 #   Function: New
  49 #
  50 #   Creates and returns a new object.
  51 #
  52 sub New
  53     {
  54     my $package = shift;
  55
  56     # Let's make it safe, since normally you can pass values to New.  Having them just be ignored would be an obscure error.
  57     if (scalar @_)
  58         {  die "You can't pass values to NaturalDocs::SymbolTable::Symbol->New()\n";  };
  59
  60     my $object = [ undef, undef, undef ];
  61     bless $object, $package;
  62
  63     return $object;
  64     };
  65
  66 #
  67 #   Function: AddDefinition
  68 #
  69 #   Adds a symbol definition.  If this is the first definition for this symbol, it will become the global definition.  If the definition
  70 #   already exists for the file, it will be ignored.
  71 #
  72 #   Parameters:
  73 #
  74 #       file   - The <FileName> that defines the symbol.
  75 #       type - The <TopicType> of the definition.
  76 #       prototype - The prototype of the definition, if applicable.  Undef otherwise.
  77 #       summary - The summary for the definition, if applicable.  Undef otherwise.
  78 #
  79 #   Returns:
  80 #
  81 #       Whether this provided the first definition for this symbol.
  82 #
  83 sub AddDefinition #(file, type, prototype, summary)
  84     {
  85     my ($self, $file, $type, $prototype, $summary) = @_;
  86
  87     my $isFirst;
  88
  89     if (!defined $self->[DEFINITIONS])
  90         {
  91         $self->[DEFINITIONS] = { };
  92         $self->[GLOBAL_DEFINITION] = $file;
  93         $isFirst = 1;
  94         };
  95
  96     if (!exists $self->[DEFINITIONS]{$file})
  97         {
  98         $self->[DEFINITIONS]{$file} = NaturalDocs::SymbolTable::SymbolDefinition->New($type, $prototype, $summary);
  99         };
 100
 101     return $isFirst;
 102     };
 103
 104
 105 #
 106 #   Function: ChangeDefinition
 107 #
 108 #   Changes the information about an existing definition.
 109 #
 110 #   Parameters:
 111 #
 112 #       file   - The <FileName> that defines the symbol.  Must exist.
 113 #       type - The new <TopicType> of the definition.
 114 #       prototype - The new prototype of the definition, if applicable.  Undef otherwise.
 115 #       summary - The new summary of the definition, if applicable.  Undef otherwise.
 116 #
 117 sub ChangeDefinition #(file, type, prototype, summary)
 118     {
 119     my ($self, $file, $type, $prototype, $summary) = @_;
 120
 121     if (defined $self->[DEFINITIONS] &&
 122         exists $self->[DEFINITIONS]{$file})
 123         {
 124         $self->[DEFINITIONS]{$file}->SetType($type);
 125         $self->[DEFINITIONS]{$file}->SetPrototype($prototype);
 126         $self->[DEFINITIONS]{$file}->SetSummary($summary);
 127         };
 128     };
 129
 130
 131 #
 132 #   Function: DeleteDefinition
 133 #
 134 #   Removes a symbol definition.  If the definition served as the global definition, a new one will be selected.
 135 #
 136 #   Parameters:
 137 #
 138 #       file - The <FileName> which contains definition to delete.
 139 #
 140 #   Returns:
 141 #
 142 #       Whether that was the only definition, and the symbol is now undefined.
 143 #
 144 sub DeleteDefinition #(file)
 145     {
 146     my ($self, $file) = @_;
 147
 148     # If there are no definitions...
 149     if (!defined $self->[DEFINITIONS])
 150         {  return undef;  };
 151
 152     delete $self->[DEFINITIONS]{$file};
 153
 154     # If there are no more definitions...
 155     if (!scalar keys %{$self->[DEFINITIONS]})
 156         {
 157         $self->[DEFINITIONS] = undef;
 158
 159         # If definitions was previously defined, and now is empty, we can safely assume that the global definition was just deleted
 160         # without checking it against $file.
 161
 162         $self->[GLOBAL_DEFINITION] = undef;
 163
 164         return 1;
 165         }
 166
 167     # If there are more definitions and the global one was just deleted...
 168     elsif ($self->[GLOBAL_DEFINITION] eq $file)
 169         {
 170         # Which one becomes global is pretty much random.
 171         $self->[GLOBAL_DEFINITION] = (keys %{$self->[DEFINITIONS]})[0];
 172         return undef;
 173         };
 174     };
 175
 176
 177 #
 178 #   Function: AddReference
 179 #
 180 #   Adds a reference that can be interpreted as this symbol.  It can be, but not necessarily is.
 181 #
 182 #   Parameters:
 183 #
 184 #       referenceString - The string of the reference.
 185 #       score                - The score of this interpretation.
 186 #
 187 sub AddReference #(referenceString, score)
 188     {
 189     my ($self, $referenceString, $score) = @_;
 190
 191     if (!defined $self->[REFERENCES])
 192         {  $self->[REFERENCES] = { };  };
 193
 194     $self->[REFERENCES]{$referenceString} = $score;
 195     };
 196
 197
 198 #
 199 #   Function: DeleteReference
 200 #
 201 #   Deletes a reference that can be interpreted as this symbol.
 202 #
 203 #   Parameters:
 204 #
 205 #       referenceString - The string of the reference to delete.
 206 #
 207 sub DeleteReference #(referenceString)
 208     {
 209     my ($self, $referenceString) = @_;
 210
 211     # If there are no definitions...
 212     if (!defined $self->[REFERENCES])
 213         {  return;  };
 214
 215     delete $self->[REFERENCES]{$referenceString};
 216
 217     # If there are no more definitions...
 218     if (!scalar keys %{$self->[REFERENCES]})
 219         {
 220         $self->[REFERENCES] = undef;
 221         };
 222     };
 223
 224
 225 #
 226 #   Function: DeleteAllReferences
 227 #
 228 #   Removes all references that can be interpreted as this symbol.
 229 #
 230 sub DeleteAllReferences
 231     {
 232     $_[0]->[REFERENCES] = undef;
 233     };
 234
 235
 236 ###############################################################################
 237 # Group: Information Functions
 238
 239 #
 240 #   Function: IsDefined
 241 #
 242 #   Returns whether the symbol is defined anywhere or not.  If it's not, that means it's just a potential interpretation of a
 243 #   reference.
 244 #
 245 sub IsDefined
 246     {
 247     return defined $_[0]->[GLOBAL_DEFINITION];
 248     };
 249
 250 #
 251 #   Function: IsDefinedIn
 252 #
 253 #   Returns whether the symbol is defined in the passed <FileName>.
 254 #
 255 sub IsDefinedIn #(file)
 256     {
 257     my ($self, $file) = @_;
 258     return ($self->IsDefined() && exists $self->[DEFINITIONS]{$file});
 259     };
 260
 261
 262 #
 263 #   Function: Definitions
 264 #
 265 #   Returns an array of all the <FileNames> that define this symbol.  If none do, will return an empty array.
 266 #
 267 sub Definitions
 268     {
 269     my $self = shift;
 270
 271     if ($self->IsDefined())
 272         {  return keys %{$self->[DEFINITIONS]};  }
 273     else
 274         {  return ( );  };
 275     };
 276
 277
 278 #
 279 #   Function: GlobalDefinition
 280 #
 281 #   Returns the <FileName> that contains the global definition of this symbol, or undef if the symbol isn't defined.
 282 #
 283 sub GlobalDefinition
 284     {
 285     return $_[0]->[GLOBAL_DEFINITION];
 286     };
 287
 288
 289 #
 290 #   Function: TypeDefinedIn
 291 #
 292 #   Returns the <TopicType> of the symbol defined in the passed <FileName>, or undef if it's not defined in that file.
 293 #
 294 sub TypeDefinedIn #(file)
 295     {
 296     my ($self, $file) = @_;
 297
 298     if ($self->IsDefined())
 299         {  return $self->[DEFINITIONS]{$file}->Type();  }
 300     else
 301         {  return undef;  };
 302     };
 303
 304
 305 #
 306 #   Function: GlobalType
 307 #
 308 #   Returns the <TopicType> of the global definition, or undef if the symbol isn't defined.
 309 #
 310 sub GlobalType
 311     {
 312     my $self = shift;
 313
 314     my $globalDefinition = $self->GlobalDefinition();
 315
 316     if (!defined $globalDefinition)
 317         {  return undef;  }
 318     else
 319         {  return $self->[DEFINITIONS]{$globalDefinition}->Type();  };
 320     };
 321
 322
 323 #
 324 #   Function: PrototypeDefinedIn
 325 #
 326 #   Returns the prototype of symbol defined in the passed <FileName>, or undef if it doesn't exist or is not defined in that file.
 327 #
 328 sub PrototypeDefinedIn #(file)
 329     {
 330     my ($self, $file) = @_;
 331
 332     if ($self->IsDefined())
 333         {  return $self->[DEFINITIONS]{$file}->Prototype();  }
 334     else
 335         {  return undef;  };
 336     };
 337
 338
 339 #
 340 #   Function: GlobalPrototype
 341 #
 342 #   Returns the prototype of the global definition.  Will be undef if it doesn't exist or the symbol isn't defined.
 343 #
 344 sub GlobalPrototype
 345     {
 346     my $self = shift;
 347
 348     my $globalDefinition = $self->GlobalDefinition();
 349
 350     if (!defined $globalDefinition)
 351         {  return undef;  }
 352     else
 353         {  return $self->[DEFINITIONS]{$globalDefinition}->Prototype();  };
 354     };
 355
 356
 357 #
 358 #   Function: SummaryDefinedIn
 359 #
 360 #   Returns the summary of symbol defined in the passed <FileName>, or undef if it doesn't exist or is not defined in that file.
 361 #
 362 sub SummaryDefinedIn #(file)
 363     {
 364     my ($self, $file) = @_;
 365
 366     if ($self->IsDefined())
 367         {  return $self->[DEFINITIONS]{$file}->Summary();  }
 368     else
 369         {  return undef;  };
 370     };
 371
 372
 373 #
 374 #   Function: GlobalSummary
 375 #
 376 #   Returns the summary of the global definition.  Will be undef if it doesn't exist or the symbol isn't defined.
 377 #
 378 sub GlobalSummary
 379     {
 380     my $self = shift;
 381
 382     my $globalDefinition = $self->GlobalDefinition();
 383
 384     if (!defined $globalDefinition)
 385         {  return undef;  }
 386     else
 387         {  return $self->[DEFINITIONS]{$globalDefinition}->Summary();  };
 388     };
 389
 390
 391 #
 392 #   Function: HasReferences
 393 #
 394 #   Returns whether the symbol can be interpreted as any references.
 395 #
 396 sub HasReferences
 397     {
 398     return defined $_[0]->[REFERENCES];
 399     };
 400
 401 #
 402 #   Function: References
 403 #
 404 #   Returns an array of all the reference strings that can be interpreted as this symbol.  If none, will return an empty array.
 405 #
 406 sub References
 407     {
 408     if (defined $_[0]->[REFERENCES])
 409         {  return keys %{$_[0]->[REFERENCES]};  }
 410     else
 411         {  return ( );  };
 412     };
 413
 414
 415 #
 416 #   Function: ReferencesAndScores
 417 #
 418 #   Returns a hash of all the references that can be interpreted as this symbol and their scores.  The keys are the reference
 419 #   strings, and the values are the scores.  If none, will return an empty hash.
 420 #
 421 sub ReferencesAndScores
 422     {
 423     if (defined $_[0]->[REFERENCES])
 424         {  return %{$_[0]->[REFERENCES]};  }
 425     else
 426         {  return ( );  };
 427     };
 428
 429 1;