| #--- TocInsertor.pm ----------------------------------------------------------- |
| # function: Insert Table of Contents HTML::Toc, generated by |
| # HTML::TocGenerator. |
| # note: - The term 'propagate' is used as a shortcut for the process of |
| # both generating and inserting a ToC at the same time. |
| # - 'TIP' is an abbreviation of 'Toc Insertion Point'. |
| |
| |
| package HTML::TocInsertor; |
| |
| |
| use strict; |
| use FileHandle; |
| use HTML::TocGenerator; |
| |
| |
| BEGIN { |
| use vars qw(@ISA $VERSION); |
| |
| $VERSION = '0.91'; |
| |
| @ISA = qw(HTML::TocGenerator); |
| } |
| |
| # TocInsertionPoint (TIP) constants |
| |
| use constant TIP_PREPOSITION_REPLACE => 'replace'; |
| use constant TIP_PREPOSITION_BEFORE => 'before'; |
| use constant TIP_PREPOSITION_AFTER => 'after'; |
| |
| use constant TIP_TOKEN_ID => 0; |
| use constant TIP_PREPOSITION => 1; |
| use constant TIP_INCLUDE_ATTRIBUTES => 2; |
| use constant TIP_EXCLUDE_ATTRIBUTES => 3; |
| use constant TIP_TOC => 4; |
| |
| use constant MODE_DO_NOTHING => 0; # 0b00 |
| use constant MODE_DO_INSERT => 1; # 0b01 |
| use constant MODE_DO_PROPAGATE => 3; # 0b11 |
| |
| END {} |
| |
| |
| #--- HTML::TocInsertor::new() ------------------------------------------------- |
| # function: Constructor. |
| |
| sub new { |
| # Get arguments |
| my ($aType) = @_; |
| my $self = $aType->SUPER::new; |
| # TRUE if insertion point token must be output, FALSE if not |
| $self->{_doOutputInsertionPointToken} = 1; |
| # Reset batch variables |
| $self->_resetBatchVariables; |
| # Bias to not insert ToC |
| $self->{hti__Mode} = MODE_DO_NOTHING; |
| |
| # TODO: Initialize output |
| |
| return $self; |
| } # new() |
| |
| |
| #--- HTML::TocInsertor::_deinitializeOutput() --------------------------------- |
| # function: Deinitialize output. |
| |
| sub _deinitializeOutput { |
| # Get arguments |
| my ($self) = @_; |
| # Filehandle is defined? |
| if (defined($self->{_outputFileHandle})) { |
| # Yes, filehandle is defined; |
| # Restore selected filehandle |
| select($self->{_oldFileHandle}); |
| # Undefine filehandle, closing it automatically |
| undef $self->{_outputFileHandle}; |
| } |
| } # _deinitializeOutput() |
| |
| |
| #--- HTML::TocInsertor::_initializeOutput() ----------------------------------- |
| # function: Initialize output. |
| |
| sub _initializeOutput { |
| # Get arguments |
| my ($self) = @_; |
| # Bias to write to outputfile |
| my $doOutputToFile = 1; |
| |
| # Is output specified? |
| if (defined($self->{options}{'output'})) { |
| # Yes, output is specified; |
| # Indicate to not output to outputfile |
| $doOutputToFile = 0; |
| # Alias output reference |
| $self->{_output} = $self->{options}{'output'}; |
| # Clear output |
| ${$self->{_output}} = ""; |
| } |
| |
| # Is output file specified? |
| if (defined($self->{options}{'outputFile'})) { |
| # Yes, output file is specified; |
| # Indicate to output to outputfile |
| $doOutputToFile = 1; |
| # Open file |
| $self->{_outputFileHandle} = |
| new FileHandle ">" . $self->{options}{'outputFile'}; |
| |
| # Backup currently selected filehandle |
| $self->{_oldFileHandle} = select; |
| # Set new default filehandle |
| select($self->{_outputFileHandle}); |
| } |
| |
| # Alias output-to-file indicator |
| $self->{_doOutputToFile} = $doOutputToFile; |
| } # _initializeOutput() |
| |
| |
| #--- HTML::TocInsertor::_deinitializeInsertorBatch() -------------------------- |
| # function: Deinitialize insertor batch. |
| |
| sub _deinitializeInsertorBatch { |
| # Get arguments |
| my ($self) = @_; |
| # Indicate ToC insertion has finished |
| $self->{_isTocInsertionPointPassed} = 0; |
| # Write buffered output |
| $self->_writeBufferedOutput(); |
| # Propagate? |
| if ($self->{hti__Mode} == MODE_DO_PROPAGATE) { |
| # Yes, propagate; |
| # Deinitialize generator batch |
| $self->_deinitializeGeneratorBatch(); |
| } |
| else { |
| # No, insert only; |
| # Do general batch deinitialization |
| $self->_deinitializeBatch(); |
| } |
| # Deinitialize output |
| $self->_deinitializeOutput(); |
| # Indicate end of batch |
| $self->{hti__Mode} = MODE_DO_NOTHING; |
| # Reset batch variables |
| $self->_resetBatchVariables(); |
| } # _deinitializeInsertorBatch() |
| |
| |
| #--- HTML::TocInsertor::_initializeInsertorBatch() ---------------------------- |
| # function: Initialize insertor batch. |
| # args: - $aTocs: Reference to array of tocs. |
| # - $aOptions: optional options |
| |
| sub _initializeInsertorBatch { |
| # Get arguments |
| my ($self, $aTocs, $aOptions) = @_; |
| # Add invocation options |
| $self->setOptions($aOptions); |
| # Option 'doGenerateToc' specified? |
| if (!defined($self->{options}{'doGenerateToc'})) { |
| # No, options 'doGenerateToc' not specified; |
| # Default to 'doGenerateToc' |
| $self->{options}{'doGenerateToc'} = 1; |
| } |
| # Propagate? |
| if ($self->{options}{'doGenerateToc'}) { |
| # Yes, propagate; |
| # Indicate mode |
| $self->{hti__Mode} = MODE_DO_PROPAGATE; |
| # Initialize generator batch |
| # NOTE: This method takes care of calling '_initializeBatch()' |
| $self->_initializeGeneratorBatch($aTocs); |
| } |
| else { |
| # No, insert; |
| # Indicate mode |
| $self->{hti__Mode} = MODE_DO_INSERT; |
| # Do general batch initialization |
| $self->_initializeBatch($aTocs); |
| } |
| # Initialize output |
| $self->_initializeOutput(); |
| # Parse ToC insertion points |
| $self->_parseTocInsertionPoints(); |
| } # _initializeInsertorBatch() |
| |
| |
| #--- HTML::TocInsertor::_insert() --------------------------------------------- |
| # function: Insert ToC in string. |
| # args: - $aString: Reference to string to parse. |
| # note: Used internally. |
| |
| sub _insert { |
| # Get arguments |
| my ($self, $aString) = @_; |
| # Propagate? |
| if ($self->{options}{'doGenerateToc'}) { |
| # Yes, propagate; |
| # Generate & insert ToC |
| $self->_generate($aString); |
| } |
| else { |
| # No, just insert ToC |
| # Insert by parsing file |
| $self->parse($aString); |
| # Flush remaining buffered text |
| $self->eof(); |
| } |
| } # _insert() |
| |
| |
| #--- HTML::TocInsertor::_insertIntoFile() ------------------------------------- |
| # function: Do insert generated ToCs in file. |
| # args: - $aToc: (reference to array of) ToC object(s) to insert. |
| # - $aFile: (reference to array of) file(s) to parse for insertion |
| # points. |
| # - $aOptions: optional insertor options |
| # note: Used internally. |
| |
| sub _insertIntoFile { |
| # Get arguments |
| my ($self, $aFile) = @_; |
| # Local variables; |
| my ($file, @files); |
| # Dereference array reference or make array of file specification |
| @files = (ref($aFile) =~ m/ARRAY/) ? @$aFile : ($aFile); |
| # Loop through files |
| foreach $file (@files) { |
| # Propagate? |
| if ($self->{options}{'doGenerateToc'}) { |
| # Yes, propagate; |
| # Generate and insert ToC |
| $self->_generateFromFile($file); |
| } |
| else { |
| # No, just insert ToC |
| # Insert by parsing file |
| $self->parse_file($file); |
| } |
| } |
| } # _insertIntoFile() |
| |
| |
| #--- HTML::TocInsertor::_parseTocInsertionPoints() ---------------------------- |
| # function: Parse ToC insertion point specifier. |
| |
| sub _parseTocInsertionPoints { |
| # Get arguments |
| my ($self) = @_; |
| # Local variables |
| my ($tipPreposition, $tipToken, $toc, $tokenTipParser); |
| # Create parser for TIP tokens |
| $tokenTipParser = HTML::_TokenTipParser->new( |
| $self->{_tokensTip} |
| ); |
| # Loop through ToCs |
| foreach $toc (@{$self->{_tocs}}) { |
| # Split TIP in preposition and token |
| ($tipPreposition, $tipToken) = split( |
| '\s+', $toc->{options}{'insertionPoint'}, 2 |
| ); |
| # Known preposition? |
| if ( |
| ($tipPreposition ne TIP_PREPOSITION_REPLACE) && |
| ($tipPreposition ne TIP_PREPOSITION_BEFORE) && |
| ($tipPreposition ne TIP_PREPOSITION_AFTER) |
| ) { |
| # No, unknown preposition; |
| # Use default preposition |
| $tipPreposition = TIP_PREPOSITION_AFTER; |
| # Use entire 'insertionPoint' as token |
| $tipToken = $toc->{options}{'insertionPoint'}; |
| } |
| # Indicate current ToC to parser |
| $tokenTipParser->setToc($toc); |
| # Indicate current preposition to parser |
| $tokenTipParser->setPreposition($tipPreposition); |
| # Parse ToC Insertion Point |
| $tokenTipParser->parse($tipToken); |
| # Flush remaining buffered text |
| $tokenTipParser->eof(); |
| } |
| } # _parseTocInsertionPoints() |
| |
| |
| #--- HTML::TocInsertor::_processTokenAsInsertionPoint() ----------------------- |
| # function: Check for token being a ToC insertion point (Tip) token and |
| # process it accordingly. |
| # args: - $aTokenType: type of token: start, end, comment or text. |
| # - $aTokenId: token id of currently parsed token |
| # - $aTokenAttributes: attributes of currently parsed token |
| # - $aOrigText: complete token |
| # returns: 1 if successful -- token is processed as insertion point, 0 |
| # if not. |
| |
| sub _processTokenAsInsertionPoint { |
| # Get arguments |
| my ($self, $aTokenType, $aTokenId, $aTokenAttributes, $aOrigText) = @_; |
| # Local variables |
| my ($i, $result, $tipToken, $tipTokenId, $tipTokens); |
| # Bias to token not functioning as a ToC insertion point (Tip) token |
| $result = 0; |
| # Alias ToC insertion point (Tip) array of right type |
| $tipTokens = $self->{_tokensTip}[$aTokenType]; |
| # Loop through tipTokens |
| $i = 0; |
| while ($i < scalar @{$tipTokens}) { |
| # Aliases |
| $tipToken = $tipTokens->[$i]; |
| $tipTokenId = $tipToken->[TIP_TOKEN_ID]; |
| # Id & attributes match? |
| if ( |
| ($aTokenId =~ m/$tipTokenId/) && ( |
| HTML::TocGenerator::_doesHashContainHash( |
| $aTokenAttributes, $tipToken->[TIP_INCLUDE_ATTRIBUTES], 0 |
| ) && |
| HTML::TocGenerator::_doesHashContainHash( |
| $aTokenAttributes, $tipToken->[TIP_EXCLUDE_ATTRIBUTES], 1 |
| ) |
| ) |
| ) { |
| # Yes, id and attributes match; |
| # Process ToC insertion point |
| $self->_processTocInsertionPoint($tipToken); |
| # Indicate token functions as ToC insertion point |
| $result = 1; |
| # Remove Tip token, automatically advancing to next token |
| splice(@$tipTokens, $i, 1); |
| } |
| else { |
| # No, tag doesn't match ToC insertion point |
| # Advance to next start token |
| $i++; |
| } |
| } |
| # Token functions as ToC insertion point? |
| if ($result) { |
| # Yes, token functions as ToC insertion point; |
| # Process insertion point(s) |
| $self->_processTocInsertionPoints($aOrigText); |
| } |
| # Return value |
| return $result; |
| } # _processTokenAsInsertionPoint() |
| |
| |
| #--- HTML::TocInsertor::toc() ------------------------------------------------- |
| # function: Toc processing method. Add toc reference to scenario. |
| # args: - $aScenario: Scenario to add ToC reference to. |
| # - $aToc: Reference to ToC to insert. |
| # note: The ToC hasn't been build yet; only a reference to the ToC to be |
| # build is inserted. |
| |
| sub toc { |
| # Get arguments |
| my ($self, $aScenario, $aToc) = @_; |
| # Add toc to scenario |
| push(@$aScenario, $aToc); |
| } # toc() |
| |
| |
| #--- HTML::TocInsertor::_processTocInsertionPoint() ---------------------------- |
| # function: Process ToC insertion point. |
| # args: - $aTipToken: Reference to token array item which matches the ToC |
| # insertion point. |
| |
| sub _processTocInsertionPoint { |
| # Get arguments |
| my ($self, $aTipToken) = @_; |
| # Local variables |
| my ($tipToc, $tipPreposition); |
| |
| # Aliases |
| $tipToc = $aTipToken->[TIP_TOC]; |
| $tipPreposition = $aTipToken->[TIP_PREPOSITION]; |
| |
| SWITCH: { |
| # Replace token with ToC? |
| if ($tipPreposition eq TIP_PREPOSITION_REPLACE) { |
| # Yes, replace token; |
| # Indicate ToC insertion point has been passed |
| $self->{_isTocInsertionPointPassed} = 1; |
| # Add ToC reference to scenario reference by calling 'toc' method |
| $self->toc($self->{_scenarioAfterToken}, $tipToc); |
| #push(@{$self->{_scenarioAfterToken}}, $tipTokenToc); |
| # Indicate token itself must not be output |
| $self->{_doOutputInsertionPointToken} = 0; |
| last SWITCH; |
| } |
| # Output ToC before token? |
| if ($tipPreposition eq TIP_PREPOSITION_BEFORE) { |
| # Yes, output ToC before token; |
| # Indicate ToC insertion point has been passed |
| $self->{_isTocInsertionPointPassed} = 1; |
| # Add ToC reference to scenario reference by calling 'toc' method |
| $self->toc($self->{_scenarioBeforeToken}, $tipToc); |
| #push(@{$self->{_scenarioBeforeToken}}, $tipTokenToc); |
| last SWITCH; |
| } |
| # Output ToC after token? |
| if ($tipPreposition eq TIP_PREPOSITION_AFTER) { |
| # Yes, output ToC after token; |
| # Indicate ToC insertion point has been passed |
| $self->{_isTocInsertionPointPassed} = 1; |
| # Add ToC reference to scenario reference by calling 'toc' method |
| $self->toc($self->{_scenarioAfterToken}, $tipToc); |
| #push(@{$self->{_scenarioAfterToken}}, $tipTokenToc); |
| last SWITCH; |
| } |
| } |
| } # _processTocInsertionPoint() |
| |
| |
| #--- HTML::TocInsertor::_processTocInsertionPoints() -------------------------- |
| # function: Process ToC insertion points |
| # args: - $aTokenText: Text of token which acts as insertion point for one |
| # or multiple ToCs. |
| |
| sub _processTocInsertionPoints { |
| # Get arguments |
| my ($self, $aTokenText) = @_; |
| # Local variables |
| my ($outputPrefix, $outputSuffix); |
| # Extend scenario |
| push(@{$self->{_scenario}}, @{$self->{_scenarioBeforeToken}}); |
| |
| if ($outputPrefix = $self->{_outputPrefix}) { |
| push(@{$self->{_scenario}}, \$outputPrefix); |
| $self->{_outputPrefix} = ""; |
| } |
| |
| # Must insertion point token be output? |
| if ($self->{_doOutputInsertionPointToken}) { |
| # Yes, output insertion point token; |
| push(@{$self->{_scenario}}, \$aTokenText); |
| } |
| |
| if ($outputSuffix = $self->{_outputSuffix}) { |
| push(@{$self->{_scenario}}, \$outputSuffix); |
| $self->{_outputSuffix} = ""; |
| } |
| |
| push(@{$self->{_scenario}}, @{$self->{_scenarioAfterToken}}); |
| # Add new act to scenario for output to come |
| my $output = ""; |
| push(@{$self->{_scenario}}, \$output); |
| # Write output, processing possible '_outputSuffix' |
| #$self->_writeOrBufferOutput(""); |
| # Reset helper scenario's |
| $self->{_scenarioBeforeToken} = []; |
| $self->{_scenarioAfterToken} = []; |
| # Reset bias value to output insertion point token |
| $self->{_doOutputInsertionPointToken} = 1; |
| |
| } # _processTocInsertionPoints() |
| |
| |
| #--- HTML::Toc::_resetBatchVariables() ---------------------------------------- |
| # function: Reset batch variables. |
| |
| sub _resetBatchVariables { |
| my ($self) = @_; |
| # Call ancestor |
| $self->SUPER::_resetBatchVariables(); |
| # Array containing references to scalars. This array depicts the order |
| # in which output must be performed after the first ToC Insertion Point |
| # has been passed. |
| $self->{_scenario} = []; |
| # Helper scenario |
| $self->{_scenarioBeforeToken} = []; |
| # Helper scenario |
| $self->{_scenarioAfterToken} = []; |
| # Arrays containing start, end, comment, text & declaration tokens which |
| # must trigger the ToC insertion. Each array element may contain a |
| # reference to an array containing the following elements: |
| $self->{_tokensTip} = [ |
| [], # TT_TOKENTYPE_START |
| [], # TT_TOKENTYPE_END |
| [], # TT_TOKENTYPE_COMMENT |
| [], # TT_TOKENTYPE_TEXT |
| [] # TT_TOKENTYPE_DECLARATION |
| ]; |
| # 1 if ToC insertion point has been passed, 0 if not |
| $self->{_isTocInsertionPointPassed} = 0; |
| # Tokens after ToC |
| $self->{outputBuffer} = ""; |
| # Trailing text after parsed token |
| $self->{_outputSuffix} = ""; |
| # Preceding text before parsed token |
| $self->{_outputPrefix} = ""; |
| } # _resetBatchVariables() |
| |
| |
| #--- HTML::TocInsertor::_writeBufferedOutput() -------------------------------- |
| # function: Write buffered output to output device(s). |
| |
| sub _writeBufferedOutput { |
| # Get arguments |
| my ($self) = @_; |
| # Local variables |
| my ($scene); |
| # Must ToC be parsed? |
| if ($self->{options}{'parseToc'}) { |
| # Yes, ToC must be parsed; |
| # Parse ToC |
| #$self->parse($self->{toc}); |
| # Output tokens after ToC |
| #$self->_writeOrBufferOutput($self->{outputBuffer}); |
| } |
| else { |
| # No, ToC needn't be parsed; |
| # Output scenario |
| foreach $scene (@{$self->{_scenario}}) { |
| # Is scene a reference to a scalar? |
| if (ref($scene) eq "SCALAR") { |
| # Yes, scene is a reference to a scalar; |
| # Output scene |
| $self->_writeOutput($$scene); |
| } |
| else { |
| # No, scene must be reference to HTML::Toc; |
| # Output toc |
| $self->_writeOutput($scene->format()); |
| } |
| } |
| } |
| } # _writeBufferedOutput() |
| |
| |
| #--- HTML::TocInsertor::_writeOrBufferOutput() -------------------------------- |
| # function: Write processed HTML to output device(s). |
| # args: - aOutput: scalar to write |
| # note: If '_isTocInsertionPointPassed' text is buffered before being |
| # output because the ToC has to be generated before it can be output. |
| # Only after the entire data has been parsed, the ToC and the |
| # following text will be output. |
| |
| sub _writeOrBufferOutput { |
| # Get arguments |
| my ($self, $aOutput) = @_; |
| |
| # Add possible output prefix and suffix |
| $aOutput = $self->{_outputPrefix} . $aOutput . $self->{_outputSuffix}; |
| # Clear output prefix and suffix |
| $self->{_outputPrefix} = ""; |
| $self->{_outputSuffix} = ""; |
| |
| # Has ToC insertion point been passed? |
| if ($self->{_isTocInsertionPointPassed}) { |
| # Yes, ToC insertion point has been passed; |
| # Buffer output; add output to last '_scenario' item |
| my $index = scalar(@{$self->{_scenario}}) - 1; |
| ${$self->{_scenario}[$index]} .= $aOutput; |
| } |
| else { |
| # No, ToC insertion point hasn't been passed; |
| # Write output |
| $self->_writeOutput($aOutput); |
| } |
| } # _writeOrBufferOutput() |
| |
| |
| #--- HTML::TocInsertor::_writeOutput() ---------------------------------------- |
| # function: Write processed HTML to output device(s). |
| # args: - aOutput: scalar to write |
| |
| sub _writeOutput { |
| # Get arguments |
| my ($self, $aOutput) = @_; |
| # Write output to scalar; |
| ${$self->{_output}} .= $aOutput if (defined($self->{_output})); |
| # Write output to output file |
| print $aOutput if ($self->{_doOutputToFile}) |
| } # _writeOutput() |
| |
| |
| #--- HTML::TocGenerator::anchorId() ------------------------------------------- |
| # function: Anchor id processing method. |
| # args: - $aAnchorId |
| |
| sub anchorId { |
| # Get arguments |
| my ($self, $aAnchorId) = @_; |
| # Indicate id must be added to start tag |
| $self->{_doAddAnchorIdToStartTag} = 1; |
| $self->{_anchorId} = $aAnchorId; |
| } # anchorId() |
| |
| |
| #--- HTML::TocInsertor::anchorNameBegin() ------------------------------------- |
| # function: Process anchor name begin, generated by HTML::TocGenerator. |
| # args: - $aAnchorNameBegin: Anchor name begin tag to output. |
| # - $aToc: Reference to ToC to which anchorname belongs. |
| |
| sub anchorNameBegin { |
| # Get arguments |
| my ($self, $aAnchorNameBegin, $aToc) = @_; |
| # Is another anchorName active? |
| if (defined($self->{_activeAnchorName})) { |
| # Yes, another anchorName is active; |
| # Show warning |
| print "Warn\n"; |
| $self->_showWarning( |
| HTML::TocGenerator::WARNING_NESTED_ANCHOR_PS_WITHIN_PS, |
| [$aAnchorNameBegin, $self->{_activeAnchorName}] |
| ); |
| } |
| # Store anchor name as output prefix |
| $self->{_outputPrefix} = $aAnchorNameBegin; |
| # Indicate active anchor name |
| $self->{_activeAnchorName} = $aAnchorNameBegin; |
| # Indicate anchor name end must be output |
| $self->{_doOutputAnchorNameEnd} = 1; |
| } # anchorNameBegin() |
| |
| |
| #--- HTML::TocInsertor::anchorNameEnd() --------------------------------------- |
| # function: Process anchor name end, generated by HTML::TocGenerator. |
| # args: - $aAnchorNameEnd: Anchor name end tag to output. |
| # - $aToc: Reference to ToC to which anchorname belongs. |
| |
| sub anchorNameEnd { |
| # Get arguments |
| my ($self, $aAnchorNameEnd) = @_; |
| # Store anchor name as output prefix |
| $self->{_outputSuffix} .= $aAnchorNameEnd; |
| # Indicate deactive anchor name |
| $self->{_activeAnchorName} = undef; |
| } # anchorNameEnd() |
| |
| |
| #--- HTML::TocInsertor::comment() --------------------------------------------- |
| # function: Process comment. |
| # args: - $aComment: comment text with '<!--' and '-->' tags stripped off. |
| |
| sub comment { |
| # Get arguments |
| my ($self, $aComment) = @_; |
| # Local variables |
| my ($tocInsertionPointToken, $doOutput, $origText); |
| # Allow ancestor to process the comment tag |
| $self->SUPER::comment($aComment); |
| # Assemble original comment |
| $origText = "<!--$aComment-->"; |
| # Must ToCs be inserted? |
| if ($self->{hti__Mode} & MODE_DO_INSERT) { |
| # Yes, ToCs must be inserted; |
| # Processing comment as ToC insertion point is successful? |
| if (! $self->_processTokenAsInsertionPoint( |
| HTML::TocGenerator::TT_TOKENTYPE_COMMENT, $aComment, undef, $origText |
| )) { |
| # No, comment isn't a ToC insertion point; |
| # Output comment normally |
| $self->_writeOrBufferOutput($origText); |
| } |
| } |
| } # comment() |
| |
| |
| #--- HTML::TocInsertor::declaration() ----------------------------------------- |
| # function: This function is called every time a declaration is encountered |
| # by HTML::Parser. |
| |
| sub declaration { |
| # Get arguments |
| my ($self, $aDeclaration) = @_; |
| # Allow ancestor to process the declaration tag |
| $self->SUPER::declaration($aDeclaration); |
| # Must ToCs be inserted? |
| if ($self->{hti__Mode} & MODE_DO_INSERT) { |
| # Yes, ToCs must be inserted; |
| # Processing declaration as ToC insertion point is successful? |
| if (! $self->_processTokenAsInsertionPoint( |
| HTML::TocGenerator::TT_TOKENTYPE_DECLARATION, $aDeclaration, undef, |
| "<!$aDeclaration>" |
| )) { |
| # No, declaration isn't a ToC insertion point; |
| # Output declaration normally |
| $self->_writeOrBufferOutput("<!$aDeclaration>"); |
| } |
| } |
| } # declaration() |
| |
| |
| #--- HTML::TocInsertor::end() ------------------------------------------------- |
| # function: This function is called every time a closing tag is encountered |
| # by HTML::Parser. |
| # args: - $aTag: tag name (in lower case). |
| |
| sub end { |
| # Get arguments |
| my ($self, $aTag, $aOrigText) = @_; |
| # Allow ancestor to process the end tag |
| $self->SUPER::end($aTag, $aOrigText); |
| # Must ToCs be inserted? |
| if ($self->{hti__Mode} & MODE_DO_INSERT) { |
| # Yes, ToCs must be inserted; |
| # Processing end tag as ToC insertion point is successful? |
| if (! $self->_processTokenAsInsertionPoint( |
| HTML::TocGenerator::TT_TOKENTYPE_END, $aTag, undef, $aOrigText |
| )) { |
| # No, end tag isn't a ToC insertion point; |
| # Output end tag normally |
| $self->_writeOrBufferOutput($aOrigText); |
| } |
| } |
| } # end() |
| |
| |
| #--- HTML::TocInsertor::insert() ---------------------------------------------- |
| # function: Insert ToC in string. |
| # args: - $aToc: (reference to array of) ToC object to insert |
| # - $aString: string to insert ToC in |
| # - $aOptions: hash reference with optional insertor options |
| |
| sub insert { |
| # Get arguments |
| my ($self, $aToc, $aString, $aOptions) = @_; |
| # Initialize TocInsertor batch |
| $self->_initializeInsertorBatch($aToc, $aOptions); |
| # Do insert Toc |
| $self->_insert($aString); |
| # Deinitialize TocInsertor batch |
| $self->_deinitializeInsertorBatch(); |
| } # insert() |
| |
| |
| #--- HTML::TocInsertor::insertIntoFile() -------------------------------------- |
| # function: Insert ToCs in file. |
| # args: - $aToc: (reference to array of) ToC object(s) to insert. |
| # - $aFile: (reference to array of) file(s) to parse for insertion |
| # points. |
| # - $aOptions: optional insertor options |
| |
| sub insertIntoFile { |
| # Get arguments |
| my ($self, $aToc, $aFile, $aOptions) = @_; |
| # Initialize TocInsertor batch |
| $self->_initializeInsertorBatch($aToc, $aOptions); |
| # Do insert ToCs into file |
| $self->_insertIntoFile($aFile); |
| # Deinitialize TocInsertor batch |
| $self->_deinitializeInsertorBatch(); |
| } # insertIntoFile() |
| |
| |
| #--- HTML::TocInsertor::number() ---------------------------------------------- |
| # function: Process heading number generated by HTML::Toc. |
| # args: - $aNumber |
| |
| sub number { |
| # Get arguments |
| my ($self, $aNumber) = @_; |
| # Store heading number as output suffix |
| $self->{_outputSuffix} .= $aNumber; |
| } # number() |
| |
| |
| #--- HTML::TocInsertor::propagateFile() --------------------------------------- |
| # function: Propagate ToC; generate & insert ToC, using file as input. |
| # args: - $aToc: (reference to array of) ToC object to insert |
| # - $aFile: (reference to array of) file to parse for insertion |
| # points. |
| # - $aOptions: optional insertor options |
| |
| sub propagateFile { |
| # Get arguments |
| my ($self, $aToc, $aFile, $aOptions) = @_; |
| # Local variables; |
| my ($file, @files); |
| # Initialize TocInsertor batch |
| $self->_initializeInsertorBatch($aToc, $aOptions); |
| # Dereference array reference or make array of file specification |
| @files = (ref($aFile) =~ m/ARRAY/) ? @$aFile : ($aFile); |
| # Loop through files |
| foreach $file (@files) { |
| # Generate and insert ToC |
| $self->_generateFromFile($file); |
| } |
| # Deinitialize TocInsertor batch |
| $self->_deinitializeInsertorBatch(); |
| } # propagateFile() |
| |
| |
| #--- HTML::TocInsertor::start() ----------------------------------------------- |
| # function: This function is called every time an opening tag is encountered. |
| # args: - $aTag: tag name (in lower case). |
| # - $aAttr: reference to hash containing all tag attributes (in lower |
| # case). |
| # - $aAttrSeq: reference to array containing all tag attributes (in |
| # lower case) in the original order |
| # - $aOrigText: the original HTML text |
| |
| sub start { |
| # Get arguments |
| my ($self, $aTag, $aAttr, $aAttrSeq, $aOrigText) = @_; |
| # Local variables |
| my ($doOutput, $i, $tocToken, $tag, $anchorId); |
| # Let ancestor process the start tag |
| $self->SUPER::start($aTag, $aAttr, $aAttrSeq, $aOrigText); |
| # Must ToC be inserted? |
| if ($self->{hti__Mode} & MODE_DO_INSERT) { |
| # Yes, ToC must be inserted; |
| # Processing start tag as ToC insertion point is successful? |
| if (! $self->_processTokenAsInsertionPoint( |
| HTML::TocGenerator::TT_TOKENTYPE_START, $aTag, $aAttr, $aOrigText |
| )) { |
| # No, start tag isn't a ToC insertion point; |
| # Add anchor id? |
| if ($self->{_doAddAnchorIdToStartTag}) { |
| # Yes, anchor id must be added; |
| # Reset indicator; |
| $self->{_doAddAnchorIdToStartTag} = 0; |
| # Alias anchor id |
| $anchorId = $self->{_anchorId}; |
| # Attribute 'id' already exists? |
| if (defined($aAttr->{id})) { |
| # Yes, attribute 'id' already exists; |
| # Show warning |
| print STDERR "WARNING: Overwriting existing id attribute '" . |
| $aAttr->{id} . "' of tag $aOrigText\n"; |
| |
| # Add anchor id to start tag |
| $aOrigText =~ s/(id)=\S*([\s>])/$1=$anchorId$2/i; |
| } |
| else { |
| # No, attribute 'id' doesn't exist; |
| # Add anchor id to start tag |
| $aOrigText =~ s/>/ id=$anchorId>/; |
| } |
| } |
| # Output start tag normally |
| $self->_writeOrBufferOutput($aOrigText); |
| } |
| } |
| } # start() |
| |
| |
| #--- HTML::TocInsertor::text() ------------------------------------------------ |
| # function: This function is called every time plain text is encountered. |
| # args: - @_: array containing data. |
| |
| sub text { |
| # Get arguments |
| my ($self, $aText) = @_; |
| # Let ancestor process the text |
| $self->SUPER::text($aText); |
| # Must ToC be inserted? |
| if ($self->{hti__Mode} & MODE_DO_INSERT) { |
| # Yes, ToC must be inserted; |
| # Processing text as ToC insertion point is successful? |
| if (! $self->_processTokenAsInsertionPoint( |
| HTML::TocGenerator::TT_TOKENTYPE_TEXT, $aText, undef, $aText |
| )) { |
| # No, text isn't a ToC insertion point; |
| # Output text normally |
| $self->_writeOrBufferOutput($aText); |
| } |
| } |
| } # text() |
| |
| |
| |
| |
| #=== HTML::_TokenTipParser ==================================================== |
| # function: Parse 'TIP tokens'. 'TIP tokens' mark HTML code which is to be |
| # used as the ToC Insertion Point. |
| # note: Used internally. |
| |
| package HTML::_TokenTipParser; |
| |
| |
| BEGIN { |
| use vars qw(@ISA); |
| |
| @ISA = qw(HTML::_TokenTocParser); |
| } |
| |
| |
| END {} |
| |
| |
| #--- HTML::_TokenTipParser::new() --------------------------------------------- |
| # function: Constructor |
| |
| sub new { |
| # Get arguments |
| my ($aType, $aTokenArray) = @_; |
| # Create instance |
| my $self = $aType->SUPER::new; |
| # Reference token array |
| $self->{tokens} = $aTokenArray; |
| # Reference to last added token |
| $self->{_lastAddedToken} = undef; |
| $self->{_lastAddedTokenType} = undef; |
| # Return instance |
| return $self; |
| } # new() |
| |
| |
| #--- HTML::_TokenTipParser::_processAttributes() ------------------------------ |
| # function: Process attributes. |
| # args: - $aAttributes: Attributes to parse. |
| |
| sub _processAttributes { |
| # Get arguments |
| my ($self, $aAttributes) = @_; |
| # Local variables |
| my (%includeAttributes, %excludeAttributes); |
| |
| # Parse attributes |
| $self->_parseAttributes( |
| $aAttributes, \%includeAttributes, \%excludeAttributes |
| ); |
| # Include attributes are specified? |
| if (keys(%includeAttributes) > 0) { |
| # Yes, include attributes are specified; |
| # Store include attributes |
| @${$self->{_lastAddedToken}}[ |
| HTML::TocInsertor::TIP_INCLUDE_ATTRIBUTES |
| ] = \%includeAttributes; |
| } |
| # Exclude attributes are specified? |
| if (keys(%excludeAttributes) > 0) { |
| # Yes, exclude attributes are specified; |
| # Store exclude attributes |
| @${$self->{_lastAddedToken}}[ |
| HTML::TocInsertor::TIP_EXCLUDE_ATTRIBUTES |
| ] = \%excludeAttributes; |
| } |
| } # _processAttributes() |
| |
| |
| #--- HTML::_TokenTipParser::_processToken() ----------------------------------- |
| # function: Process token. |
| # args: - $aTokenType: Type of token to process. |
| # - $aTag: Tag of token. |
| |
| sub _processToken { |
| # Get arguments |
| my ($self, $aTokenType, $aTag) = @_; |
| # Local variables |
| my ($tokenArray, $index); |
| # Push element on array of update tokens |
| $index = push(@{$self->{tokens}[$aTokenType]}, []) - 1; |
| # Alias token array to add element to |
| $tokenArray = $self->{tokens}[$aTokenType]; |
| # Indicate last updated token array element |
| $self->{_lastAddedTokenType} = $aTokenType; |
| $self->{_lastAddedToken} = \$$tokenArray[$index]; |
| # Add fields |
| $$tokenArray[$index][HTML::TocInsertor::TIP_TOC] = $self->{_toc}; |
| $$tokenArray[$index][HTML::TocInsertor::TIP_TOKEN_ID] = $aTag; |
| $$tokenArray[$index][HTML::TocInsertor::TIP_PREPOSITION] = |
| $self->{_preposition}; |
| } # _processToken() |
| |
| |
| #--- HTML::_TokenTipParser::comment() ----------------------------------------- |
| # function: Process comment. |
| # args: - $aComment: comment text with '<!--' and '-->' tags stripped off. |
| |
| sub comment { |
| # Get arguments |
| my ($self, $aComment) = @_; |
| # Process token |
| $self->_processToken(HTML::TocGenerator::TT_TOKENTYPE_COMMENT, $aComment); |
| } # comment() |
| |
| |
| #--- HTML::_TokenTipParser::declaration() -------------------------------- |
| # function: This function is called every time a markup declaration is |
| # encountered by HTML::Parser. |
| # args: - $aDeclaration: Markup declaration. |
| |
| sub declaration { |
| # Get arguments |
| my ($self, $aDeclaration) = @_; |
| # Process token |
| $self->_processToken( |
| HTML::TocGenerator::TT_TOKENTYPE_DECLARATION, $aDeclaration |
| ); |
| } # declaration() |
| |
| |
| #--- HTML::_TokenTipParser::end() ---------------------------------------- |
| # function: This function is called every time a closing tag is encountered |
| # by HTML::Parser. |
| # args: - $aTag: tag name (in lower case). |
| |
| sub end { |
| # Get arguments |
| my ($self, $aTag, $aOrigText) = @_; |
| # Process token |
| $self->_processToken(HTML::TocGenerator::TT_TOKENTYPE_END, $aTag); |
| } # end() |
| |
| |
| #--- HTML::_TokenTipParser->setPreposition() ---------------------------------- |
| # function: Set current preposition. |
| |
| sub setPreposition { |
| # Get arguments |
| my ($self, $aPreposition) = @_; |
| # Set current ToC |
| $self->{_preposition} = $aPreposition; |
| } # setPreposition() |
| |
| |
| #--- HTML::_TokenTipParser->setToc() ------------------------------------------ |
| # function: Set current ToC. |
| |
| sub setToc { |
| # Get arguments |
| my ($self, $aToc) = @_; |
| # Set current ToC |
| $self->{_toc} = $aToc; |
| } # setToc() |
| |
| |
| #--- HTML::_TokenTipParser::start() -------------------------------------- |
| # function: This function is called every time an opening tag is encountered. |
| # args: - $aTag: tag name (in lower case). |
| # - $aAttr: reference to hash containing all tag attributes (in lower |
| # case). |
| # - $aAttrSeq: reference to array containing all attribute keys (in |
| # lower case) in the original order |
| # - $aOrigText: the original HTML text |
| |
| sub start { |
| # Get arguments |
| my ($self, $aTag, $aAttr, $aAttrSeq, $aOrigText) = @_; |
| # Process token |
| $self->_processToken(HTML::TocGenerator::TT_TOKENTYPE_START, $aTag); |
| # Process attributes |
| $self->_processAttributes($aAttr); |
| } # start() |
| |
| |
| #--- HTML::_TokenTipParser::text() --------------------------------------- |
| # function: This function is called every time plain text is encountered. |
| # args: - @_: array containing data. |
| |
| sub text { |
| # Get arguments |
| my ($self, $aText) = @_; |
| # Was token already created and is last added token of type 'text'? |
| if ( |
| defined($self->{_lastAddedToken}) && |
| $self->{_lastAddedTokenType} == HTML::TocGenerator::TT_TOKENTYPE_TEXT |
| ) { |
| # Yes, token is already created; |
| # Add tag to existing token |
| @${$self->{_lastAddedToken}}[HTML::TocGenerator::TT_TAG_BEGIN] .= $aText; |
| } |
| else { |
| # No, token isn't created; |
| # Process token |
| $self->_processToken(HTML::TocGenerator::TT_TOKENTYPE_TEXT, $aText); |
| } |
| } # text() |
| |
| |
| 1; |
