bixbite 0.1.0

data/template/assets/naturaldocs/NaturalDocs/Modules/NaturalDocs/ImageReferenceTable.pm

@@ -0,0 +1,383 @@
+###############################################################################
+#
+#   Package: NaturalDocs::ImageReferenceTable
+#
+###############################################################################
+#
+#   A <NaturalDocs::SourceDB>-based package that manages all the image references appearing in source files.
+#
+###############################################################################
+
+# 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;
+
+use NaturalDocs::ImageReferenceTable::String;
+use NaturalDocs::ImageReferenceTable::Reference;
+
+
+package NaturalDocs::ImageReferenceTable;
+
+use base 'NaturalDocs::SourceDB::Extension';
+
+
+###############################################################################
+# Group: Information
+
+#
+#   Topic: Usage
+#
+#       - <NaturalDocs::Project> and <NaturalDocs::SourceDB> must be initialized before this package can be used.
+#
+#       - Call <Register()> before using.
+#
+#
+#   Topic: Programming Notes
+#
+#       When working on this code, remember that there are three things it has to juggle.
+#
+#       - The information in <NaturalDocs::SourceDB>.
+#       - Image file references in <NaturalDocs::Project>.
+#       - Source file rebuilding on changes.
+#
+#       Managing the actual image files will be handled between <NaturalDocs::Project> and the <NaturalDocs::Builder>
+#       sub-packages.
+#
+#
+#   Topic: Implementation
+#
+#       Managing image references is simpler than managing the references in <NaturalDocs::SymbolTable>.  In SymbolTable,
+#       you have to worry about reference targets popping into and out of existence.  A link may go to a file that hasn't been
+#       reparsed yet and the target may no longer exist.  We have to deal with that when we know it, which may be after the
+#       reference's file was parsed.  Also, a new definition may appear that serves as a better interpretation of a link than its
+#       current target, and again we may only know that after the reference's file has been parsed already.  So we have to deal
+#       with scores and potential symbols and each symbol knowing exactly what links to it and so forth.
+#
+#       Not so with image references.  All possible targets (all possible image files) are known by <NaturalDocs::Project> early
+#       on and will remain consistent throughout execution.  So because of that, we can get away with only storing reference
+#       counts with each image and determining exactly where a reference points to as we find them.
+#
+#       Reference counts are stored with the image file information in <NaturalDocs::Project>.  However, it is not loaded and
+#       saved to disk by it.  Rather, it is regenerated by this package when it loads <ImageReferenceTable.nd>.
+#       NaturalDocs::Project only stores the last modification time (so it can add files to the build list if they've changed) and
+#       whether it had any references at all on the last run (so it knows whether it should care if they've changed.)
+#       ImageReferenceTable.nd stores each reference's target, width, and height.  Whether their interpretations have changed is
+#       dealt with in the <Load()> function, again since the list of targets (image files) is constant.
+#
+#       The package is based on <NaturalDocs::SourceDB>, so read it's documentation for more information on how it works.
+#
+
+
+###############################################################################
+# Group: Variables
+
+
+#
+#   var: extensionID
+#   The <ExtensionID> granted by <NaturalDocs::SourceDB>.
+#
+my $extensionID;
+
+
+
+###############################################################################
+# Group: Files
+
+
+#
+#   File: ImageReferenceTable.nd
+#
+#   The data file which stores all the image references from the last run of Natural Docs.
+#
+#   Format:
+#
+#       > [Standard Binary Header]
+#
+#       It starts with the standard binary header from <NaturalDocs::BinaryFile>.
+#
+#       > [Image Reference String or undef]
+#       > [AString16: target file]
+#       > [UInt16: target width or 0]
+#       > [UInt16: target height or 0]
+#
+#       For each <ImageReferenceString>, it's target, width, and height are stored.  The target is needed so we can tell if it
+#       changed from the last run, and the dimensions are needed because if the target hasn't changed but the file's dimensions
+#       have, the source files need to be rebuilt.
+#
+#       <ImageReferenceStrings> are encoded by <NaturalDocs::ImageReferenceTable::String>.
+#
+#       > [AString16: definition file or undef] ...
+#
+#       Then comes a series of AString16s for all the files that define the reference until it hits an undef.
+#
+#       This whole series is repeated for each <ImageReferenceString> until it hits an undef.
+#
+#	Revisions:
+#
+#		1.4:
+#
+#			- The file was added to Natural Docs.
+#
+
+
+
+###############################################################################
+# Group: Functions
+
+
+#
+#   Function: Register
+#   Registers the package with <NaturalDocs::SourceDB>.
+#
+sub Register
+    {
+    my $self = shift;
+    $extensionID = NaturalDocs::SourceDB->RegisterExtension($self, 0);
+    };
+
+
+#
+#   Function: Load
+#
+#   Loads the data from <ImageReferenceTable.nd>.  Returns whether it was successful.
+#
+sub Load # => bool
+    {
+    my $self = shift;
+
+    if (NaturalDocs::Settings->RebuildData())
+        {  return 0;  };
+
+    # The file format hasn't changed since it was introduced.
+    if (!NaturalDocs::BinaryFile->OpenForReading( NaturalDocs::Project->DataFile('ImageReferenceTable.nd') ))
+        {  return 0;  };
+
+
+    # [Image Reference String or undef]
+    while (my $referenceString = NaturalDocs::ImageReferenceTable::String->FromBinaryFile())
+        {
+        NaturalDocs::SourceDB->AddItem($extensionID, $referenceString,
+                                                           NaturalDocs::ImageReferenceTable::Reference->New());
+
+        # [AString16: target file]
+        # [UInt16: target width or 0]
+        # [UInt16: target height or 0]
+
+        my $targetFile = NaturalDocs::BinaryFile->GetAString16();
+        my $width = NaturalDocs::BinaryFile->GetUInt16();
+        my $height = NaturalDocs::BinaryFile->GetUInt16();
+
+        my $newTargetFile = $self->SetReferenceTarget($referenceString);
+        my $newWidth;
+        my $newHeight;
+
+        if ($newTargetFile)
+            {
+            NaturalDocs::Project->AddImageFileReference($newTargetFile);
+            ($newWidth, $newHeight) = NaturalDocs::Project->ImageFileDimensions($newTargetFile);
+            };
+
+        my $rebuildDefinitions = ($newTargetFile ne $targetFile || $newWidth != $width || $newHeight != $height);
+
+
+        # [AString16: definition file or undef] ...
+        while (my $definitionFile = NaturalDocs::BinaryFile->GetAString16())
+            {
+            NaturalDocs::SourceDB->AddDefinition($extensionID, $referenceString, $definitionFile);
+
+            if ($rebuildDefinitions)
+                {  NaturalDocs::Project->RebuildFile($definitionFile);  };
+            };
+        };
+
+
+    NaturalDocs::BinaryFile->Close();
+    return 1;
+    };
+
+
+#
+#   Function: Save
+#
+#   Saves the data to <ImageReferenceTable.nd>.
+#
+sub Save
+    {
+    my $self = shift;
+
+    my $references = NaturalDocs::SourceDB->GetAllItemsHashRef($extensionID);
+
+    NaturalDocs::BinaryFile->OpenForWriting( NaturalDocs::Project->DataFile('ImageReferenceTable.nd') );
+
+    while (my ($referenceString, $referenceObject) = each %$references)
+        {
+        # [Image Reference String or undef]
+        # [AString16: target file]
+        # [UInt16: target width or 0]
+        # [UInt16: target height or 0]
+
+        NaturalDocs::ImageReferenceTable::String->ToBinaryFile($referenceString);
+
+        my $target = $referenceObject->Target();
+        my ($width, $height);
+
+        if ($target)
+            {  ($width, $height) = NaturalDocs::Project->ImageFileDimensions($target);  };
+
+        NaturalDocs::BinaryFile->WriteAString16( $referenceObject->Target() );
+        NaturalDocs::BinaryFile->WriteUInt16( ($width || 0) );
+        NaturalDocs::BinaryFile->WriteUInt16( ($height || 0) );
+
+        # [AString16: definition file or undef] ...
+
+        my $definitions = $referenceObject->GetAllDefinitionsHashRef();
+
+        foreach my $definition (keys %$definitions)
+            {  NaturalDocs::BinaryFile->WriteAString16($definition);  };
+
+        NaturalDocs::BinaryFile->WriteAString16(undef);
+        };
+
+    NaturalDocs::ImageReferenceTable::String->ToBinaryFile(undef);
+
+    NaturalDocs::BinaryFile->Close();
+    };
+
+
+#
+#   Function: AddReference
+#
+#   Adds a new image reference.
+#
+sub AddReference #(FileName file, string referenceText)
+    {
+    my ($self, $file, $referenceText) = @_;
+
+    my $referenceString = NaturalDocs::ImageReferenceTable::String->Make($file, $referenceText);
+
+    if (!NaturalDocs::SourceDB->HasItem($extensionID, $referenceString))
+        {
+        my $referenceObject = NaturalDocs::ImageReferenceTable::Reference->New();
+        NaturalDocs::SourceDB->AddItem($extensionID, $referenceString, $referenceObject);
+
+        my $target = $self->SetReferenceTarget($referenceString);
+        if ($target)
+            {  NaturalDocs::Project->AddImageFileReference($target);  };
+        };
+
+    NaturalDocs::SourceDB->AddDefinition($extensionID, $referenceString, $file);
+    };
+
+
+#
+#   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 #(ImageReferenceString referenceString, FileName file, bool wasLastDefinition)
+    {
+    my ($self, $referenceString, $file, $wasLastDefinition) = @_;
+
+    if ($wasLastDefinition)
+        {
+        my $referenceObject = NaturalDocs::SourceDB->GetItem($extensionID, $referenceString);
+        my $target = $referenceObject->Target();
+
+        if ($target)
+            {  NaturalDocs::Project->DeleteImageFileReference($target);  };
+
+        NaturalDocs::SourceDB->DeleteItem($extensionID, $referenceString);
+        };
+    };
+
+
+#
+#   Function: GetReferenceTarget
+#
+#   Returns the image file the reference resolves to, or undef if none.
+#
+#   Parameters:
+#
+#       sourceFile - The source <FileName> the reference appears in.
+#       text - The reference text.
+#
+sub GetReferenceTarget #(FileName sourceFile, string text) => FileName
+    {
+    my ($self, $sourceFile, $text) = @_;
+
+    my $referenceString = NaturalDocs::ImageReferenceTable::String->Make($sourceFile, $text);
+    my $reference = NaturalDocs::SourceDB->GetItem($extensionID, $referenceString);
+
+    if (!defined $reference)
+        {  return undef;  }
+    else
+        {  return $reference->Target();  };
+    };
+
+
+#
+#   Function: SetReferenceTarget
+#
+#   Determines the best target for the passed <ImageReferenceString> and sets it on the
+#   <NaturalDocs::ImageReferenceTable::Reference> object.  Returns the new target <FileName>.  Does *not* add any source
+#   files to the bulid list.
+#
+sub SetReferenceTarget #(ImageReferenceString referenceString) => FileName
+    {
+    my ($self, $referenceString) = @_;
+
+    my $referenceObject = NaturalDocs::SourceDB->GetItem($extensionID, $referenceString);
+    my ($sourcePath, $text) = NaturalDocs::ImageReferenceTable::String->InformationOf($referenceString);
+
+
+    # Try the path relative to the source file first.
+
+    my $target;
+
+    my $imageFile = NaturalDocs::File->JoinPaths($sourcePath, $text);
+    my $exists = NaturalDocs::Project->ImageFileExists($imageFile);
+
+
+    # Then try relative image directories.
+
+    if (!$exists)
+        {
+        my $relativeImageDirectories = NaturalDocs::Settings->RelativeImageDirectories();
+
+        for (my $i = 0; $i < scalar @$relativeImageDirectories && !$exists; $i++)
+            {
+            $imageFile = NaturalDocs::File->JoinPaths($sourcePath, $relativeImageDirectories->[$i], 1);
+            $imageFile = NaturalDocs::File->JoinPaths($imageFile, $text);
+
+            $exists = NaturalDocs::Project->ImageFileExists($imageFile);
+            };
+        };
+
+
+    # Then try absolute image directories.
+
+    if (!$exists)
+        {
+        my $imageDirectories = NaturalDocs::Settings->ImageDirectories();
+
+        for (my $i = 0; $i < scalar @$imageDirectories && !$exists; $i++)
+            {
+            $imageFile = NaturalDocs::File->JoinPaths($imageDirectories->[$i], $text);
+            $exists = NaturalDocs::Project->ImageFileExists($imageFile);
+            };
+        };
+
+
+    if ($exists)
+        {  $target = NaturalDocs::Project->ImageFileCapitalization($imageFile);  };
+    #else leave it as undef.
+
+    $referenceObject->SetTarget($target);
+    return $target;
+    };
+
+
+1;

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

@@ -0,0 +1,44 @@
+###############################################################################
+#
+#   Package: NaturalDocs::ImageReferenceTable::Reference
+#
+###############################################################################
+#
+#   A class for references 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::ImageReferenceTable::Reference;
+
+use base 'NaturalDocs::SourceDB::Item';
+
+
+use NaturalDocs::DefineMembers 'TARGET', 'Target()', 'SetTarget()',
+                                                 'NEEDS_REBUILD', 'NeedsRebuild()', 'SetNeedsRebuild()';
+
+
+#
+#   Variables: Members
+#
+#   The following constants are indexes into the object array.
+#
+#   TARGET - The image <FileName> this reference resolves to, or undef if none.
+#
+
+
+#
+#   Functions: Member Functions
+#
+#   Target - Returns the image <FileName> this reference resolves to, or undef if none.
+#   SetTarget - Replaces the image <FileName> this reference resolves to, or undef if none.
+#
+
+
+1;

data/template/assets/naturaldocs/NaturalDocs/Modules/NaturalDocs/ImageReferenceTable/String.pm

@@ -0,0 +1,110 @@
+###############################################################################
+#
+#   Package: NaturalDocs::ImageReferenceTable::String
+#
+###############################################################################
+#
+#   A package for creating and managing <ImageReferenceStrings>.
+#
+###############################################################################
+
+# 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::ImageReferenceTable::String;
+
+
+#
+#   Type: ImageReferenceString
+#
+#   A string representing a unique image reference.  It's composed of the reference text and the directory of the source file.
+#   The source file name itself isn't included because two files in the same directory with the same reference text will always go
+#   to the same targets.
+#
+
+
+#
+#   Function: Make
+#
+#   Converts a source <FileName> and the reference text to an <ImageReferenceString>.
+#
+sub Make #(FileName sourceFile, string text) => ImageReferenceString
+    {
+    my ($self, $sourceFile, $text) = @_;
+
+    my $path = NaturalDocs::File->NoFileName($sourceFile);
+
+    # Condense whitespace and remove any separator characters.
+    $path =~ tr/ \t\r\n\x1C/ /s;
+    $text =~ tr/ \t\r\n\x1C/ /s;
+
+    return $path . "\x1C" . $text;
+    };
+
+
+#
+#   Function: InformationOf
+#
+#   Returns the information contained in the <ImageReferenceString> as the array ( path, text ).
+#
+sub InformationOf #(ImageReferenceString referenceString)
+    {
+    my ($self, $referenceString) = @_;
+    return split(/\x1C/, $referenceString);
+    };
+
+
+#
+#   Function: ToBinaryFile
+#
+#   Writes an <ImageReferenceString> to <NaturalDocs::BinaryFile>.  Can also encode an undef.
+#
+#   Format:
+#
+#       > [AString16: path] [AString16: reference text] ...
+#
+#       Undef is represented by the first AString16 being undef.
+#
+sub ToBinaryFile #(ImageReferenceString referenceString)
+    {
+    my ($self, $referenceString) = @_;
+
+    if (defined $referenceString)
+        {
+        my ($path, $text) = split(/\x1C/, $referenceString);
+
+        NaturalDocs::BinaryFile->WriteAString16($path);
+        NaturalDocs::BinaryFile->WriteAString16($text);
+        }
+    else
+        {
+        NaturalDocs::BinaryFile->WriteAString16(undef);
+        };
+    };
+
+
+#
+#   Function: FromBinaryFile
+#
+#   Loads an <ImageReferenceString> or undef from <NaturalDocs::BinaryFile> and returns it.
+#
+sub FromBinaryFile
+    {
+    my $self = shift;
+
+    my $path = NaturalDocs::BinaryFile->GetAString16();
+
+    if (!defined $path)
+        {  return undef;  };
+
+    my $text = NaturalDocs::BinaryFile->GetAString16();
+
+    return $path . "\x1C" . $text;
+    };
+
+
+1;