bixbite 0.1.0

data/template/assets/naturaldocs/NaturalDocs/Modules/NaturalDocs/SymbolTable/Reference.pm

@@ -0,0 +1,273 @@
+###############################################################################
+#
+#   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 <FileNames> that define this reference.
+#       INTERPRETATIONS                - A hashref of the possible interpretations of this reference.  The keys are the <SymbolStrings>
+#                                                     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 => 0;
+use constant INTERPRETATIONS => 1;
+use constant CURRENT_INTERPRETATION => 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->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 <FileName> that defines the reference.
+#
+sub AddDefinition #(file)
+    {
+    my ($self, $file) = @_;
+
+    $self->[DEFINITIONS]{$file} = 1;
+    };
+
+
+#
+#   Function: DeleteDefinition
+#
+#   Removes a reference definition.
+#
+#   Parameters:
+#
+#       file - The <FileName> which has the definition to delete.
+#
+sub DeleteDefinition #(file)
+    {
+    my ($self, $file) = @_;
+
+    delete $self->[DEFINITIONS]{$file};
+    };
+
+
+#
+#   Function: AddInterpretation
+#
+#   Adds a symbol that this reference can be interpreted as.
+#
+#   Parameters:
+#
+#       symbol  - The <SymbolString>.
+#       score     - The score of this interpretation.
+#
+sub AddInterpretation #(symbol, score)
+    {
+    my ($self, $symbol, $score) = @_;
+
+    $self->[INTERPRETATIONS]{$symbol} = $score;
+    };
+
+
+#
+#   Function: DeleteInterpretation
+#
+#   Deletes a symbol that this reference can be interpreted as.
+#
+#   Parameters:
+#
+#       symbol - The <SymbolString> to delete.
+#
+sub DeleteInterpretation #(symbol)
+    {
+    my ($self, $symbol) = @_;
+
+    delete $self->[INTERPRETATIONS]{$symbol};
+    };
+
+
+#
+#   Function: DeleteAllInterpretationsButCurrent
+#
+#   Deletes all interpretations except for the current one.
+#
+sub DeleteAllInterpretationsButCurrent
+    {
+    my $self = shift;
+
+    if ($self->HasCurrentInterpretation())
+        {
+        my $score = $self->CurrentScore();
+
+        # Fastest way to clear a hash except for one item?  Make a new hash with just that item.
+        %{$self->[INTERPRETATIONS]} = ( $self->[CURRENT_INTERPRETATION] => $score );
+        };
+    };
+
+
+#
+#   Function: SetCurrentInterpretation
+#
+#   Changes the current interpretation.  The new one must already have been added via <AddInterpretation()>.
+#
+#   Parameters:
+#
+#       symbol - The <SymbolString>l to make the current interpretation.  Can be set to undef to clear it.
+#
+sub SetCurrentInterpretation #(symbol)
+    {
+    my ($self, $symbol) = @_;
+
+    $self->[CURRENT_INTERPRETATION] = $symbol;
+    };
+
+
+###############################################################################
+# Group: Information Functions
+
+
+#
+#   Function: Definitions
+#
+#   Returns an array of all the <FileNames> that define this reference.  If none do, returns an empty array.
+#
+sub Definitions
+    {
+    return keys %{$_[0]->[DEFINITIONS]};
+    };
+
+
+#
+#   Function: IsDefined
+#
+#   Returns whether the reference has any definitions or not.
+#
+sub IsDefined
+    {
+    return scalar keys %{$_[0]->[DEFINITIONS]};
+    };
+
+
+#
+#   Function: IsDefinedIn
+#
+#   Returns whether the reference is defined in the passed <FileName>.
+#
+sub IsDefinedIn #(file)
+    {
+    my ($self, $file) = @_;
+
+    return exists $self->[DEFINITIONS]{$file};
+    };
+
+
+#
+#   Function: Interpretations
+#
+#   Returns an array of all the <SymbolStrings> that this reference can be interpreted as.  If none, returns an empty array.
+#
+sub Interpretations
+    {
+    return keys %{$_[0]->[INTERPRETATIONS]};
+    };
+
+
+#
+#   Function: InterpretationsAndScores
+#
+#   Returns a hash of all the <SymbolStrings> that this reference can be interpreted as and their scores.  The keys are the <SymbolStrings>
+#   and the values are the scores.  If none, returns an empty hash.
+#
+sub InterpretationsAndScores
+    {
+    return %{$_[0]->[INTERPRETATIONS]};
+    };
+
+
+#
+#   Function: HasCurrentInterpretation
+#
+#   Returns whether the reference has a current interpretation or not.
+#
+sub HasCurrentInterpretation
+    {
+    return defined $_[0]->[CURRENT_INTERPRETATION];
+    };
+
+
+#
+#   Function: CurrentInterpretation
+#
+#   Returns the <SymbolString> of the current interpretation, or undef if none.
+#
+sub CurrentInterpretation
+    {
+    return $_[0]->[CURRENT_INTERPRETATION];
+    };
+
+
+#
+#   Function: CurrentScore
+#
+#   Returns the score of the current interpretation, or undef if none.
+#
+sub CurrentScore
+    {
+    my $self = shift;
+
+    if (defined $self->[CURRENT_INTERPRETATION])
+        {
+        return $self->[INTERPRETATIONS]{ $self->[CURRENT_INTERPRETATION] };
+        }
+    else
+        {  return undef;  };
+    };
+
+
+1;

data/template/assets/naturaldocs/NaturalDocs/Modules/NaturalDocs/SymbolTable/ReferenceTarget.pm

@@ -0,0 +1,97 @@
+###############################################################################
+#
+#   Class: NaturalDocs::SymbolTable::ReferenceTarget
+#
+###############################################################################
+#
+#   A class for storing information about a reference target.
+#
+###############################################################################
+
+# 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::ReferenceTarget;
+
+
+###############################################################################
+# Group: Implementation
+
+#
+#   Constants: Members
+#
+#   The class is implemented as a blessed arrayref.  The following constants are its members.
+#
+#       SYMBOL  - The target <SymbolString>.
+#       FILE        - The <FileName> the target is defined in.
+#       TYPE       - The target <TopicType>.
+#       PROTOTYPE - The target's prototype, or undef if none.
+#       SUMMARY    - The target's summary, or undef if none.
+#
+
+# DEPENDENCY: New() depends on the order of these constants.  If they change, New() has to be updated.
+use constant SYMBOL => 0;
+use constant FILE => 1;
+use constant TYPE => 2;
+use constant PROTOTYPE => 3;
+use constant SUMMARY => 4;
+
+###############################################################################
+# Group: Functions
+
+
+#
+#   Function: New
+#
+#   Creates and returns a new object.
+#
+#   Parameters:
+#
+#       symbol - The target <SymbolString>.
+#       file       - The <FileName> the target is defined in.
+#       type     - The <TopicType> of the target symbol.
+#       prototype - The target's prototype.  Set to undef if not defined or not applicable.
+#       summary - The target's summary.  Set to undef if not defined or not applicable.
+#
+sub New #(symbol, file, type, prototype, summary)
+    {
+    # DEPENDENCY: This code depends on the order of the member constants.
+
+    my $package = shift;
+
+    my $object = [ @_ ];
+    bless $object, $package;
+
+    return $object;
+    };
+
+
+# Function: Symbol
+# Returns the target's <SymbolString>.
+sub Symbol
+    {  return $_[0]->[SYMBOL];  };
+
+# Function: File
+# Returns the <FileName> the target is defined in.
+sub File
+    {  return $_[0]->[FILE];  };
+
+# Function: Type
+# Returns the target's <TopicType>.
+sub Type
+    {  return $_[0]->[TYPE];  };
+
+# Function: Prototype
+# Returns the target's prototype, or undef if not defined or not applicable.
+sub Prototype
+    {  return $_[0]->[PROTOTYPE];  };
+
+# Function: Summary
+# Returns the target's summary, or undef if not defined or not applicable.
+sub Summary
+    {  return $_[0]->[SUMMARY];  };
+
+1;

data/template/assets/naturaldocs/NaturalDocs/Modules/NaturalDocs/SymbolTable/Symbol.pm

@@ -0,0 +1,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;