mirror of
https://github.com/lxsang/antd-lua-plugin
synced 2025-07-13 05:34:25 +02:00
mimgrating from another repo
This commit is contained in:
Xuan Sang LE
487
lib/ann/fann/docs/NaturalDocs-1.52/Modules/NaturalDocs/Languages/Simple.pm
Executable file
487
lib/ann/fann/docs/NaturalDocs-1.52/Modules/NaturalDocs/Languages/Simple.pm
Executable file
@ -0,0 +1,487 @@
|
||||
###############################################################################
|
||||
#
|
||||
# Class: NaturalDocs::Languages::Simple
|
||||
#
|
||||
###############################################################################
|
||||
#
|
||||
# A class containing the characteristics of a particular programming language for basic support within Natural Docs.
|
||||
# Also serves as a base class for languages that break from general conventions, such as not having parameter lists use
|
||||
# parenthesis and commas.
|
||||
#
|
||||
###############################################################################
|
||||
|
||||
# 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::Languages::Simple;
|
||||
|
||||
use base 'NaturalDocs::Languages::Base';
|
||||
use base 'Exporter';
|
||||
|
||||
our @EXPORT = ( 'ENDER_ACCEPT', 'ENDER_IGNORE', 'ENDER_ACCEPT_AND_CONTINUE', 'ENDER_REVERT_TO_ACCEPTED' );
|
||||
|
||||
|
||||
use NaturalDocs::DefineMembers 'LINE_COMMENT_SYMBOLS', 'LineCommentSymbols()', 'SetLineCommentSymbols() duparrayref',
|
||||
'BLOCK_COMMENT_SYMBOLS', 'BlockCommentSymbols()',
|
||||
'SetBlockCommentSymbols() duparrayref',
|
||||
'PROTOTYPE_ENDERS',
|
||||
'LINE_EXTENDER', 'LineExtender()', 'SetLineExtender()',
|
||||
'PACKAGE_SEPARATOR', 'PackageSeparator()',
|
||||
'PACKAGE_SEPARATOR_WAS_SET', 'PackageSeparatorWasSet()',
|
||||
'ENUM_VALUES', 'EnumValues()',
|
||||
'ENUM_VALUES_WAS_SET', 'EnumValuesWasSet()';
|
||||
|
||||
#
|
||||
# Function: New
|
||||
#
|
||||
# Creates and returns a new object.
|
||||
#
|
||||
# Parameters:
|
||||
#
|
||||
# name - The name of the language.
|
||||
#
|
||||
sub New #(name)
|
||||
{
|
||||
my ($selfPackage, $name) = @_;
|
||||
|
||||
my $object = $selfPackage->SUPER::New($name);
|
||||
|
||||
$object->[ENUM_VALUES] = ::ENUM_GLOBAL();
|
||||
$object->[PACKAGE_SEPARATOR] = '.';
|
||||
|
||||
return $object;
|
||||
};
|
||||
|
||||
|
||||
#
|
||||
# Functions: Members
|
||||
#
|
||||
# LineCommentSymbols - Returns an arrayref of symbols that start a line comment, or undef if none.
|
||||
# SetLineCommentSymbols - Replaces the arrayref of symbols that start a line comment.
|
||||
# BlockCommentSymbols - Returns an arrayref of start/end symbol pairs that specify a block comment, or undef if none. Pairs
|
||||
# are specified with two consecutive array entries.
|
||||
# SetBlockCommentSymbols - Replaces the arrayref of start/end symbol pairs that specify a block comment. Pairs are
|
||||
# specified with two consecutive array entries.
|
||||
# LineExtender - Returns the symbol to ignore a line break in languages where line breaks are significant.
|
||||
# SetLineExtender - Replaces the symbol to ignore a line break in languages where line breaks are significant.
|
||||
# PackageSeparator - Returns the package separator symbol.
|
||||
# PackageSeparatorWasSet - Returns whether the package separator symbol was ever changed from the default.
|
||||
#
|
||||
|
||||
#
|
||||
# Function: SetPackageSeparator
|
||||
# Replaces the language's package separator string.
|
||||
#
|
||||
sub SetPackageSeparator #(separator)
|
||||
{
|
||||
my ($self, $separator) = @_;
|
||||
$self->[PACKAGE_SEPARATOR] = $separator;
|
||||
$self->[PACKAGE_SEPARATOR_WAS_SET] = 1;
|
||||
};
|
||||
|
||||
|
||||
#
|
||||
# Functions: Members
|
||||
#
|
||||
# EnumValues - Returns the <EnumValuesType> that describes how the language handles enums.
|
||||
# EnumValuesWasSet - Returns whether <EnumValues> was ever changed from the default.
|
||||
|
||||
|
||||
#
|
||||
# Function: SetEnumValues
|
||||
# Replaces the <EnumValuesType> that describes how the language handles enums.
|
||||
#
|
||||
sub SetEnumValues #(EnumValuesType newBehavior)
|
||||
{
|
||||
my ($self, $behavior) = @_;
|
||||
$self->[ENUM_VALUES] = $behavior;
|
||||
$self->[ENUM_VALUES_WAS_SET] = 1;
|
||||
};
|
||||
|
||||
|
||||
#
|
||||
# Function: PrototypeEndersFor
|
||||
#
|
||||
# Returns an arrayref of prototype ender symbols for the passed <TopicType>, or undef if none.
|
||||
#
|
||||
sub PrototypeEndersFor #(type)
|
||||
{
|
||||
my ($self, $type) = @_;
|
||||
|
||||
if (defined $self->[PROTOTYPE_ENDERS])
|
||||
{ return $self->[PROTOTYPE_ENDERS]->{$type}; }
|
||||
else
|
||||
{ return undef; };
|
||||
};
|
||||
|
||||
|
||||
#
|
||||
# Function: SetPrototypeEndersFor
|
||||
#
|
||||
# Replaces the arrayref of prototype ender symbols for the passed <TopicType>.
|
||||
#
|
||||
sub SetPrototypeEndersFor #(type, enders)
|
||||
{
|
||||
my ($self, $type, $enders) = @_;
|
||||
|
||||
if (!defined $self->[PROTOTYPE_ENDERS])
|
||||
{ $self->[PROTOTYPE_ENDERS] = { }; };
|
||||
|
||||
if (!defined $enders)
|
||||
{ delete $self->[PROTOTYPE_ENDERS]->{$type}; }
|
||||
else
|
||||
{
|
||||
$self->[PROTOTYPE_ENDERS]->{$type} = [ @$enders ];
|
||||
};
|
||||
};
|
||||
|
||||
|
||||
|
||||
|
||||
###############################################################################
|
||||
# Group: Parsing Functions
|
||||
|
||||
|
||||
#
|
||||
# Function: ParseFile
|
||||
#
|
||||
# Parses the passed source file, sending comments acceptable for documentation to <NaturalDocs::Parser->OnComment()>
|
||||
# and all other sections to <OnCode()>.
|
||||
#
|
||||
# Parameters:
|
||||
#
|
||||
# sourceFile - The <FileName> of the source file to parse.
|
||||
# topicList - A reference to the list of <NaturalDocs::Parser::ParsedTopics> being built by the file.
|
||||
#
|
||||
# Returns:
|
||||
#
|
||||
# Since this class cannot automatically document the code or generate a scope record, it always returns ( undef, undef ).
|
||||
#
|
||||
sub ParseFile #(sourceFile, topicsList)
|
||||
{
|
||||
my ($self, $sourceFile, $topicsList) = @_;
|
||||
|
||||
open(SOURCEFILEHANDLE, '<' . $sourceFile)
|
||||
or die "Couldn't open input file " . $sourceFile . "\n";
|
||||
|
||||
my $lineReader = NaturalDocs::LineReader->New(\*SOURCEFILEHANDLE);
|
||||
|
||||
my @commentLines;
|
||||
my @codeLines;
|
||||
my $lastCommentTopicCount = 0;
|
||||
|
||||
if ($self->Name() eq 'Text File')
|
||||
{
|
||||
@commentLines = $lineReader->GetAll();
|
||||
NaturalDocs::Parser->OnComment(\@commentLines, 1);
|
||||
}
|
||||
|
||||
else
|
||||
{
|
||||
my $line = $lineReader->Get();
|
||||
my $lineNumber = 1;
|
||||
|
||||
while (defined $line)
|
||||
{
|
||||
my $originalLine = $line;
|
||||
|
||||
|
||||
# Retrieve multiline comments. This leaves $line at the next line.
|
||||
# We check for multiline comments before single line comments because in Lua the symbols are --[[ and --.
|
||||
|
||||
if (my $closingSymbol = $self->StripOpeningBlockSymbols(\$line, $self->BlockCommentSymbols()))
|
||||
{
|
||||
# Note that it is possible for a multiline comment to start correctly but not end so. We want those comments to stay in
|
||||
# the code. For example, look at this prototype with this splint annotation:
|
||||
#
|
||||
# int get_array(integer_t id,
|
||||
# /*@out@*/ array_t array);
|
||||
#
|
||||
# The annotation starts correctly but doesn't end so because it is followed by code on the same line.
|
||||
|
||||
my $lineRemainder;
|
||||
|
||||
for (;;)
|
||||
{
|
||||
$lineRemainder = $self->StripClosingSymbol(\$line, $closingSymbol);
|
||||
|
||||
push @commentLines, $line;
|
||||
|
||||
# If we found an end comment symbol...
|
||||
if (defined $lineRemainder)
|
||||
{ last; };
|
||||
|
||||
$line = $lineReader->Get();
|
||||
|
||||
if (!defined $line)
|
||||
{ last; };
|
||||
};
|
||||
|
||||
if ($lineRemainder !~ /^[ \t]*$/)
|
||||
{
|
||||
# If there was something past the closing symbol this wasn't an acceptable comment, so move the lines to code.
|
||||
push @codeLines, @commentLines;
|
||||
@commentLines = ( );
|
||||
};
|
||||
|
||||
$line = $lineReader->Get();
|
||||
}
|
||||
|
||||
|
||||
# Retrieve single line comments. This leaves $line at the next line.
|
||||
|
||||
elsif ($self->StripOpeningSymbols(\$line, $self->LineCommentSymbols()))
|
||||
{
|
||||
do
|
||||
{
|
||||
push @commentLines, $line;
|
||||
$line = $lineReader->Get();
|
||||
|
||||
if (!defined $line)
|
||||
{ goto EndDo; };
|
||||
}
|
||||
while ($self->StripOpeningSymbols(\$line, $self->LineCommentSymbols()));
|
||||
|
||||
EndDo: # I hate Perl sometimes.
|
||||
}
|
||||
|
||||
|
||||
# Otherwise just add it to the code.
|
||||
|
||||
else
|
||||
{
|
||||
push @codeLines, $line;
|
||||
$line = $lineReader->Get();
|
||||
};
|
||||
|
||||
|
||||
# If there were comments, send them to Parser->OnComment().
|
||||
|
||||
if (scalar @commentLines)
|
||||
{
|
||||
# First process any code lines before the comment.
|
||||
if (scalar @codeLines)
|
||||
{
|
||||
$self->OnCode(\@codeLines, $lineNumber, $topicsList, $lastCommentTopicCount);
|
||||
$lineNumber += scalar @codeLines;
|
||||
@codeLines = ( );
|
||||
};
|
||||
|
||||
$lastCommentTopicCount = NaturalDocs::Parser->OnComment(\@commentLines, $lineNumber);
|
||||
$lineNumber += scalar @commentLines;
|
||||
@commentLines = ( );
|
||||
};
|
||||
|
||||
}; # while (defined $line)
|
||||
|
||||
|
||||
# Clean up any remaining code.
|
||||
if (scalar @codeLines)
|
||||
{
|
||||
$self->OnCode(\@codeLines, $lineNumber, $topicsList, $lastCommentTopicCount);
|
||||
@codeLines = ( );
|
||||
};
|
||||
|
||||
};
|
||||
|
||||
close(SOURCEFILEHANDLE);
|
||||
|
||||
return ( undef, undef );
|
||||
};
|
||||
|
||||
|
||||
#
|
||||
# Function: OnCode
|
||||
#
|
||||
# Called whenever a section of code is encountered by the parser. Is used to find the prototype of the last topic created.
|
||||
#
|
||||
# Parameters:
|
||||
#
|
||||
# codeLines - The source code as an arrayref of lines.
|
||||
# codeLineNumber - The line number of the first line of code.
|
||||
# topicList - A reference to the list of <NaturalDocs::Parser::ParsedTopics> being built by the file.
|
||||
# lastCommentTopicCount - The number of Natural Docs topics that were created by the last comment.
|
||||
#
|
||||
sub OnCode #(codeLines, codeLineNumber, topicList, lastCommentTopicCount)
|
||||
{
|
||||
my ($self, $codeLines, $codeLineNumber, $topicList, $lastCommentTopicCount) = @_;
|
||||
|
||||
if ($lastCommentTopicCount && defined $self->PrototypeEndersFor($topicList->[-1]->Type()))
|
||||
{
|
||||
my $lineIndex = 0;
|
||||
my $prototype;
|
||||
|
||||
# Skip all blank lines before a prototype.
|
||||
while ($lineIndex < scalar @$codeLines && $codeLines->[$lineIndex] =~ /^[ \t]*$/)
|
||||
{ $lineIndex++; };
|
||||
|
||||
my @tokens;
|
||||
my $tokenIndex = 0;
|
||||
|
||||
my @brackets;
|
||||
my $enders = $self->PrototypeEndersFor($topicList->[-1]->Type());
|
||||
|
||||
# Add prototype lines until we reach the end of the prototype or the end of the code lines.
|
||||
while ($lineIndex < scalar @$codeLines)
|
||||
{
|
||||
my $line = $self->RemoveLineExtender($codeLines->[$lineIndex] . "\n");
|
||||
|
||||
push @tokens, $line =~ /([^\(\)\[\]\{\}\<\>]+|.)/g;
|
||||
|
||||
while ($tokenIndex < scalar @tokens)
|
||||
{
|
||||
# If we're not inside brackets, check for ender symbols.
|
||||
if (!scalar @brackets)
|
||||
{
|
||||
my $startingIndex = 0;
|
||||
my $testPrototype;
|
||||
|
||||
for (;;)
|
||||
{
|
||||
my ($enderIndex, $ender) = ::FindFirstSymbol($tokens[$tokenIndex], $enders, $startingIndex);
|
||||
|
||||
if ($enderIndex == -1)
|
||||
{ last; }
|
||||
else
|
||||
{
|
||||
# We do this here so we don't duplicate prototype for every single token. Just the first time an ender symbol
|
||||
# is found in one.
|
||||
if (!defined $testPrototype)
|
||||
{ $testPrototype = $prototype; };
|
||||
|
||||
$testPrototype .= substr($tokens[$tokenIndex], $startingIndex, $enderIndex - $startingIndex);
|
||||
|
||||
my $enderResult;
|
||||
|
||||
# If the ender is all text and the character preceding or following it is as well, ignore it.
|
||||
if ($ender =~ /^[a-z0-9]+$/i &&
|
||||
( ($enderIndex > 0 && substr($tokens[$tokenIndex], $enderIndex - 1, 1) =~ /^[a-z0-9_]$/i) ||
|
||||
substr($tokens[$tokenIndex], $enderIndex + length($ender), 1) =~ /^[a-z0-9_]$/i ) )
|
||||
{ $enderResult = ENDER_IGNORE(); }
|
||||
else
|
||||
{ $enderResult = $self->OnPrototypeEnd($topicList->[-1]->Type(), \$testPrototype, $ender); }
|
||||
|
||||
if ($enderResult == ENDER_IGNORE())
|
||||
{
|
||||
$testPrototype .= $ender;
|
||||
$startingIndex = $enderIndex + length($ender);
|
||||
}
|
||||
elsif ($enderResult == ENDER_REVERT_TO_ACCEPTED())
|
||||
{
|
||||
return;
|
||||
}
|
||||
else # ENDER_ACCEPT || ENDER_ACCEPT_AND_CONTINUE
|
||||
{
|
||||
my $titleInPrototype = $topicList->[-1]->Title();
|
||||
|
||||
# Strip parenthesis so Function(2) and Function(int, int) will still match Function(anything).
|
||||
$titleInPrototype =~ s/[\t ]*\([^\(]*$//;
|
||||
|
||||
if (index($testPrototype, $titleInPrototype) != -1)
|
||||
{
|
||||
$topicList->[-1]->SetPrototype( $self->NormalizePrototype($testPrototype) );
|
||||
};
|
||||
|
||||
if ($enderResult == ENDER_ACCEPT())
|
||||
{ return; }
|
||||
else # ENDER_ACCEPT_AND_CONTINUE
|
||||
{
|
||||
$testPrototype .= $ender;
|
||||
$startingIndex = $enderIndex + length($ender);
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
# If we are inside brackets, check for closing symbols.
|
||||
elsif ( ($tokens[$tokenIndex] eq ')' && $brackets[-1] eq '(') ||
|
||||
($tokens[$tokenIndex] eq ']' && $brackets[-1] eq '[') ||
|
||||
($tokens[$tokenIndex] eq '}' && $brackets[-1] eq '{') ||
|
||||
($tokens[$tokenIndex] eq '>' && $brackets[-1] eq '<') )
|
||||
{
|
||||
pop @brackets;
|
||||
};
|
||||
|
||||
# Check for opening brackets.
|
||||
if ($tokens[$tokenIndex] =~ /^[\(\[\{]$/ ||
|
||||
($tokens[$tokenIndex] eq "<" && $tokens[$tokenIndex-1] !~ /operator[ \t]*$/) )
|
||||
{
|
||||
push @brackets, $tokens[$tokenIndex];
|
||||
};
|
||||
|
||||
$prototype .= $tokens[$tokenIndex];
|
||||
$tokenIndex++;
|
||||
};
|
||||
|
||||
$lineIndex++;
|
||||
};
|
||||
|
||||
# If we got out of that while loop by running out of lines, there was no prototype.
|
||||
};
|
||||
};
|
||||
|
||||
|
||||
use constant ENDER_ACCEPT => 1;
|
||||
use constant ENDER_IGNORE => 2;
|
||||
use constant ENDER_ACCEPT_AND_CONTINUE => 3;
|
||||
use constant ENDER_REVERT_TO_ACCEPTED => 4;
|
||||
|
||||
#
|
||||
# Function: OnPrototypeEnd
|
||||
#
|
||||
# Called whenever the end of a prototype is found so that there's a chance for derived classes to mark false positives.
|
||||
#
|
||||
# Parameters:
|
||||
#
|
||||
# type - The <TopicType> of the prototype.
|
||||
# prototypeRef - A reference to the prototype so far, minus the ender in dispute.
|
||||
# ender - The ender symbol.
|
||||
#
|
||||
# Returns:
|
||||
#
|
||||
# ENDER_ACCEPT - The ender is accepted and the prototype is finished.
|
||||
# ENDER_IGNORE - The ender is rejected and parsing should continue. Note that the prototype will be rejected as a whole
|
||||
# if all enders are ignored before reaching the end of the code.
|
||||
# ENDER_ACCEPT_AND_CONTINUE - The ender is accepted so the prototype may stand as is. However, the prototype might
|
||||
# also continue on so continue parsing. If there is no accepted ender between here and
|
||||
# the end of the code this version will be accepted instead.
|
||||
# ENDER_REVERT_TO_ACCEPTED - The expedition from ENDER_ACCEPT_AND_CONTINUE failed. Use the last accepted
|
||||
# version and end parsing.
|
||||
#
|
||||
sub OnPrototypeEnd #(type, prototypeRef, ender)
|
||||
{
|
||||
return ENDER_ACCEPT();
|
||||
};
|
||||
|
||||
|
||||
#
|
||||
# Function: RemoveLineExtender
|
||||
#
|
||||
# If the passed line has a line extender, returns it without the extender or the line break that follows. If it doesn't, or there are
|
||||
# no line extenders defined, returns the passed line unchanged.
|
||||
#
|
||||
sub RemoveLineExtender #(line)
|
||||
{
|
||||
my ($self, $line) = @_;
|
||||
|
||||
if (defined $self->LineExtender())
|
||||
{
|
||||
my $lineExtenderIndex = rindex($line, $self->LineExtender());
|
||||
|
||||
if ($lineExtenderIndex != -1 &&
|
||||
substr($line, $lineExtenderIndex + length($self->LineExtender())) =~ /^[ \t]*\n$/)
|
||||
{
|
||||
$line = substr($line, 0, $lineExtenderIndex) . ' ';
|
||||
};
|
||||
};
|
||||
|
||||
return $line;
|
||||
};
|
||||
|
||||
|
||||
1;
|
||||
Reference in New Issue
Block a user