From 9ba8e6cf38da5196ed7bc878fe452952f3e10638 Mon Sep 17 00:00:00 2001 From: Magnus Auvinen Date: Tue, 22 May 2007 15:06:55 +0000 Subject: moved docs --- .../doctool/Modules/NaturalDocs/ReferenceString.pm | 301 +++++++++++++++++++++ 1 file changed, 301 insertions(+) create mode 100644 docs/doctool/Modules/NaturalDocs/ReferenceString.pm (limited to 'docs/doctool/Modules/NaturalDocs/ReferenceString.pm') diff --git a/docs/doctool/Modules/NaturalDocs/ReferenceString.pm b/docs/doctool/Modules/NaturalDocs/ReferenceString.pm new file mode 100644 index 00000000..c9bca75a --- /dev/null +++ b/docs/doctool/Modules/NaturalDocs/ReferenceString.pm @@ -0,0 +1,301 @@ +############################################################################### +# +# Package: NaturalDocs::ReferenceString +# +############################################################################### +# +# A package to manage handling throughout the program. +# +############################################################################### + +# This file is part of Natural Docs, which is Copyright (C) 2003-2005 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' ); + + +# +# Constants: Binary Format Flags +# +# These flags can be combined to specify the format when using and . All are exported +# by default. +# +# BINARYREF_NOTYPE - Do not include the . +# BINARYREF_NORESOLVEFLAGS - Do not include the . +# +use constant BINARYREF_NOTYPE => 0x01; +use constant BINARYREF_NORESOLVINGFLAGS => 0x02; + + +# +# +# Function: MakeFrom +# +# Encodes the passed information as a . 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 . +# symbol - The of the reference. +# scope - The scope the reference appears in, or undef if none. +# using - An arrayref of scope that are also available for checking due to the equivalent a "using" statement, +# or undef if none. +# resolvingFlags - The to use with this reference. They are ignored if the type is . +# +# Returns: +# +# The encoded . +# +sub MakeFrom #(type, symbol, scope, using, resolvingFlags) + { + my ($self, $type, $symbol, $scope, $using, $resolvingFlags) = @_; + + if ($type == ::REFERENCE_TEXT() || $resolvingFlags == 0) + { $resolvingFlags = undef; }; + + # The format is [type] 0x1E [resolving flags] \x1E [symbol] 0x1E [scope] ( 0x1E [using] )* + # The format of the symbol, scope, and usings are the identifiers separated by 0x1F characters. + # If scope is undef but using isn't, there will be two 0x1E's to signify the missing scope. + + my @identifiers = NaturalDocs::SymbolString->IdentifiersOf($symbol); + + my $string = $type . "\x1E" . $resolvingFlags . "\x1E" . join("\x1F", @identifiers); + + if (defined $scope) + { + @identifiers = NaturalDocs::SymbolString->IdentifiersOf($scope); + $string .= "\x1E" . join("\x1F", @identifiers); + }; + + if (defined $using) + { + my @usingStrings; + + foreach my $using (@$using) + { + @identifiers = NaturalDocs::SymbolString->IdentifiersOf($using); + push @usingStrings, join("\x1F", @identifiers); + }; + + if (!defined $scope) + { $string .= "\x1E"; }; + + $string .= "\x1E" . join("\x1E", @usingStrings); + }; + + return $string; + }; + + +# +# Function: ToBinaryFile +# +# Writes a to the passed filehandle. Can also encode an undef. +# +# Parameters: +# +# fileHandle - The filehandle to write to. +# referenceString - The to write, or undef. +# binaryFormatFlags - Any you want to use to influence encoding. +# +# Format: +# +# > [SymbolString: Symbol or undef for an undef reference] +# > [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: +# +# - must fit into a UInt8. All values must be <= 255. +# - All must fit into a UInt8. All values must be <= 255. +# +sub ToBinaryFile #(fileHandle, referenceString, binaryFormatFlags) + { + my ($self, $fileHandle, $referenceString, $binaryFormatFlags) = @_; + + my ($type, $symbol, $scope, $using, $resolvingFlags) = $self->InformationOf($referenceString); + + # [SymbolString: Symbol or undef for an undef reference] + + NaturalDocs::SymbolString->ToBinaryFile($fileHandle, $symbol); + + # [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 or undef from the passed filehandle. +# +# Parameters: +# +# fileHandle - The filehandle to read from. +# binaryFormatFlags - Any you want to use to influence decoding. +# type - The to use if is set. +# resolvingFlags - The to use if is set. +# +# Returns: +# +# The or undef. +# +# See Also: +# +# See for format and dependencies. +# +sub FromBinaryFile #(fileHandle, binaryFormatFlags, type, resolvingFlags) + { + my ($self, $fileHandle, $binaryFormatFlags, $type, $resolvingFlags) = @_; + + # [SymbolString: Symbol or undef for an undef reference] + + my $symbol = NaturalDocs::SymbolString->FromBinaryFile($fileHandle); + + if (!defined $symbol) + { return undef; }; + + # [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, $scope, $usingSymbol, $resolvingFlags); + }; + + +# +# Function: InformationOf +# +# Returns the information encoded in a . +# +# Parameters: +# +# referenceString - The to decode. +# +# Returns: +# +# The array ( type, symbol, scope, using, resolvingFlags ). +# +# type - The . +# symbol - The . +# scope - The scope , or undef if none. +# using - An arrayref of scope that the reference also has access to via "using" statements, or undef if none. +# resolvingFlags - The of the reference. +# +sub InformationOf #(referenceString) + { + my ($self, $referenceString) = @_; + + my ($type, $resolvingFlags, $symbolString, $scopeString, @usingStrings) = split(/\x1E/, $referenceString); + + if (!length $resolvingFlags) + { $resolvingFlags = undef; }; + + my @identifiers = split(/\x1F/, $symbolString); + my $symbol = NaturalDocs::SymbolString->Join(@identifiers); + + my $scope; + if (defined $scopeString && length($scopeString)) + { + @identifiers = split(/\x1F/, $scopeString); + $scope = NaturalDocs::SymbolString->Join(@identifiers); + }; + + my $using; + if (scalar @usingStrings) + { + $using = [ ]; + foreach my $usingString (@usingStrings) + { + @identifiers = split(/\x1F/, $usingString); + push @$using, NaturalDocs::SymbolString->Join(@identifiers); + }; + }; + + return ( $type, $symbol, $scope, $using, $resolvingFlags ); + }; + + +# +# Function: TypeOf +# +# Returns the encoded in the reference string. This is faster than if this is +# the only information you need. +# +sub TypeOf #(referenceString) + { + my ($self, $referenceString) = @_; + + $referenceString =~ /^([^\x1E]+)/; + return $1; + }; + + +1; -- cgit 1.4.1