Source

jqplot / extras / NaturalDocs / Modules / NaturalDocs / SymbolTable / Symbol.pm

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
###############################################################################
#
#   Package: NaturalDocs::SymbolTable::Symbol
#
###############################################################################
#
#   A class representing a symbol or a potential symbol.
#
###############################################################################

# This file is part of Natural Docs, which is Copyright (C) 2003-2008 Greg Valure
# Natural Docs is licensed under the GPL

use strict;
use integer;

package NaturalDocs::SymbolTable::Symbol;


###############################################################################
# Group: Implementation

#
#   Constants: Members
#
#   The class is implemented as a blessed arrayref.  The following constants are its members.
#
#       DEFINITIONS             - A hashref of all the files which define this symbol.  The keys are the <FileNames>, and the values are
#                                         <NaturalDocs::SymbolTable::SymbolDefinition> objects.  If no files define this symbol, this item will
#                                          be undef.
#       GLOBAL_DEFINITION  - The <FileName> which defines the global version of the symbol, which is what is used if
#                                          a file references the symbol but does not have its own definition.  If there are no definitions, this
#                                          item will be undef.
#       REFERENCES              - A hashref of the references that can be interpreted as this symbol.  This doesn't mean these
#                                          references necessarily are.  The keys are the reference strings, and the values are the scores of
#                                          the interpretations.  If no references can be interpreted as this symbol, this item will be undef.
#
use constant DEFINITIONS => 0;
use constant GLOBAL_DEFINITION => 1;
use constant REFERENCES => 2;


###############################################################################
# Group: Modification Functions

#
#   Function: New
#
#   Creates and returns a new object.
#
sub New
    {
    my $package = shift;

    # Let's make it safe, since normally you can pass values to New.  Having them just be ignored would be an obscure error.
    if (scalar @_)
        {  die "You can't pass values to NaturalDocs::SymbolTable::Symbol->New()\n";  };

    my $object = [ undef, undef, undef ];
    bless $object, $package;

    return $object;
    };

#
#   Function: AddDefinition
#
#   Adds a symbol definition.  If this is the first definition for this symbol, it will become the global definition.  If the definition
#   already exists for the file, it will be ignored.
#
#   Parameters:
#
#       file   - The <FileName> that defines the symbol.
#       type - The <TopicType> of the definition.
#       prototype - The prototype of the definition, if applicable.  Undef otherwise.
#       summary - The summary for the definition, if applicable.  Undef otherwise.
#
#   Returns:
#
#       Whether this provided the first definition for this symbol.
#
sub AddDefinition #(file, type, prototype, summary)
    {
    my ($self, $file, $type, $prototype, $summary) = @_;

    my $isFirst;

    if (!defined $self->[DEFINITIONS])
        {
        $self->[DEFINITIONS] = { };
        $self->[GLOBAL_DEFINITION] = $file;
        $isFirst = 1;
        };

    if (!exists $self->[DEFINITIONS]{$file})
        {
        $self->[DEFINITIONS]{$file} = NaturalDocs::SymbolTable::SymbolDefinition->New($type, $prototype, $summary);
        };

    return $isFirst;
    };


#
#   Function: ChangeDefinition
#
#   Changes the information about an existing definition.
#
#   Parameters:
#
#       file   - The <FileName> that defines the symbol.  Must exist.
#       type - The new <TopicType> of the definition.
#       prototype - The new prototype of the definition, if applicable.  Undef otherwise.
#       summary - The new summary of the definition, if applicable.  Undef otherwise.
#
sub ChangeDefinition #(file, type, prototype, summary)
    {
    my ($self, $file, $type, $prototype, $summary) = @_;

    if (defined $self->[DEFINITIONS] &&
        exists $self->[DEFINITIONS]{$file})
        {
        $self->[DEFINITIONS]{$file}->SetType($type);
        $self->[DEFINITIONS]{$file}->SetPrototype($prototype);
        $self->[DEFINITIONS]{$file}->SetSummary($summary);
        };
    };


#
#   Function: DeleteDefinition
#
#   Removes a symbol definition.  If the definition served as the global definition, a new one will be selected.
#
#   Parameters:
#
#       file - The <FileName> which contains definition to delete.
#
#   Returns:
#
#       Whether that was the only definition, and the symbol is now undefined.
#
sub DeleteDefinition #(file)
    {
    my ($self, $file) = @_;

    # If there are no definitions...
    if (!defined $self->[DEFINITIONS])
        {  return undef;  };

    delete $self->[DEFINITIONS]{$file};

    # If there are no more definitions...
    if (!scalar keys %{$self->[DEFINITIONS]})
        {
        $self->[DEFINITIONS] = undef;

        # If definitions was previously defined, and now is empty, we can safely assume that the global definition was just deleted
        # without checking it against $file.

        $self->[GLOBAL_DEFINITION] = undef;

        return 1;
        }

    # If there are more definitions and the global one was just deleted...
    elsif ($self->[GLOBAL_DEFINITION] eq $file)
        {
        # Which one becomes global is pretty much random.
        $self->[GLOBAL_DEFINITION] = (keys %{$self->[DEFINITIONS]})[0];
        return undef;
        };
    };


#
#   Function: AddReference
#
#   Adds a reference that can be interpreted as this symbol.  It can be, but not necessarily is.
#
#   Parameters:
#
#       referenceString - The string of the reference.
#       score                - The score of this interpretation.
#
sub AddReference #(referenceString, score)
    {
    my ($self, $referenceString, $score) = @_;

    if (!defined $self->[REFERENCES])
        {  $self->[REFERENCES] = { };  };

    $self->[REFERENCES]{$referenceString} = $score;
    };


#
#   Function: DeleteReference
#
#   Deletes a reference that can be interpreted as this symbol.
#
#   Parameters:
#
#       referenceString - The string of the reference to delete.
#
sub DeleteReference #(referenceString)
    {
    my ($self, $referenceString) = @_;

    # If there are no definitions...
    if (!defined $self->[REFERENCES])
        {  return;  };

    delete $self->[REFERENCES]{$referenceString};

    # If there are no more definitions...
    if (!scalar keys %{$self->[REFERENCES]})
        {
        $self->[REFERENCES] = undef;
        };
    };


#
#   Function: DeleteAllReferences
#
#   Removes all references that can be interpreted as this symbol.
#
sub DeleteAllReferences
    {
    $_[0]->[REFERENCES] = undef;
    };


###############################################################################
# Group: Information Functions

#
#   Function: IsDefined
#
#   Returns whether the symbol is defined anywhere or not.  If it's not, that means it's just a potential interpretation of a
#   reference.
#
sub IsDefined
    {
    return defined $_[0]->[GLOBAL_DEFINITION];
    };

#
#   Function: IsDefinedIn
#
#   Returns whether the symbol is defined in the passed <FileName>.
#
sub IsDefinedIn #(file)
    {
    my ($self, $file) = @_;
    return ($self->IsDefined() && exists $self->[DEFINITIONS]{$file});
    };


#
#   Function: Definitions
#
#   Returns an array of all the <FileNames> that define this symbol.  If none do, will return an empty array.
#
sub Definitions
    {
    my $self = shift;

    if ($self->IsDefined())
        {  return keys %{$self->[DEFINITIONS]};  }
    else
        {  return ( );  };
    };


#
#   Function: GlobalDefinition
#
#   Returns the <FileName> that contains the global definition of this symbol, or undef if the symbol isn't defined.
#
sub GlobalDefinition
    {
    return $_[0]->[GLOBAL_DEFINITION];
    };


#
#   Function: TypeDefinedIn
#
#   Returns the <TopicType> of the symbol defined in the passed <FileName>, or undef if it's not defined in that file.
#
sub TypeDefinedIn #(file)
    {
    my ($self, $file) = @_;

    if ($self->IsDefined())
        {  return $self->[DEFINITIONS]{$file}->Type();  }
    else
        {  return undef;  };
    };


#
#   Function: GlobalType
#
#   Returns the <TopicType> of the global definition, or undef if the symbol isn't defined.
#
sub GlobalType
    {
    my $self = shift;

    my $globalDefinition = $self->GlobalDefinition();

    if (!defined $globalDefinition)
        {  return undef;  }
    else
        {  return $self->[DEFINITIONS]{$globalDefinition}->Type();  };
    };


#
#   Function: PrototypeDefinedIn
#
#   Returns the prototype of symbol defined in the passed <FileName>, or undef if it doesn't exist or is not defined in that file.
#
sub PrototypeDefinedIn #(file)
    {
    my ($self, $file) = @_;

    if ($self->IsDefined())
        {  return $self->[DEFINITIONS]{$file}->Prototype();  }
    else
        {  return undef;  };
    };


#
#   Function: GlobalPrototype
#
#   Returns the prototype of the global definition.  Will be undef if it doesn't exist or the symbol isn't defined.
#
sub GlobalPrototype
    {
    my $self = shift;

    my $globalDefinition = $self->GlobalDefinition();

    if (!defined $globalDefinition)
        {  return undef;  }
    else
        {  return $self->[DEFINITIONS]{$globalDefinition}->Prototype();  };
    };


#
#   Function: SummaryDefinedIn
#
#   Returns the summary of symbol defined in the passed <FileName>, or undef if it doesn't exist or is not defined in that file.
#
sub SummaryDefinedIn #(file)
    {
    my ($self, $file) = @_;

    if ($self->IsDefined())
        {  return $self->[DEFINITIONS]{$file}->Summary();  }
    else
        {  return undef;  };
    };


#
#   Function: GlobalSummary
#
#   Returns the summary of the global definition.  Will be undef if it doesn't exist or the symbol isn't defined.
#
sub GlobalSummary
    {
    my $self = shift;

    my $globalDefinition = $self->GlobalDefinition();

    if (!defined $globalDefinition)
        {  return undef;  }
    else
        {  return $self->[DEFINITIONS]{$globalDefinition}->Summary();  };
    };


#
#   Function: HasReferences
#
#   Returns whether the symbol can be interpreted as any references.
#
sub HasReferences
    {
    return defined $_[0]->[REFERENCES];
    };

#
#   Function: References
#
#   Returns an array of all the reference strings that can be interpreted as this symbol.  If none, will return an empty array.
#
sub References
    {
    if (defined $_[0]->[REFERENCES])
        {  return keys %{$_[0]->[REFERENCES]};  }
    else
        {  return ( );  };
    };


#
#   Function: ReferencesAndScores
#
#   Returns a hash of all the references that can be interpreted as this symbol and their scores.  The keys are the reference
#   strings, and the values are the scores.  If none, will return an empty hash.
#
sub ReferencesAndScores
    {
    if (defined $_[0]->[REFERENCES])
        {  return %{$_[0]->[REFERENCES]};  }
    else
        {  return ( );  };
    };

1;