bixbite 0.1.0

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

@@ -0,0 +1,165 @@
+###############################################################################
+#
+#   Package: NaturalDocs::Constants
+#
+###############################################################################
+#
+#   Constants that are used throughout the script.  All are exported by default.
+#
+###############################################################################
+
+# 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::Constants;
+
+use vars qw(@EXPORT @ISA);
+require Exporter;
+@ISA = qw(Exporter);
+
+@EXPORT = ('MENU_TITLE', 'MENU_SUBTITLE', 'MENU_FILE', 'MENU_GROUP', 'MENU_TEXT', 'MENU_LINK', 'MENU_FOOTER',
+                   'MENU_INDEX', 'MENU_FORMAT', 'MENU_ENDOFORIGINAL', 'MENU_DATA',
+
+                   'MENU_FILE_NOAUTOTITLE', 'MENU_GROUP_UPDATETITLES', 'MENU_GROUP_UPDATESTRUCTURE',
+                   'MENU_GROUP_UPDATEORDER', 'MENU_GROUP_HASENDOFORIGINAL',
+                   'MENU_GROUP_UNSORTED', 'MENU_GROUP_FILESSORTED',
+                   'MENU_GROUP_FILESANDGROUPSSORTED', 'MENU_GROUP_EVERYTHINGSORTED',
+                   'MENU_GROUP_ISINDEXGROUP',
+
+                   'FILE_NEW', 'FILE_CHANGED', 'FILE_SAME', 'FILE_DOESNTEXIST');
+
+#
+#   Topic: Assumptions
+#
+#   - No constant here will ever be zero.
+#   - All constants are exported by default.
+#
+
+
+###############################################################################
+# Group: Virtual Types
+# These are only groups of constants, but should be treated like typedefs or enums.  Each one represents a distinct type and
+# their values should only be one of their constants or undef.
+
+
+#
+#   Constants: MenuEntryType
+#
+#   The types of entries that can appear in the menu.
+#
+#       MENU_TITLE         - The title of the menu.
+#       MENU_SUBTITLE   - The sub-title of the menu.
+#       MENU_FILE           - A source file, relative to the source directory.
+#       MENU_GROUP       - A group.
+#       MENU_TEXT          - Arbitrary text.
+#       MENU_LINK           - A web link.
+#       MENU_FOOTER      - Footer text.
+#       MENU_INDEX        - An index.
+#       MENU_FORMAT     - The version of Natural Docs the menu file was generated with.
+#       MENU_ENDOFORIGINAL - A dummy entry that marks where the original group content ends.  This is used when automatically
+#                                           changing the groups so that the alphabetization or lack thereof can be detected without being
+#                                           affected by new entries tacked on to the end.
+#       MENU_DATA - Data not meant for user editing.
+#
+#   Dependency:
+#
+#       <PreviousMenuState.nd> depends on these values all being able to fit into a UInt8, i.e. <= 255.
+#
+use constant MENU_TITLE => 1;
+use constant MENU_SUBTITLE => 2;
+use constant MENU_FILE => 3;
+use constant MENU_GROUP => 4;
+use constant MENU_TEXT => 5;
+use constant MENU_LINK => 6;
+use constant MENU_FOOTER => 7;
+use constant MENU_INDEX => 8;
+use constant MENU_FORMAT => 9;
+use constant MENU_ENDOFORIGINAL => 10;
+use constant MENU_DATA => 11;
+
+
+#
+#   Constants: FileStatus
+#
+#   What happened to a file since Natural Docs' last execution.
+#
+#       FILE_NEW                - The file has been added since the last run.
+#       FILE_CHANGED        - The file has been modified since the last run.
+#       FILE_SAME               - The file hasn't been modified since the last run.
+#       FILE_DOESNTEXIST  - The file doesn't exist, or was deleted.
+#
+use constant FILE_NEW => 1;
+use constant FILE_CHANGED => 2;
+use constant FILE_SAME => 3;
+use constant FILE_DOESNTEXIST => 4;
+
+
+
+###############################################################################
+# Group: Flags
+# These constants can be combined with each other.
+
+
+#
+#   Constants: Menu Entry Flags
+#
+#   The various flags that can apply to a menu entry.  You cannot mix flags of different types, since they may overlap.
+#
+#   File Flags:
+#
+#       MENU_FILE_NOAUTOTITLE - Whether the file is auto-titled or not.
+#
+#   Group Flags:
+#
+#       MENU_GROUP_UPDATETITLES - The group should have its auto-titles regenerated.
+#       MENU_GROUP_UPDATESTRUCTURE - The group should be checked for structural changes, such as being removed or being
+#                                                             split into subgroups.
+#       MENU_GROUP_UPDATEORDER - The group should be resorted.
+#
+#       MENU_GROUP_HASENDOFORIGINAL - Whether the group contains a dummy <MENU_ENDOFORIGINAL> entry.
+#       MENU_GROUP_ISINDEXGROUP - Whether the group is used primarily for <MENU_INDEX> entries.  <MENU_TEXT> entries
+#                                                       are tolerated.
+#
+#       MENU_GROUP_UNSORTED - The group's contents are not sorted.
+#       MENU_GROUP_FILESSORTED - The group's files are sorted alphabetically.
+#       MENU_GROUP_FILESANDGROUPSSORTED - The group's files and sub-groups are sorted alphabetically.
+#       MENU_GROUP_EVERYTHINGSORTED - All entries in the group are sorted alphabetically.
+#
+use constant MENU_FILE_NOAUTOTITLE => 0x0001;
+
+use constant MENU_GROUP_UPDATETITLES => 0x0001;
+use constant MENU_GROUP_UPDATESTRUCTURE => 0x0002;
+use constant MENU_GROUP_UPDATEORDER => 0x0004;
+use constant MENU_GROUP_HASENDOFORIGINAL => 0x0008;
+
+# This could really be a two-bit field instead of four flags, but it's not worth the effort since it's only used internally.
+use constant MENU_GROUP_UNSORTED => 0x0010;
+use constant MENU_GROUP_FILESSORTED => 0x0020;
+use constant MENU_GROUP_FILESANDGROUPSSORTED => 0x0040;
+use constant MENU_GROUP_EVERYTHINGSORTED => 0x0080;
+
+use constant MENU_GROUP_ISINDEXGROUP => 0x0100;
+
+
+
+
+###############################################################################
+# Group: Support Functions
+
+
+#
+#   Function: IsClassHierarchyReference
+#   Returns whether the passed <ReferenceType> belongs to <NaturalDocs::ClassHierarchy>.
+#
+sub IsClassHierarchyReference #(reference)
+    {
+    my ($self, $reference) = @_;
+    return ($reference == ::REFERENCE_CH_CLASS() || $reference == ::REFERENCE_CH_PARENT());
+    };
+
+
+
+1;

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

@@ -0,0 +1,100 @@
+###############################################################################
+#
+#   Package: NaturalDocs::DefineMembers
+#
+###############################################################################
+#
+#   A custom Perl pragma to define member constants and accessors for use in Natural Docs objects while supporting inheritance.
+#
+#   Each member will be defined as a numeric constant which should be used as that variable's index into the object arrayref.
+#   They will be assigned sequentially from zero, and take into account any members defined this way in parent classes.  Note
+#   that you can *not* use multiple inheritance with this method.
+#
+#   If a parameter ends in parenthesis, it will be generated as an accessor for the previous member.  If it also starts with "Set",
+#   the accessor will accept a single parameter to replace the value with.  If it's followed with "duparrayref", it will assume the
+#   parameter is either an arrayref or undef, and if the former, will duplicate it to set the value.
+#
+#   Example:
+#
+#   > package MyPackage;
+#   >
+#   > use NaturalDocs::DefineMembers 'VAR_A', 'VarA()', 'SetVarA()',
+#   >                                'VAR_B', 'VarB()',
+#   >                                'VAR_C',
+#   >                                'VAR_D', 'VarD()', 'SetVarD() duparrayref';
+#   >
+#   > sub SetC #(C)
+#   >    {
+#   >    my ($self, $c) = @_;
+#   >    $self->[VAR_C] = $c;
+#   >    };
+#
+###############################################################################
+
+# This file is part of Natural Docs, which is Copyright (C) 2003-2008 Greg Valure
+# Natural Docs is licensed under the GPL
+
+
+package NaturalDocs::DefineMembers;
+
+sub import #(member, member, ...)
+    {
+    my ($self, @parameters) = @_;
+    my $package = caller();
+
+    no strict 'refs';
+    my $parent = ${$package . '::ISA'}[0];
+    use strict 'refs';
+
+    my $memberConstant = 0;
+    my $lastMemberName;
+
+    if (defined $parent && $parent->can('END_OF_MEMBERS'))
+        {  $memberConstant = $parent->END_OF_MEMBERS();  };
+
+    my $code = '{ package ' . $package . ";\n";
+
+    foreach my $parameter (@parameters)
+        {
+        if ($parameter =~ /^(.+)\(\) *(duparrayref)?$/i)
+            {
+            my ($functionName, $pragma) = ($1, lc($2));
+
+            if ($functionName =~ /^Set/)
+                {
+                if ($pragma eq 'duparrayref')
+                    {
+                    $code .=
+                    'sub ' . $functionName . '
+                        {
+                        if (defined $_[1])
+                            {  $_[0]->[' . $lastMemberName . '] = [ @{$_[1]} ];  }
+                        else
+                            {  $_[0]->[' . $lastMemberName . '] = undef;  };
+                        };' . "\n";
+                    }
+                else
+                    {
+                    $code .= 'sub ' . $functionName . ' { $_[0]->[' . $lastMemberName . '] = $_[1];  };' . "\n";
+                    };
+                }
+            else
+                {
+                $code .= 'sub ' . $functionName . ' { return $_[0]->[' . $lastMemberName . '];  };' . "\n";
+                };
+            }
+        else
+            {
+            $code .= 'use constant ' . $parameter . ' => ' . $memberConstant . ";\n";
+            $memberConstant++;
+            $lastMemberName = $parameter;
+            };
+        };
+
+    $code .= 'use constant END_OF_MEMBERS => ' . $memberConstant . ";\n";
+    $code .= '};';
+
+    eval $code;
+    };
+
+1;

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

@@ -0,0 +1,305 @@
+###############################################################################
+#
+#   Package: NaturalDocs::Error
+#
+###############################################################################
+#
+#   Manages all aspects of error handling in Natural Docs.
+#
+###############################################################################
+
+# 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;
+
+$SIG{'__DIE__'} = \&NaturalDocs::Error::CatchDeath;
+
+
+package NaturalDocs::Error;
+
+
+###############################################################################
+# Group: Variables
+
+
+#
+#   handle: FH_CRASHREPORT
+#   The filehandle used for generating crash reports.
+#
+
+
+#
+#   var: stackTrace
+#   The stack trace generated by <CatchDeath()>.
+#
+my $stackTrace;
+
+
+#
+#   var: softDeath
+#   Whether the program exited using <SoftDeath()>.
+#
+my $softDeath;
+
+
+#
+#   var: currentAction
+#   What Natural Docs was doing when it crashed.  This stores strings generated by functions like <OnStartParsing()>.
+#
+my $currentAction;
+
+
+###############################################################################
+# Group: Functions
+
+
+#
+#   Function: SoftDeath
+#
+#   Generates a "soft" death, which means the program exits like with Perl's die(), but no crash report will be generated.
+#
+#   Parameter:
+#
+#       message - The error message to die with.
+#
+sub SoftDeath #(message)
+    {
+    my ($self, $message) = @_;
+
+    $softDeath = 1;
+    if ($message !~ /\n$/)
+        {  $message .= "\n";  };
+
+    die $message;
+    };
+
+
+#
+#   Function: OnStartParsing
+#
+#   Called whenever <NaturalDocs::Parser> starts parsing a source file.
+#
+sub OnStartParsing #(FileName file)
+    {
+    my ($self, $file) = @_;
+    $currentAction = 'Parsing ' . $file;
+    };
+
+
+#
+#   Function: OnEndParsing
+#
+#   Called whenever <NaturalDocs::Parser> is done parsing a source file.
+#
+sub OnEndParsing #(FileName file)
+    {
+    my ($self, $file) = @_;
+    $currentAction = undef;
+    };
+
+
+#
+#   Function: OnStartBuilding
+#
+#   Called whenever <NaturalDocs::Builder> starts building a source file.
+#
+sub OnStartBuilding #(FileName file)
+    {
+    my ($self, $file) = @_;
+    $currentAction = 'Building ' . $file;
+    };
+
+
+#
+#   Function: OnEndBuilding
+#
+#   Called whenever <NaturalDocs::Builder> is done building a source file.
+#
+sub OnEndBuilding #(FileName file)
+    {
+    my ($self, $file) = @_;
+    $currentAction = undef;
+    };
+
+
+#
+#   Function: HandleDeath
+#
+#   Should be called whenever Natural Docs dies out of execution.
+#
+sub HandleDeath
+    {
+    my $self = shift;
+
+    my $reason = $::EVAL_ERROR;
+    $reason =~ s/[\n\r]+$//;
+
+    my $errorMessage =
+         "\n"
+         . "Natural Docs encountered the following error and was stopped:\n"
+         . "\n"
+         . "   " . $reason . "\n"
+         . "\n"
+
+         . "You can get help at the following web site:\n"
+         . "\n"
+         . "   " . NaturalDocs::Settings->AppURL() . "\n"
+         . "\n";
+
+    if (!$softDeath)
+        {
+        my $crashReport = $self->GenerateCrashReport();
+
+        if ($crashReport)
+            {
+            $errorMessage .=
+             "If sending an error report, please include the information found in the\n"
+             . "following file:\n"
+             . "\n"
+             . "   " . $crashReport . "\n"
+             . "\n";
+            }
+        else
+            {
+            $errorMessage .=
+             "If sending an error report, please include the following information:\n"
+             . "\n"
+             . "   Natural Docs version: " . NaturalDocs::Settings->TextAppVersion() . "\n"
+             . "   Perl version: " . $self->PerlVersion() . " on " . $::OSNAME . "\n"
+             . "\n";
+             };
+        };
+
+    die $errorMessage;
+    };
+
+
+###############################################################################
+# Group: Support Functions
+
+
+#
+#   Function: PerlVersion
+#   Returns the current Perl version as a string.
+#
+sub PerlVersion
+    {
+    my $self = shift;
+
+    my $perlVersion;
+
+    if ($^V)
+        {  $perlVersion = sprintf('%vd', $^V);  }
+    if (!$perlVersion || substr($perlVersion, 0, 1) eq '%')
+        {  $perlVersion = $];  };
+
+    return $perlVersion;
+    };
+
+
+#
+#   Function: GenerateCrashReport
+#
+#   Generates a report and returns the <FileName> it's located at.  Returns undef if it could not generate one.
+#
+sub GenerateCrashReport
+    {
+    my $self = shift;
+
+    my $errorMessage = $::EVAL_ERROR;
+    $errorMessage =~ s/[\r\n]+$//;
+
+    my $reportDirectory = NaturalDocs::Settings->ProjectDirectory();
+
+    if (!$reportDirectory || !-d $reportDirectory)
+        {  return undef;  };
+
+    my $file = NaturalDocs::File->JoinPaths($reportDirectory, 'LastCrash.txt');
+
+    open(FH_CRASHREPORT, '>' . $file) or return undef;
+
+    print FH_CRASHREPORT
+    'Crash Message:' . "\n\n"
+    . '   ' . $errorMessage . "\n\n";
+
+    if ($currentAction)
+        {
+        print FH_CRASHREPORT
+        'Current Action:' . "\n\n"
+        . '   ' . $currentAction . "\n\n";
+        };
+
+    print FH_CRASHREPORT
+    'Natural Docs version ' . NaturalDocs::Settings->TextAppVersion() . "\n"
+    . 'Perl version ' . $self->PerlVersion . ' on ' . $::OSNAME . "\n\n"
+    . 'Command Line:' . "\n\n"
+    . '   ' . join(' ', @ARGV) . "\n\n";
+
+    if ($stackTrace)
+        {
+        print FH_CRASHREPORT
+        'Stack Trace:' . "\n\n"
+        . $stackTrace;
+        }
+    else
+        {
+        print FH_CRASHREPORT
+        'Stack Trace not available.' . "\n\n";
+        };
+
+    close(FH_CRASHREPORT);
+    return $file;
+    };
+
+
+###############################################################################
+# Group: Signal Handlers
+
+
+#
+#   Function: CatchDeath
+#
+#   Catches Perl die calls.
+#
+#   *IMPORTANT:* This function is a signal handler and should not be called manually.  Also, because of this, it does not have
+#   a $self parameter.
+#
+#   Parameters:
+#
+#       message - The error message to die with.
+#
+sub CatchDeath #(message)
+    {
+    # No $self because it's a signal handler.
+    my $message = shift;
+
+    if (!$NaturalDocs::Error::softDeath)
+        {
+        my $i = 0;
+        my ($lastPackage, $lastFile, $lastLine, $lastFunction);
+
+        while (my ($package, $file, $line, $function) = caller($i))
+            {
+            if ($i != 0)
+                {  $stackTrace .= ', called from' . "\n";  };
+
+            $stackTrace .= '   ' . $function;
+
+            if (defined $lastLine)
+                {
+                $stackTrace .= ', line ' . $lastLine;
+
+                if ($function !~ /^NaturalDocs::/)
+                    {  $stackTrace .= ' of ' . $lastFile;  };
+                };
+
+            ($lastPackage, $lastFile, $lastLine, $lastFunction) = ($package, $file, $line, $function);
+            $i++;
+            };
+        };
+    };
+
+
+1;