<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">###############################################################################
#
#   Package: NaturalDocs::SymbolTable::Reference
#
###############################################################################
#
#   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::Reference;


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

#
#   Constants: Members
#
#   The class is implemented as a blessed arrayref.  The following constants are its members.
#
#       DEFINITIONS                        - An existence hashref of the &lt;FileNames&gt; that define this reference.
#       INTERPRETATIONS                - A hashref of the possible interpretations of this reference.  The keys are the &lt;SymbolStrings&gt;
#                                                     and the values are the scores.
#       CURRENT_INTERPRETATION  - The interpretation currently used as the reference target.  It will be the interpretation with
#                                                     the highest score that is actually defined.  If none are defined, this item will be undef.
#

# DEPENDENCY: New() depends on the order of these constants.  If they change, New() has to be updated.
use constant DEFINITIONS =&gt; 0;
use constant INTERPRETATIONS =&gt; 1;
use constant CURRENT_INTERPRETATION =&gt; 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::Reference-&gt;New()\n";  };

    # DEPENDENCY: This code depends on the order of the member constants.
    my $object = [ { }, { }, undef ];
    bless $object, $package;

    return $object;
    };


#
#   Function: AddDefinition
#
#   Adds a reference definition.
#
#   Parameters:
#
#       file   - The &lt;FileName&gt; that defines the reference.
#
sub AddDefinition #(file)
    {
    my ($self, $file) = @_;

    $self-&gt;[DEFINITIONS]{$file} = 1;
    };


#
#   Function: DeleteDefinition
#
#   Removes a reference definition.
#
#   Parameters:
#
#       file - The &lt;FileName&gt; which has the definition to delete.
#
sub DeleteDefinition #(file)
    {
    my ($self, $file) = @_;

    delete $self-&gt;[DEFINITIONS]{$file};
    };


#
#   Function: AddInterpretation
#
#   Adds a symbol that this reference can be interpreted as.
#
#   Parameters:
#
#       symbol  - The &lt;SymbolString&gt;.
#       score     - The score of this interpretation.
#
sub AddInterpretation #(symbol, score)
    {
    my ($self, $symbol, $score) = @_;

    $self-&gt;[INTERPRETATIONS]{$symbol} = $score;
    };


#
#   Function: DeleteInterpretation
#
#   Deletes a symbol that this reference can be interpreted as.
#
#   Parameters:
#
#       symbol - The &lt;SymbolString&gt; to delete.
#
sub DeleteInterpretation #(symbol)
    {
    my ($self, $symbol) = @_;

    delete $self-&gt;[INTERPRETATIONS]{$symbol};
    };


#
#   Function: DeleteAllInterpretationsButCurrent
#
#   Deletes all interpretations except for the current one.
#
sub DeleteAllInterpretationsButCurrent
    {
    my $self = shift;

    if ($self-&gt;HasCurrentInterpretation())
        {
        my $score = $self-&gt;CurrentScore();

        # Fastest way to clear a hash except for one item?  Make a new hash with just that item.
        %{$self-&gt;[INTERPRETATIONS]} = ( $self-&gt;[CURRENT_INTERPRETATION] =&gt; $score );
        };
    };


#
#   Function: SetCurrentInterpretation
#
#   Changes the current interpretation.  The new one must already have been added via &lt;AddInterpretation()&gt;.
#
#   Parameters:
#
#       symbol - The &lt;SymbolString&gt;l to make the current interpretation.  Can be set to undef to clear it.
#
sub SetCurrentInterpretation #(symbol)
    {
    my ($self, $symbol) = @_;

    $self-&gt;[CURRENT_INTERPRETATION] = $symbol;
    };


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


#
#   Function: Definitions
#
#   Returns an array of all the &lt;FileNames&gt; that define this reference.  If none do, returns an empty array.
#
sub Definitions
    {
    return keys %{$_[0]-&gt;[DEFINITIONS]};
    };


#
#   Function: IsDefined
#
#   Returns whether the reference has any definitions or not.
#
sub IsDefined
    {
    return scalar keys %{$_[0]-&gt;[DEFINITIONS]};
    };


#
#   Function: IsDefinedIn
#
#   Returns whether the reference is defined in the passed &lt;FileName&gt;.
#
sub IsDefinedIn #(file)
    {
    my ($self, $file) = @_;

    return exists $self-&gt;[DEFINITIONS]{$file};
    };


#
#   Function: Interpretations
#
#   Returns an array of all the &lt;SymbolStrings&gt; that this reference can be interpreted as.  If none, returns an empty array.
#
sub Interpretations
    {
    return keys %{$_[0]-&gt;[INTERPRETATIONS]};
    };


#
#   Function: InterpretationsAndScores
#
#   Returns a hash of all the &lt;SymbolStrings&gt; that this reference can be interpreted as and their scores.  The keys are the &lt;SymbolStrings&gt;
#   and the values are the scores.  If none, returns an empty hash.
#
sub InterpretationsAndScores
    {
    return %{$_[0]-&gt;[INTERPRETATIONS]};
    };


#
#   Function: HasCurrentInterpretation
#
#   Returns whether the reference has a current interpretation or not.
#
sub HasCurrentInterpretation
    {
    return defined $_[0]-&gt;[CURRENT_INTERPRETATION];
    };


#
#   Function: CurrentInterpretation
#
#   Returns the &lt;SymbolString&gt; of the current interpretation, or undef if none.
#
sub CurrentInterpretation
    {
    return $_[0]-&gt;[CURRENT_INTERPRETATION];
    };


#
#   Function: CurrentScore
#
#   Returns the score of the current interpretation, or undef if none.
#
sub CurrentScore
    {
    my $self = shift;

    if (defined $self-&gt;[CURRENT_INTERPRETATION])
        {
        return $self-&gt;[INTERPRETATIONS]{ $self-&gt;[CURRENT_INTERPRETATION] };
        }
    else
        {  return undef;  };
    };


1;
</pre></body></html>