mimgrating from another repo

lib/ann/fann/docs/NaturalDocs-1.52/Modules/NaturalDocs/SourceDB/Extension.pm

@@ -0,0 +1,85 @@
+###############################################################################
+#
+#   Package: NaturalDocs::SourceDB::Extension
+#
+###############################################################################
+#
+#   A base package for all <SourceDB> extensions.
+#
+###############################################################################
+
+# This file is part of Natural Docs, which is Copyright <20> 2003-2010 Greg Valure
+# Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL)
+# Refer to License.txt for the complete details
+
+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;

lib/ann/fann/docs/NaturalDocs-1.52/Modules/NaturalDocs/SourceDB/File.pm

@@ -0,0 +1,130 @@
+###############################################################################
+#
+#   Package: NaturalDocs::SourceDB::File
+#
+###############################################################################
+#
+#   A class used to index items by file.
+#
+###############################################################################
+
+# This file is part of Natural Docs, which is Copyright <20> 2003-2010 Greg Valure
+# Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL)
+# Refer to License.txt for the complete details
+
+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;

lib/ann/fann/docs/NaturalDocs-1.52/Modules/NaturalDocs/SourceDB/Item.pm

@@ -0,0 +1,202 @@
+###############################################################################
+#
+#   Package: NaturalDocs::SourceDB::Item
+#
+###############################################################################
+#
+#   A base class for something being tracked in <NaturalDocs::SourceDB>.
+#
+###############################################################################
+
+# This file is part of Natural Docs, which is Copyright <20> 2003-2010 Greg Valure
+# Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL)
+# Refer to License.txt for the complete details
+
+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;

lib/ann/fann/docs/NaturalDocs-1.52/Modules/NaturalDocs/SourceDB/ItemDefinition.pm

@@ -0,0 +1,46 @@
+###############################################################################
+#
+#   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 <20> 2003-2010 Greg Valure
+# Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL)
+# Refer to License.txt for the complete details
+
+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;

lib/ann/fann/docs/NaturalDocs-1.52/Modules/NaturalDocs/SourceDB/WatchedFileDefinitions.pm

@@ -0,0 +1,160 @@
+###############################################################################
+#
+#   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 <20> 2003-2010 Greg Valure
+# Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL)
+# Refer to License.txt for the complete details
+
+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;