ddnet/docs/tool/Modules/NaturalDocs/ClassHierarchy/Class.pm

413 lines
11 KiB
Perl
Raw Normal View History

2008-08-02 08:21:29 +00:00
###############################################################################
#
# Class: NaturalDocs::ClassHierarchy::Class
#
###############################################################################
#
# An object that stores information about a class in the hierarchy. It does not store its <SymbolString>; it assumes that it will
# be stored in a hashref where the key is the <SymbolString>.
#
###############################################################################
# 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::ClassHierarchy::Class;
#
# Constants: Members
#
# The class is implemented as a blessed arrayref. The keys are the constants below.
#
# DEFINITIONS - An existence hashref of all the <FileNames> which define this class. Undef if none.
# PARENTS - An existence hashref of the <SymbolStrings> of all the parents this class has.
# CHILDREN - An existence hashref of the <SymbolStrings> of all the children this class has.
# PARENT_REFERENCES - A hashref of the parent <ReferenceStrings> this class has. The keys are the <ReferenceStrings>,
# and the values are existence hashrefs of all the <FileNames> that define them. Undef if none.
#
use NaturalDocs::DefineMembers 'DEFINITIONS', 'PARENTS', 'CHILDREN', 'PARENT_REFERENCES';
# Dependency: New() depends on the order of these constants, as well as the class not being derived from any other.
###############################################################################
# Group: Modification Functions
#
# Function: New
#
# Creates and returns a new class.
#
sub New
{
# Dependency: This function depends on the order of the constants, as well as the class not being derived from any other.
my ($package, $definitionFile) = @_;
my $object = [ undef, undef, undef, undef ];
bless $object, $package;
return $object;
};
#
# Function: AddDefinition
#
# Adds a rew definition of this class and returns if that was the first definition.
#
# Parameters:
#
# file - The <FileName> the definition appears in.
#
# Returns:
#
# Whether this was the first definition of this class.
#
sub AddDefinition #(file)
{
my ($self, $file) = @_;
my $wasFirst;
if (!defined $self->[DEFINITIONS])
{
$self->[DEFINITIONS] = { };
$wasFirst = 1;
};
$self->[DEFINITIONS]->{$file} = 1;
return $wasFirst;
};
#
# Function: DeleteDefinition
#
# Removes the definition of this class and returns if there are no more definitions. Note that if there are no more
# definitions, you may still want to keep the object around if <HasChildren()> returns true.
#
# Parameters:
#
# file - The <FileName> the definition appears in.
#
# Returns:
#
# Whether this deleted the last definition of this class.
#
sub DeleteDefinition #(file)
{
my ($self, $file) = @_;
if (defined $self->[DEFINITIONS])
{
delete $self->[DEFINITIONS]->{$file};
if (!scalar keys %{$self->[DEFINITIONS]})
{
$self->[DEFINITIONS] = undef;
return 1;
};
};
return undef;
};
#
# Function: AddParentReference
#
# Adds a parent reference to the class and return whether it resulted in a new parent class.
#
# Parameters:
#
# reference - The <ReferenceString> used to determine the parent.
# file - The <FileName> the parent reference is in.
# referenceTranslations - A hashref of what each reference currently resolves to. The keys are the
# <ReferenceStrings> and the values are class <SymbolStrings>. It should include an entry for
# the reference parameter above.
#
# Returns:
#
# If the reference adds a new parent, it will return that parent's <SymbolString>. Otherwise it will return undef.
#
sub AddParentReference #(reference, file, referenceTranslations)
{
my ($self, $reference, $file, $referenceTranslations) = @_;
if (!defined $self->[PARENT_REFERENCES])
{ $self->[PARENT_REFERENCES] = { }; };
if (!defined $self->[PARENTS])
{ $self->[PARENTS] = { }; };
if (!exists $self->[PARENT_REFERENCES]->{$reference})
{
$self->[PARENT_REFERENCES]->{$reference} = { $file => 1 };
my $symbol = $referenceTranslations->{$reference};
if (!exists $self->[PARENTS]->{$symbol})
{
$self->[PARENTS]->{$symbol} = 1;
return $symbol;
}
else
{ return undef; };
}
else
{
$self->[PARENT_REFERENCES]->{$reference}->{$file} = 1;
return undef;
};
};
#
# Function: DeleteParentReference
#
# Deletes a parent reference from the class and return whether it resulted in a loss of a parent class.
#
# Parameters:
#
# reference - The <ReferenceString> used to determine the parent.
# file - The <FileName> the parent declaration is in.
# referenceTranslations - A hashref of what each reference currently resolves to. The keys are the
# <ReferenceStrings> and the values are class <SymbolStrings>. It should include an entry for
# the reference parameter above.
#
# Returns:
#
# If this causes a parent class to be lost, it will return that parent's <SymbolString>. Otherwise it will return undef.
#
sub DeleteParentReference #(reference, file, referenceTranslations)
{
my ($self, $reference, $file, $referenceTranslations) = @_;
if (defined $self->[PARENT_REFERENCES] && exists $self->[PARENT_REFERENCES]->{$reference} &&
exists $self->[PARENT_REFERENCES]->{$reference}->{$file})
{
delete $self->[PARENT_REFERENCES]->{$reference}->{$file};
# Quit if there are other definitions of this reference.
if (scalar keys %{$self->[PARENT_REFERENCES]->{$reference}})
{ return undef; };
delete $self->[PARENT_REFERENCES]->{$reference};
if (!scalar keys %{$self->[PARENT_REFERENCES]})
{ $self->[PARENT_REFERENCES] = undef; };
my $parent = $referenceTranslations->{$reference};
# Check if any other references resolve to the same parent.
if (defined $self->[PARENT_REFERENCES])
{
foreach my $parentReference (keys %{$self->[PARENT_REFERENCES]})
{
if ($referenceTranslations->{$parentReference} eq $parent)
{ return undef; };
};
};
# If we got this far, no other parent references resolve to this symbol.
delete $self->[PARENTS]->{$parent};
if (!scalar keys %{$self->[PARENTS]})
{ $self->[PARENTS] = undef; };
return $parent;
}
else
{ return undef; };
};
#
# Function: AddChild
# Adds a child <SymbolString> to the class. Unlike <AddParentReference()>, this does not keep track of anything other than
# whether it has it or not.
#
# Parameters:
#
# child - The <SymbolString> to add.
#
sub AddChild #(child)
{
my ($self, $child) = @_;
if (!defined $self->[CHILDREN])
{ $self->[CHILDREN] = { }; };
$self->[CHILDREN]->{$child} = 1;
};
#
# Function: DeleteChild
# Deletes a child <SymbolString> from the class. Unlike <DeleteParentReference()>, this does not keep track of anything other
# than whether it has it or not.
#
# Parameters:
#
# child - The <SymbolString> to delete.
#
sub DeleteChild #(child)
{
my ($self, $child) = @_;
if (defined $self->[CHILDREN])
{
delete $self->[CHILDREN]->{$child};
if (!scalar keys %{$self->[CHILDREN]})
{ $self->[CHILDREN] = undef; };
};
};
###############################################################################
# Group: Information Functions
#
# Function: Definitions
# Returns an array of the <FileNames> that define this class, or an empty array if none.
#
sub Definitions
{
my ($self) = @_;
if (defined $self->[DEFINITIONS])
{ return keys %{$self->[DEFINITIONS]}; }
else
{ return ( ); };
};
#
# Function: IsDefinedIn
# Returns whether the class is defined in the passed <FileName>.
#
sub IsDefinedIn #(file)
{
my ($self, $file) = @_;
if (defined $self->[DEFINITIONS])
{ return exists $self->[DEFINITIONS]->{$file}; }
else
{ return 0; };
};
#
# Function: IsDefined
# Returns whether the class is defined in any files.
#
sub IsDefined
{
my ($self) = @_;
return defined $self->[DEFINITIONS];
};
#
# Function: ParentReferences
# Returns an array of the parent <ReferenceStrings>, or an empty array if none.
#
sub ParentReferences
{
my ($self) = @_;
if (defined $self->[PARENT_REFERENCES])
{ return keys %{$self->[PARENT_REFERENCES]}; }
else
{ return ( ); };
};
#
# Function: HasParentReference
# Returns whether the class has the passed parent <ReferenceString>.
#
sub HasParentReference #(reference)
{
my ($self, $reference) = @_;
return (defined $self->[PARENT_REFERENCES] && exists $self->[PARENT_REFERENCES]->{$reference});
};
#
# Function: HasParentReferences
# Returns whether the class has any parent <ReferenceStrings>.
#
sub HasParentReferences
{
my ($self) = @_;
return defined $self->[PARENT_REFERENCES];
};
#
# Function: Parents
# Returns an array of the parent <SymbolStrings>, or an empty array if none.
#
sub Parents
{
my ($self) = @_;
if (defined $self->[PARENTS])
{ return keys %{$self->[PARENTS]}; }
else
{ return ( ); };
};
#
# Function: HasParents
# Returns whether the class has any parent <SymbolStrings> defined.
#
sub HasParents
{
my ($self) = @_;
return defined $self->[PARENTS];
};
#
# Function: Children
# Returns an array of the child <SymbolStrings>, or an empty array if none.
#
sub Children
{
my ($self) = @_;
if (defined $self->[CHILDREN])
{ return keys %{$self->[CHILDREN]}; }
else
{ return ( ); };
};
#
# Function: HasChildren
# Returns whether any child <SymbolStrings> are defined.
#
sub HasChildren
{
my ($self) = @_;
return defined $self->[CHILDREN];
};
#
# Function: ParentReferenceDefinitions
# Returns an array of the <FileNames> which define the passed parent <ReferenceString>, or an empty array if none.
#
sub ParentReferenceDefinitions #(reference)
{
my ($self, $reference) = @_;
if (defined $self->[PARENT_REFERENCES] && exists $self->[PARENT_REFERENCES]->{$reference})
{ return keys %{$self->[PARENT_REFERENCES]->{$reference}}; }
else
{ return ( ); };
};
1;