bixbite 0.1.0

data/template/assets/naturaldocs/NaturalDocs/Modules/NaturalDocs/Project/ImageFile.pm

@@ -0,0 +1,160 @@
+###############################################################################
+#
+#   Class: NaturalDocs::Project::ImageFile
+#
+###############################################################################
+#
+#   A simple information class about project image 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;
+
+package NaturalDocs::Project::ImageFile;
+
+
+
+###############################################################################
+# Group: Implementation
+
+#
+#   Constants: Members
+#
+#   The class is implemented as a blessed arrayref.  The following constants are used as indexes.
+#
+#       LAST_MODIFIED - The integer timestamp of when the file was last modified.
+#       STATUS - <FileStatus> since the last build.
+#       REFERENCE_COUNT - The number of references to the image from the source files.
+#       WAS_USED - Whether the image was used the last time Natural Docs was run.
+#       WIDTH - The image width.  Undef if can't be determined, -1 if haven't attempted to determine yet.
+#       HEIGHT - The image height.  Undef if can't be determined, -1 if haven't attempted to determine yet.
+#
+
+use NaturalDocs::DefineMembers 'LAST_MODIFIED', 'LastModified()', 'SetLastModified()',
+                                                 'STATUS', 'Status()', 'SetStatus()',
+                                                 'REFERENCE_COUNT', 'ReferenceCount()',
+                                                 'WAS_USED', 'WasUsed()', 'SetWasUsed()',
+                                                 'WIDTH', 'Width()',
+                                                 'HEIGHT', 'Height()';
+
+
+#
+#   Topic: WasUsed versus References
+#
+#   <WasUsed()> is a simple true/false that notes whether this image file was used the last time Natural Docs was run.
+#   <ReferenceCount()> is a counter for the number of times it's used *this* run.  As such, it starts at zero regardless of whether
+#   <WasUsed()> is set or not.
+#
+
+
+###############################################################################
+# Group: Functions
+
+#
+#   Function: New
+#
+#   Creates and returns a new file object.
+#
+#   Parameters:
+#
+#       lastModified - The image file's last modification timestamp
+#       status - The <FileStatus>.
+#       wasUsed - Whether this image file was used the *last* time Natural Docs was run.
+#
+sub New #(timestamp lastModified, FileStatus status, bool wasUsed)
+    {
+    my ($package, $lastModified, $status, $width, $height, $wasUsed) = @_;
+
+    my $object = [ ];
+    $object->[LAST_MODIFIED] = $lastModified;
+    $object->[STATUS] = $status;
+    $object->[REFERENCE_COUNT] = 0;
+    $object->[WAS_USED] = $wasUsed;
+    $object->[WIDTH] = -1;
+    $object->[HEIGHT] = -1;
+
+    bless $object, $package;
+
+    return $object;
+    };
+
+
+#
+#   Functions: Member Functions
+#
+#   LastModified - Returns the integer timestamp of when the file was last modified.
+#   SetLastModified - Sets the file's last modification timestamp.
+#   Status - Returns the <FileStatus> since the last build.
+#   SetStatus - Sets the <FileStatus> since the last build.
+#
+
+#
+#   Function: ReferenceCount
+#   Returns the current number of references to this image file during *this* Natural Docs execution.
+#
+
+#
+#   Function: AddReference
+#   Increases the number of references to this image file by one.  Returns the new reference count.
+#
+sub AddReference
+    {
+    my $self = shift;
+
+    $self->[REFERENCE_COUNT]++;
+    return $self->[REFERENCE_COUNT];
+    };
+
+#
+#   Function: DeleteReference
+#   Decreases the number of references to this image file by one.  Returns the new reference count.
+#
+sub DeleteReference
+    {
+    my $self = shift;
+    $self->[REFERENCE_COUNT]--;
+
+    if ($self->[REFERENCE_COUNT] < 0)
+        {  die "Deleted more references to an image file than existed.";  };
+
+    return $self->[REFERENCE_COUNT];
+    };
+
+
+#
+#   Functions: Member Functions
+#
+#   WasUsed - Returns whether this image file was used during the *last* Natural Docs execution.
+#   SetWasUsed - Sets whether this image file was used during the *last* Natural Docs execution.
+#   Width - Returns the width in pixels, undef if it can't be determined, and -1 if determination hasn't been attempted yet.
+#   Height - Returns the width in pixels, undef if it can't be determined, and -1 if determination hasn't been attempted yet.
+#
+
+
+#
+#   Function: SetDimensions
+#   Sets the width and height of the image.  Set to undef if they can't be determined.
+#
+sub SetDimensions #(int width, int height)
+    {
+    my ($self, $width, $height) = @_;
+
+    # If either are undef, both should be undef.  This will also convert zeroes to undef.
+    if (!$width || !$height)
+        {
+        $self->[WIDTH] = undef;
+        $self->[HEIGHT] = undef;
+        }
+    else
+        {
+        $self->[WIDTH] = $width;
+        $self->[HEIGHT] = $height;
+        };
+    };
+
+
+1;

data/template/assets/naturaldocs/NaturalDocs/Modules/NaturalDocs/Project/SourceFile.pm

@@ -0,0 +1,113 @@
+###############################################################################
+#
+#   Class: NaturalDocs::Project::SourceFile
+#
+###############################################################################
+#
+#   A simple information class about project 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;
+
+package NaturalDocs::Project::SourceFile;
+
+
+
+###############################################################################
+# Group: Implementation
+
+#
+#   Constants: Members
+#
+#   The class is implemented as a blessed arrayref.  The following constants are used as indexes.
+#
+#       HAS_CONTENT             - Whether the file contains Natural Docs content or not.
+#       LAST_MODIFIED           - The integer timestamp of when the file was last modified.
+#       STATUS                       - <FileStatus> since the last build.
+#       DEFAULT_MENU_TITLE  - The file's default title in the menu.
+#
+
+# DEPENDENCY: New() depends on its parameter list being in the same order as these constants.  If the order changes, New()
+# needs to be changed.
+use NaturalDocs::DefineMembers 'HAS_CONTENT', 'LAST_MODIFIED', 'STATUS', 'DEFAULT_MENU_TITLE';
+
+
+###############################################################################
+# Group: Functions
+
+#
+#   Function: New
+#
+#   Creates and returns a new file object.
+#
+#   Parameters:
+#
+#       hasContent         - Whether the file contains Natural Docs content or not.
+#       lastModified         - The integer timestamp of when the file was last modified.
+#       status                 - The <FileStatus> since the last build.
+#       defaultMenuTitle  - The file's title in the menu.
+#
+#   Returns:
+#
+#       A reference to the new object.
+#
+sub New #(hasContent, lastModified, status, defaultMenuTitle)
+    {
+    # DEPENDENCY: This function depends on its parameter list being in the same order as the member constants.  If either order
+    # changes, this function needs to be changed.
+
+    my $package = shift;
+
+    my $object = [ @_ ];
+    bless $object, $package;
+
+    return $object;
+    };
+
+# Function: HasContent
+# Returns whether the file contains Natural Docs content or not.
+sub HasContent
+    {  return $_[0]->[HAS_CONTENT];  };
+
+# Function: SetHasContent
+# Sets whether the file contains Natural Docs content or not.
+sub SetHasContent #(hasContent)
+    {  $_[0]->[HAS_CONTENT] = $_[1];  };
+
+# Function: LastModified
+# Returns the integer timestamp of when the file was last modified.
+sub LastModified
+    {  return $_[0]->[LAST_MODIFIED];  };
+
+# Function: SetLastModified
+# Sets the file's last modification timestamp.
+sub SetLastModified #(lastModified)
+    {  $_[0]->[LAST_MODIFIED] = $_[1];  };
+
+# Function: Status
+# Returns the <FileStatus> since the last build.
+sub Status
+    {  return $_[0]->[STATUS];  };
+
+# Function: SetStatus
+# Sets the <FileStatus> since the last build.
+sub SetStatus #(status)
+    {  $_[0]->[STATUS] = $_[1];  };
+
+# Function: DefaultMenuTitle
+# Returns the file's default title on the menu.
+sub DefaultMenuTitle
+    {  return $_[0]->[DEFAULT_MENU_TITLE];  };
+
+# Function: SetDefaultMenuTitle
+# Sets the file's default title on the menu.
+sub SetDefaultMenuTitle #(menuTitle)
+    {  $_[0]->[DEFAULT_MENU_TITLE] = $_[1];  };
+
+
+1;

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

@@ -0,0 +1,334 @@
+###############################################################################
+#
+#   Package: NaturalDocs::ReferenceString
+#
+###############################################################################
+#
+#   A package to manage <ReferenceString> handling throughout the program.
+#
+###############################################################################
+
+# 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::ReferenceString;
+
+use vars '@ISA', '@EXPORT';
+@ISA = 'Exporter';
+@EXPORT = ( 'BINARYREF_NOTYPE', 'BINARYREF_NORESOLVINGFLAGS',
+
+                     'REFERENCE_TEXT', 'REFERENCE_CH_CLASS', 'REFERENCE_CH_PARENT',
+
+                     'RESOLVE_RELATIVE', 'RESOLVE_ABSOLUTE', 'RESOLVE_NOPLURAL', 'RESOLVE_NOUSING' );
+
+
+#
+#   Constants: Binary Format Flags
+#
+#   These flags can be combined to specify the format when using <ToBinaryFile()> and <FromBinaryFile()>.  All are exported
+#   by default.
+#
+#   BINARYREF_NOTYPE - Do not include the <ReferenceType>.
+#   BINARYREF_NORESOLVEFLAGS - Do not include the <Resolving Flags>.
+#
+use constant BINARYREF_NOTYPE => 0x01;
+use constant BINARYREF_NORESOLVINGFLAGS => 0x02;
+
+
+#
+#   Constants: ReferenceType
+#
+#   The type of a reference.
+#
+#       REFERENCE_TEXT - The reference appears in the text of the documentation.
+#       REFERENCE_CH_CLASS - A class reference handled by <NaturalDocs::ClassHierarchy>.
+#       REFERENCE_CH_PARENT - A parent class reference handled by <NaturalDocs::ClassHierarchy>.
+#
+#   Dependencies:
+#
+#       - <ToBinaryFile()> and <FromBinaryFile()> require that these values fit into a UInt8, i.e. are <= 255.
+#
+use constant REFERENCE_TEXT => 1;
+use constant REFERENCE_CH_CLASS => 2;
+use constant REFERENCE_CH_PARENT => 3;
+
+
+#
+#   Constants: Resolving Flags
+#
+#   Used to influence the method of resolving references in <NaturalDocs::SymbolTable>.
+#
+#       RESOLVE_RELATIVE - The reference text is truly relative, rather than Natural Docs' semi-relative.
+#       RESOLVE_ABSOLUTE - The reference text is always absolute.  No local or relative references.
+#       RESOLVE_NOPLURAL - The reference text may not be interpreted as a plural, and thus match singular forms as well.
+#       RESOLVE_NOUSING - The reference text may not include "using" statements when being resolved.
+#
+#       If neither <RESOLVE_RELATIVE> or <RESOLVE_ABSOLUTE> is specified, Natural Docs' semi-relative kicks in instead,
+#       which is where links are interpreted as local, then global, then relative.  <RESOLVE_RELATIVE> states that links are
+#       local, then relative, then global.
+#
+#   Dependencies:
+#
+#       - <ToBinaryFile()> and <FromBinaryFile()> require that these values fit into a UInt8, i.e. are <= 255.
+#
+use constant RESOLVE_RELATIVE => 0x01;
+use constant RESOLVE_ABSOLUTE => 0x02;
+use constant RESOLVE_NOPLURAL => 0x04;
+use constant RESOLVE_NOUSING => 0x08;
+
+
+#
+#
+#   Function: MakeFrom
+#
+#   Encodes the passed information as a <ReferenceString>.  The format of the string should be treated as opaque.  However, the
+#   characteristic you can rely on is that the same string will always be made from the same parameters, and thus it's suitable
+#   for comparison and use as hash keys.
+#
+#   Parameters:
+#
+#       type - The <ReferenceType>.
+#       symbol - The <SymbolString> of the reference.
+#       language - The name of the language that defines the file this reference appears in.
+#       scope - The scope <SymbolString> the reference appears in, or undef if none.
+#       using - An arrayref of scope <SymbolStrings> that are also available for checking due to the equivalent a "using" statement,
+#                  or undef if none.
+#       resolvingFlags - The <Resolving Flags> to use with this reference.  They are ignored if the type is <REFERENCE_TEXT>.
+#
+#   Returns:
+#
+#       The encoded <ReferenceString>.
+#
+sub MakeFrom #(ReferenceType type, SymbolString symbol, string language, SymbolString scope, SymbolString[]* using, flags resolvingFlags)
+    {
+    my ($self, $type, $symbol, $language, $scope, $using, $resolvingFlags) = @_;
+
+    if ($type == ::REFERENCE_TEXT() || $resolvingFlags == 0)
+       {  $resolvingFlags = undef;  };
+
+    # The format is [type] 0x1E [resolving flags] 0x1E [symbol] 0x1E [scope] ( 0x1E [using] )*
+    # If there is no scope and/or using, the separator characters still remain.
+
+    # DEPENDENCY: SymbolString->FromText() removed all 0x1E characters.
+    # DEPENDENCY: SymbolString->FromText() doesn't use 0x1E characters in its encoding.
+
+    my $string = $type . "\x1E" . $symbol . "\x1E" . $language . "\x1E" . $resolvingFlags . "\x1E";
+
+    if (defined $scope)
+        {
+        $string .= $scope;
+        };
+
+    $string .= "\x1E";
+
+    if (defined $using)
+        {
+        $string .= join("\x1E", @$using);
+        };
+
+    return $string;
+    };
+
+
+#
+#   Function: ToBinaryFile
+#
+#   Writes a <ReferenceString> to the passed filehandle.  Can also encode an undef.
+#
+#   Parameters:
+#
+#       fileHandle - The filehandle to write to.
+#       referenceString - The <ReferenceString> to write, or undef.
+#       binaryFormatFlags - Any <Binary Format Flags> you want to use to influence encoding.
+#
+#   Format:
+#
+#       > [SymbolString: Symbol or undef for an undef reference]
+#       > [AString16: language]
+#       > [SymbolString: Scope or undef for none]
+#       >
+#       > [SymbolString: Using or undef for none]
+#       > [SymbolString: Using or undef for no more]
+#       > ...
+#       >
+#       > [UInt8: Type unless BINARYREF_NOTYPE is set]
+#       > [UInt8: Resolving Flags unless BINARYREF_NORESOLVINGFLAGS is set]
+#
+#   Dependencies:
+#
+#       - <ReferenceTypes> must fit into a UInt8.  All values must be <= 255.
+#       - All <Resolving Flags> must fit into a UInt8.  All values must be <= 255.
+#
+sub ToBinaryFile #(FileHandle fileHandle, ReferenceString referenceString, flags binaryFormatFlags)
+    {
+    my ($self, $fileHandle, $referenceString, $binaryFormatFlags) = @_;
+
+    my ($type, $symbol, $language, $scope, $using, $resolvingFlags) = $self->InformationOf($referenceString);
+
+    # [SymbolString: Symbol or undef for an undef reference]
+
+    NaturalDocs::SymbolString->ToBinaryFile($fileHandle, $symbol);
+
+    # [AString16: language]
+
+    print $fileHandle pack('nA*', length $language, $language);
+
+    # [SymbolString: scope or undef if none]
+
+    NaturalDocs::SymbolString->ToBinaryFile($fileHandle, $scope);
+
+    # [SymbolString: using or undef if none/no more] ...
+
+    if (defined $using)
+        {
+        foreach my $usingScope (@$using)
+            {  NaturalDocs::SymbolString->ToBinaryFile($fileHandle, $usingScope);  };
+        };
+
+    NaturalDocs::SymbolString->ToBinaryFile($fileHandle, undef);
+
+    # [UInt8: Type unless BINARYREF_NOTYPE is set]
+
+    if (!($binaryFormatFlags & BINARYREF_NOTYPE))
+        {  print $fileHandle pack('C', $type);  };
+
+    # [UInt8: Resolving Flags unless BINARYREF_NORESOLVINGFLAGS is set]
+
+    if (!($binaryFormatFlags & BINARYREF_NORESOLVINGFLAGS))
+        {  print $fileHandle pack('C', $type);  };
+    };
+
+
+#
+#   Function: FromBinaryFile
+#
+#   Reads a <ReferenceString> or undef from the passed filehandle.
+#
+#   Parameters:
+#
+#       fileHandle - The filehandle to read from.
+#       binaryFormatFlags - Any <Binary Format Flags> you want to use to influence decoding.
+#       type - The <ReferenceType> to use if <BINARYREF_NOTYPE> is set.
+#       resolvingFlags - The <Resolving Flags> to use if <BINARYREF_NORESOLVINGFLAGS> is set.
+#
+#   Returns:
+#
+#       The <ReferenceString> or undef.
+#
+#   See Also:
+#
+#       See <ToBinaryFile()> for format and dependencies.
+#
+sub FromBinaryFile #(FileHandle fileHandle, flags binaryFormatFlags, ReferenceType type, flags resolvingFlags)
+    {
+    my ($self, $fileHandle, $binaryFormatFlags, $type, $resolvingFlags) = @_;
+    my $raw;
+
+    # [SymbolString: Symbol or undef for an undef reference]
+
+    my $symbol = NaturalDocs::SymbolString->FromBinaryFile($fileHandle);
+
+    if (!defined $symbol)
+        {  return undef;  };
+
+
+    # [AString16: language]
+
+    read($fileHandle, $raw, 2);
+    my $languageLength = unpack('n', $raw);
+
+    my $language;
+    read($fileHandle, $language, $languageLength);
+
+
+    # [SymbolString: scope or undef if none]
+
+    my $scope = NaturalDocs::SymbolString->FromBinaryFile($fileHandle);
+
+    # [SymbolString: using or undef if none/no more] ...
+
+    my $usingSymbol;
+    my @using;
+
+    while ($usingSymbol = NaturalDocs::SymbolString->FromBinaryFile($fileHandle))
+        {  push @using, $usingSymbol;  };
+
+    if (scalar @using)
+        {  $usingSymbol = \@using;  }
+    else
+        {  $usingSymbol = undef;  };
+
+    # [UInt8: Type unless BINARYREF_NOTYPE is set]
+
+    if (!($binaryFormatFlags & BINARYREF_NOTYPE))
+        {
+        my $raw;
+        read($fileHandle, $raw, 1);
+        $type = unpack('C', $raw);
+        };
+
+    # [UInt8: Resolving Flags unless BINARYREF_NORESOLVINGFLAGS is set]
+
+    if (!($binaryFormatFlags & BINARYREF_NORESOLVINGFLAGS))
+        {
+        my $raw;
+        read($fileHandle, $raw, 1);
+        $resolvingFlags = unpack('C', $raw);
+        };
+
+    return $self->MakeFrom($type, $symbol, $language, $scope, $usingSymbol, $resolvingFlags);
+    };
+
+
+#
+#   Function: InformationOf
+#
+#   Returns the information encoded in a <ReferenceString>.
+#
+#   Parameters:
+#
+#       referenceString - The <ReferenceString> to decode.
+#
+#   Returns:
+#
+#       The array ( type, symbol, language, scope, using, resolvingFlags ).
+#
+#       type - The <ReferenceType>.
+#       symbol - The <SymbolString>.
+#       language - The name of the language that defined the file the reference was defined in.
+#       scope - The scope <SymbolString>, or undef if none.
+#       using - An arrayref of scope <SymbolStrings> that the reference also has access to via "using" statements, or undef if none.
+#       resolvingFlags - The <Resolving Flags> of the reference.
+#
+sub InformationOf #(ReferenceString referenceString)
+    {
+    my ($self, $referenceString) = @_;
+
+    my ($type, $symbolString, $language, $resolvingFlags, $scopeString, @usingStrings) = split(/\x1E/, $referenceString);
+
+    if (!length $resolvingFlags)
+        {  $resolvingFlags = undef;  };
+
+    return ( $type, $symbolString, $language, $scopeString, [ @usingStrings ], $resolvingFlags );
+    };
+
+
+#
+#   Function: TypeOf
+#
+#   Returns the <ReferenceType> encoded in the reference string.  This is faster than <InformationOf()> if this is
+#   the only information you need.
+#
+sub TypeOf #(ReferenceString referenceString)
+    {
+    my ($self, $referenceString) = @_;
+
+    $referenceString =~ /^([^\x1E]+)/;
+    return $1;
+    };
+
+
+1;