diff options
Diffstat (limited to 'docs/tool/Modules/NaturalDocs/SourceDB')
| -rw-r--r-- | docs/tool/Modules/NaturalDocs/SourceDB/Extension.pm | 84 | ||||
| -rw-r--r-- | docs/tool/Modules/NaturalDocs/SourceDB/File.pm | 129 | ||||
| -rw-r--r-- | docs/tool/Modules/NaturalDocs/SourceDB/Item.pm | 201 | ||||
| -rw-r--r-- | docs/tool/Modules/NaturalDocs/SourceDB/ItemDefinition.pm | 45 | ||||
| -rw-r--r-- | docs/tool/Modules/NaturalDocs/SourceDB/WatchedFileDefinitions.pm | 159 |
5 files changed, 618 insertions, 0 deletions
diff --git a/docs/tool/Modules/NaturalDocs/SourceDB/Extension.pm b/docs/tool/Modules/NaturalDocs/SourceDB/Extension.pm new file mode 100644 index 00000000..c247ea02 --- /dev/null +++ b/docs/tool/Modules/NaturalDocs/SourceDB/Extension.pm @@ -0,0 +1,84 @@ +############################################################################### +# +# Package: NaturalDocs::SourceDB::Extension +# +############################################################################### +# +# A base package for all <SourceDB> extensions. +# +############################################################################### + +# 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::SourceDB::Extension; + + +############################################################################### +# Group: Interface Functions +# These functions must be overridden by the derived class. + + +# +# Function: Register +# +# Override this function to register the package with <NaturalDocs::SourceDB->RegisterExtension()>. +# +sub Register + { + die "Called SourceDB::Extension->Register(). This function should be overridden by every extension."; + }; + + +# +# Function: Load +# +# Called by <NaturalDocs::SourceDB->Load()> to load the extension's data. Returns whether it was successful. +# +# *This function might not be called.* If there's a situation that would cause all the source files to be reparsed anyway, +# <NaturalDocs::SourceDB> may skip calling Load() for the remaining extensions. You should *not* depend on this function +# for any critical initialization that needs to happen every time regardless. +# +sub Load # => bool + { + return 1; + }; + + +# +# Function: Save +# +# Called by <NaturalDocs::SourceDB->Save()> to save the extension's data. +# +sub Save + { + }; + + +# +# Function: OnDeletedDefinition +# +# Called for each definition deleted by <NaturalDocs::SourceDB>. This is called *after* the definition has been deleted from +# the database, so don't expect to be able to read it. +# +sub OnDeletedDefinition #(string itemString, FileName file, bool wasLastDefinition) + { + }; + + +# +# Function: OnChangedDefinition +# +# Called for each definition changed by <NaturalDocs::SourceDB>. This is called *after* the definition has been changed, so +# don't expect to be able to read the original value. +# +sub OnChangedDefinition #(string itemString, FileName file) + { + }; + + +1; diff --git a/docs/tool/Modules/NaturalDocs/SourceDB/File.pm b/docs/tool/Modules/NaturalDocs/SourceDB/File.pm new file mode 100644 index 00000000..c364c948 --- /dev/null +++ b/docs/tool/Modules/NaturalDocs/SourceDB/File.pm @@ -0,0 +1,129 @@ +############################################################################### +# +# Package: NaturalDocs::SourceDB::File +# +############################################################################### +# +# A class used to index items by file. +# +############################################################################### + +# 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::SourceDB::File; + +use NaturalDocs::DefineMembers 'ITEMS'; + + +# +# Variables: Members +# +# These constants serve as indexes into the object array. +# +# ITEMS - An arrayref where an <ExtensionID> is the index and the members are existence hashrefs of the item strigs defined +# in this file. The arrayref will always exist, but the hashrefs may be undef. +# + + +# +# Function: New +# +# Returns a new object. +# +sub New + { + my $package = shift; + + my $object = [ ]; + $object->[ITEMS] = [ ]; + + bless $object, $package; + return $object; + }; + + +# +# Function: AddItem +# +# Adds an item to this file. Returns whether this added a new item. +# +sub AddItem #(ExtensionID extension, string itemString) => bool + { + my ($self, $extension, $itemString) = @_; + + if (!defined $self->[ITEMS]->[$extension]) + { + $self->[ITEMS]->[$extension] = { $itemString => 1 }; + return 1; + } + elsif (!exists $self->[ITEMS]->[$extension]->{$itemString}) + { + $self->[ITEMS]->[$extension]->{$itemString} = 1; + return 1; + } + else + { + return 0; + }; + }; + + +# +# Function: HasItem +# +# Returns whether the item exists in this file. +# +sub HasItem #(ExtensionID extension, string itemString) => bool + { + my ($self, $extension, $itemString) = @_; + + if (defined $self->[ITEMS]->[$extension]) + { return exists $self->[ITEMS]->[$extension]->{$itemString}; } + else + { return 0; }; + }; + + +# +# Function: DeleteItem +# +# Deletes the passed item. Returns whether it existed. +# +sub DeleteItem #(ExtensionID extension, string itemString) => bool + { + my ($self, $extension, $itemString) = @_; + + if (!defined $self->[ITEMS]->[$extension]) + { return 0; } + elsif (exists $self->[ITEMS]->[$extension]->{$itemString}) + { + delete $self->[ITEMS]->[$extension]->{$itemString}; + return 1; + } + else + { return 0; }; + }; + + +# +# Function: ListItems +# +# Returns an array of all the item strings defined for a particular extension, or an empty list if none. +# +sub ListItems #(ExtensionID extension) => string array + { + my ($self, $extension) = @_; + + if (defined $self->[ITEMS]->[$extension]) + { return keys %{$self->[ITEMS]->[$extension]}; } + else + { return ( ); }; + }; + + +1; diff --git a/docs/tool/Modules/NaturalDocs/SourceDB/Item.pm b/docs/tool/Modules/NaturalDocs/SourceDB/Item.pm new file mode 100644 index 00000000..6654465c --- /dev/null +++ b/docs/tool/Modules/NaturalDocs/SourceDB/Item.pm @@ -0,0 +1,201 @@ +############################################################################### +# +# Package: NaturalDocs::SourceDB::Item +# +############################################################################### +# +# A base class for something being tracked in <NaturalDocs::SourceDB>. +# +############################################################################### + +# 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::SourceDB::Item; + +use NaturalDocs::DefineMembers 'DEFINITIONS'; + + +# +# Variables: Members +# +# The following constants are indexes into the object array. +# +# DEFINITIONS - A hashref that maps <FileNames> to either <NaturalDocs::SourceDB::ItemDefinition>-derived objects or +# serves as an existence hashref depending on whether the extension only tracks existence. Will be undef if +# there are none. +# + + +# +# Function: New +# +# Creates and returns a new object. +# +sub New + { + my $class = shift; + + my $object = [ ]; + bless $object, $class; + + return $object; + }; + + + +############################################################################### +# +# Group: Definition Functions +# +# These functions should be called by <NaturalDocs::SourceDB>. You should not be calling them directly. Call functions +# like <NaturalDocs::SourceDB->AddDefinition()> instead. +# + + +# +# Function: AddDefinition +# +# Adds a definition for the passed <FileName>. If it's already defined, the new definition will be ignored. +# +# Parameters: +# +# file - The <FileName>. +# definition - The definition, which must be an object derived from <NaturalDocs::SourceDB::ItemDefinition> or undef if +# the extension only tracks existence. +# +# Returns: +# +# Whether the definition was added, which is to say, whether this was the first definition for the passed <FileName>. +# +sub AddDefinition #(FileName file, optional NaturalDocs::SourceDB::ItemDefinition definition) => bool + { + my ($self, $file, $definition) = @_; + + if (!defined $self->[DEFINITIONS]) + { $self->[DEFINITIONS] = { }; }; + + if (!exists $self->[DEFINITIONS]->{$file}) + { + if (!defined $definition) + { $definition = 1; }; + + $self->[DEFINITIONS]->{$file} = $definition; + return 1; + } + else + { return 0; }; + }; + + +# +# Function: ChangeDefinition +# +# Changes the definition for the passed <FileName>. +# +# Parameters: +# +# file - The <FileName>. +# definition - The definition, which must be an object derived from <NaturalDocs::SourceDB::ItemDefinition>. +# +sub ChangeDefinition #(FileName file, NaturalDocs::SourceDB::ItemDefinition definition) + { + my ($self, $file, $definition) = @_; + + if (!defined $self->[DEFINITIONS] || !exists $self->[DEFINITIONS]->{$file}) + { die "Tried to change a non-existant definition in SourceD::Item."; }; + + $self->[DEFINITIONS]->{$file} = $definition; + }; + + +# +# Function: GetDefinition +# +# Returns the <NaturalDocs::SourceDB::ItemDefinition>-derived object for the passed <FileName>, non-zero if it only tracks +# existence, or undef if there is no definition. +# +sub GetDefinition #(FileName file) => NaturalDocs::SourceDB::ItemDefinition or bool + { + my ($self, $file) = @_; + + if (defined $self->[DEFINITIONS]) + { return $self->[DEFINITIONS]->{$file}; } + else + { return undef; }; + }; + + +# +# Function: DeleteDefinition +# +# Removes the definition for the passed <FileName>. Returns whether it was successful, meaning whether a definition existed +# for that file. +# +sub DeleteDefinition #(FileName file) => bool + { + my ($self, $file) = @_; + + if (defined $self->[DEFINITIONS]) + { + if (exists $self->[DEFINITIONS]->{$file}) + { + delete $self->[DEFINITIONS]->{$file}; + + if (!scalar keys %{$self->[DEFINITIONS]}) + { $self->[DEFINITIONS] = undef; }; + + return 1; + }; + }; + + return 0; + }; + + +# +# Function: HasDefinitions +# +# Returns whether there are any definitions for this item. +# +sub HasDefinitions # => bool + { + my $self = shift; + return (defined $self->[DEFINITIONS]); + }; + + +# +# Function: HasDefinition +# +# Returns whether there is a definition for the passed <FileName>. +# +sub HasDefinition #(FileName file) => bool + { + my ($self, $file) = @_; + + if (defined $self->[DEFINITIONS]) + { return (exists $self->[DEFINITIONS]->{$file}); } + else + { return 0; }; + }; + + +# +# Function: GetAllDefinitionsHashRef +# +# Returns a hashref of all the definitions of this item. *Do not change.* The keys are the <FileNames>, and the values are +# either <NaturalDocs::SourceDB::ItemDefinition>-derived objects or it's just an existence hashref if those aren't used. +# +sub GetAllDefinitionsHashRef + { + my $self = shift; + return $self->[DEFINITIONS]; + }; + + +1; diff --git a/docs/tool/Modules/NaturalDocs/SourceDB/ItemDefinition.pm b/docs/tool/Modules/NaturalDocs/SourceDB/ItemDefinition.pm new file mode 100644 index 00000000..ee053fef --- /dev/null +++ b/docs/tool/Modules/NaturalDocs/SourceDB/ItemDefinition.pm @@ -0,0 +1,45 @@ +############################################################################### +# +# Package: NaturalDocs::SourceDB::ItemDefinition +# +############################################################################### +# +# A base class for all item definitions for extensions that track more than existence. +# +############################################################################### + +# 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::SourceDB::ItemDefinition; + + +# +# Function: Compare +# +# Returns whether the definitions are equal. This version returns true by default, you must override it in your subclasses +# to make the results relevant. This is important for <NaturalDocs::SourceDB->AnalyzeTrackedFileChanges()>. +# +# This will only be called between objects of the same <ExtensionID>. If you use multiple derived classes for the same +# <ExtensionID>, you will have to take that into account yourself. +# +# Parameters: +# +# other - Another <NaturalDocs::SourceDB::ItemDefinition>-derived object to compare this one to. It will always be from +# the same <ExtensionID>. +# +# Returns: +# +# Whether they are equal. +# +sub Compare #(other) + { + return 1; + }; + + +1; diff --git a/docs/tool/Modules/NaturalDocs/SourceDB/WatchedFileDefinitions.pm b/docs/tool/Modules/NaturalDocs/SourceDB/WatchedFileDefinitions.pm new file mode 100644 index 00000000..956c6644 --- /dev/null +++ b/docs/tool/Modules/NaturalDocs/SourceDB/WatchedFileDefinitions.pm @@ -0,0 +1,159 @@ +############################################################################### +# +# Package: NaturalDocs::SourceDB::WatchedFileDefinitions +# +############################################################################### +# +# A class to track the definitions appearing in a watched file. This is only used for extensions that track definition info with +# <NaturalDocs::SourceDB::ItemDefinition>-derived objects. Do not use it for extensions that only track existence. +# +############################################################################### + +# 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::SourceDB::WatchedFileDefinitions; + + +# +# Variables: Members +# +# This object would only have one member, which is an array, so the object itself serves as that member. +# +# <ExtensionIDs> are used as indexes into this object. Each entry is a hashref that maps item strings to +# <NaturalDocs::SourceDB::ItemDefinition>-derived objects. This is only done for extensions that use those objects to track +# definitions, it's not needed for extensions that only track existence. If there are no definitions, the entry will be undef. +# + + +# +# Function: New +# +# Creates and returns a new object. +# +sub New + { + my $class = shift; + + my $object = [ ]; + bless $object, $class; + + return $object; + }; + + + +############################################################################### +# Group: Definition Functions +# + + +# +# Function: AddDefinition +# +# Adds a definition for the passed item string. If it's already defined, the new definition will be ignored. +# +# Parameters: +# +# extension - The <ExtensionID>. +# itemString - The item string. +# definition - The definition, which must be an object derived from <NaturalDocs::SourceDB::ItemDefinition>. +# +# Returns: +# +# Whether the definition was added, which is to say, whether this was the first definition for the passed <FileName>. +# +sub AddDefinition #(ExtensionID extension, string itemString, NaturalDocs::SourceDB::ItemDefinition definition) => bool + { + my ($self, $extension, $itemString, $definition) = @_; + + if (!defined $self->[$extension]) + { $self->[$extension] = { }; }; + + if (!exists $self->[$extension]->{$itemString}) + { + $self->[$extension]->{$itemString} = $definition; + return 1; + } + else + { return 0; }; + }; + + +# +# Function: GetDefinition +# +# Returns the <NaturalDocs::SourceDB::ItemDefinition>-derived object for the passed item string or undef if there is none. +# +sub GetDefinition #(ExtensionID extension, string itemString) => NaturalDocs::SourceDB::ItemDefinition + { + my ($self, $extension, $itemString) = @_; + + if (defined $self->[$extension]) + { return $self->[$extension]->{$itemString}; } + else + { return undef; }; + }; + + +# +# Function: DeleteDefinition +# +# Removes the definition for the passed item string. Returns whether it was successful, meaning whether a definition existed +# for that item. +# +sub DeleteDefinition #(ExtensionID extension, string itemString) => bool + { + my ($self, $extension, $itemString) = @_; + + if (defined $self->[$extension]) + { + if (exists $self->[$extension]->{$itemString}) + { + delete $self->[$extension]->{$itemString}; + + if (!scalar keys %{$self->[$extension]}) + { $self->[$extension] = undef; }; + + return 1; + }; + }; + + return 0; + }; + + +# +# Function: HasDefinitions +# +# Returns whether there are any definitions for this item. +# +sub HasDefinitions #(ExtensionID extension) => bool + { + my ($self, $extension) = @_; + + return (defined $self->[$extension]); + }; + + +# +# Function: HasDefinition +# +# Returns whether there is a definition for the passed item string. +# +sub HasDefinition #(ExtensionID extension, string itemString) => bool + { + my ($self, $extension, $itemString) = @_; + + if (defined $self->[$extension]) + { return (exists $self->[$extension]->{$itemString}); } + else + { return 0; }; + }; + + +1; |