<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">###############################################################################
#
#   Class: NaturalDocs::Builder::Base
#
###############################################################################
#
#   A base class for all Builder output formats.
#
###############################################################################

# 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::Builder::Base;


###############################################################################
# Group: Notes


#
#   Topic: Implementation
#
#   Builder packages are implemented as blessed arrayrefs, not hashrefs.  This is done for all objects in Natural Docs for
#   efficiency reasons.  You create members by defining constants via &lt;NaturalDocs::DefineMembers&gt; and using them as
#   indexes into the array.
#

#
#   Topic: Function Order
#
#   The functions in the build process will always be called in the following order.
#
#   - &lt;BeginBuild()&gt; will always be called.
#   - &lt;PurgeFiles()&gt; will be called next only if there's files that need to be purged.
#   - &lt;PurgeIndexes()&gt; will be called next only if there's indexes that need to be purged.
#   - &lt;PurgeImages()&gt; will e called next only if there's images that need to be purged.
#   - &lt;BuildFile()&gt; will be called once for each file that needs to be built, if any.
#   - &lt;BuildIndex()&gt; will be called once for each index that changed and is part of the menu, if any.
#   - &lt;UpdateImage()&gt; will be called once for each image that needs to be updated, if any.
#   - &lt;UpdateMenu()&gt; will be called next only if the menu changed.
#   - &lt;EndBuild()&gt; will always be called.
#

#
#   Topic: How to Approach
#
#   Here's an idea of how to approach making packages for different output types.
#
#
#   Multiple Output Files, Embedded Menu:
#
#       This example is for when you want to build one output file per source file, each with its own copy of the menu within it.
#       This is how &lt;NaturalDocs::Builder::HTML&gt; works.
#
#       Make sure you create a function that generates just the menu for a particular source file.  We'll need to generate menus for
#       both building a file from scratch and for updating the menu on an existing output file, so it's better to give it its own function.
#       You may want to surround it with something that can be easily detected in the output file to make replacing easier.
#
#       &lt;BeginBuild()&gt; isn't important.  You don't need to implement it.
#
#       Implement &lt;PurgeFiles()&gt; to delete the output files associated with the purged files.
#
#       Implement &lt;PurgeIndexes()&gt; to delete the output files associated with the purged indexes.
#
#       Implement &lt;BuildFile()&gt; to create an output file for the parsed source file.  Use the menu function described earlier.
#
#       Implement &lt;BuildIndex()&gt; to create an output file for each index.  Use the menu function described earlier for each page.
#
#       Implement &lt;UpdateMenu()&gt; to go through the list of unbuilt files and update their menus.  You can get the list from
#       &lt;NaturalDocs::Project-&gt;UnbuiltFilesWithContent()&gt;.  You need to open their output files, replace the menu, and save it back
#       to disk.  Yes, it would be simpler from a programmer's point of view to just rebuild the file completely, but that would be
#       _very_ inefficient since there could potentially be a _lot_ of files in this group.
#
#       Also make sure &lt;UpdateMenu()&gt; goes through the unchanged indexes and updates them as well.
#
#       &lt;EndBuild()&gt; isn't important.  You don't need to implement it.
#
#
#   Multiple Output Files, Menu in File:
#
#       This example is for when you want to build one output file per source file, but keep the menu in its own separate file.  This
#       is how &lt;NaturalDocs::Builder::FramedHTML&gt; works.
#
#       &lt;BeginBuild()&gt; isn't important.  You don't need to implement it.
#
#       Implement &lt;PurgeFiles()&gt; to delete the output files associated with the purged files.
#
#       Implement &lt;PurgeIndexes()&gt; to delete the output files associated with the purged indexes.
#
#       Implement &lt;BuildFile()&gt; to generate an output file from the parsed source file.
#
#       Implement &lt;BuildIndex()&gt; to generate an output file for each index.
#
#       Implement &lt;UpdateMenu()&gt; to rebuild the menu file.
#
#       &lt;EndBuild()&gt; isn't important.  You don't need to implement it.
#
#
#   Single Output File using Intermediate Files:
#
#       This example is for when you want to build one output file, such as a PDF file, but use intermediate files to handle differential
#       building.  This would be much like how a compiler compiles each source file into a object file, and then a linker stitches them
#       all together into the final executable file.
#
#       &lt;BeginBuild()&gt; isn't important.  You don't need to implement it.
#
#       Implement &lt;PurgeFiles()&gt; to delete the intermediate files associated with the purged files.
#
#       Implement &lt;PurgeIndexes()&gt; to delete the intermediate files associated with the purged indexes.
#
#       Implement &lt;BuildFile()&gt; to generate an intermediate file from the parsed source file.
#
#       Implement &lt;BuildIndex()&gt; to generate an intermediate file for the specified index.
#
#       Implement &lt;UpdateMenu()&gt; to generate the intermediate file for the menu.
#
#       Implement &lt;EndBuild()&gt; so that if the project changed, it stitches the intermediate files together into the final
#       output file.  Make sure you check the parameter because the function will be called when nothing changes too.
#
#
#   Single Output File using Direct Changes:
#
#       This example is for when you want to build one output file, such as a PDF file, but engineering it in such a way that you don't
#       need to use intermediate files.  In other words, you're able to add, delete, and modify entries directly in the output file.
#
#       Implement &lt;BeginBuild()&gt; so that if the project changed, it opens the output file and does anything it needs to do
#       to get ready for editing.
#
#       Implement &lt;PurgeFiles()&gt; to remove the entries associated with the purged files.
#
#       Implement &lt;PurgeIndexes()&gt; to remove the entries associated with the purged indexes.
#
#       Implement &lt;BuildFile()&gt; to add or replace a section of the output file with a new one generated from the parsed file.
#
#       Implement &lt;BuildIndex()&gt; to add or replace an index in the output file with a new one generated from the specified index.
#
#       Implement &lt;EndBuild()&gt; so that if the project changed, it saves the output file to disk.
#
#       How you handle the menu depends on how the output file references other sections of itself.  If it can do so by name, then
#       you can implement &lt;UpdateMenu()&gt; to update the menu section of the file and you're done.  If it has to reference itself
#       by address or offset, it gets trickier.  You should skip &lt;UpdateMenu()&gt; and instead rebuild the menu in &lt;EndBuild()&gt; if
#       the parameter is true.  This lets you do it whenever anything changes in a file, rather than just when the menu
#       visibly changes.  How you keep track of the locations and how they change is your problem.
#


###############################################################################
#
#   Group: Required Interface Functions
#
#   All Builder classes *must* define these functions.
#


#
#   Function: INIT
#
#   Define this function to call &lt;NaturalDocs::Builder-&gt;Add()&gt; so that &lt;NaturalDocs::Builder&gt; knows about this package.
#   Packages are defined this way so that new ones can be added without messing around in other code.
#


#
#   Function: CommandLineOption
#
#   Define this function to return the text that should be put in the command line after -o to use this package.  It cannot have
#   spaces and is not case sensitive.
#
#   For example, &lt;NaturalDocs::Builder::HTML&gt; returns 'html' so someone could use -o html [directory] to use that package.
#
sub CommandLineOption
    {
    NaturalDocs::Error-&gt;SoftDeath($_[0] . " didn't define CommandLineOption().");
    };


#
#   Function: BuildFile
#
#   Define this function to convert a parsed file to this package's output format.  This function will be called once for every source
#   file that needs to be rebuilt.  However, if a file hasn't changed since the last time Natural Docs was run, it will not be sent to
#   this function.  All packages must support differential build.
#
#   Parameters:
#
#       sourceFile  - The name of the source file.
#       parsedFile  - The parsed source file, as an arrayref of &lt;NaturalDocs::Parser::ParsedTopic&gt; objects.
#
sub BuildFile #(sourceFile, parsedFile)
    {
    NaturalDocs::Error-&gt;SoftDeath($_[0] . " didn't define BuildFile().");
    };


###############################################################################
#
#   Group: Optional Interface Functions
#
#   These functions can be implemented but packages are not required to do so.
#


#
#   Function: New
#
#   Creates and returns a new object.
#
#   Note that this is the only function where the first parameter will be the package name, not the object itself.
#
sub New
    {
    my $package = shift;

    my $object = [ ];
    bless $object, $package;

    return $object;
    };


#
#   Function: BeginBuild
#
#   Define this function if the package needs to do anything at the beginning of the build process.  This function will be called
#   every time Natural Docs is run, even if the project hasn't changed.  This allows you to manage dependencies specific
#   to the output format that may change independently from the source tree and menu.  For example,
#   &lt;NaturalDocs::Builder::HTML&gt; needs to keep the CSS files in sync regardless of whether the source tree changed or not.
#
#   Parameters:
#
#       hasChanged - Whether the project has changed, such as source files or the menu file.  If false, nothing else is going to be
#                            called except &lt;EndBuild()&gt;.
#
sub BeginBuild #(hasChanged)
    {
    };


#
#   Function: EndBuild
#
#   Define this function if the package needs to do anything at the end of the build process.  This function will be called every time
#   Natural Docs is run, even if the project hasn't changed.  This allows you to manage dependencies specific to the output
#   format that may change independently from the source tree.  For example, &lt;NaturalDocs::Builder::HTML&gt; needs to keep the
#   CSS files in sync regardless of whether the source tree changed or not.
#
#   Parameters:
#
#       hasChanged - Whether the project has changed, such as source files or the menu file.  If false, the only other function that
#                            was called was &lt;BeginBuild()&gt;.
#
sub EndBuild #(hasChanged)
    {
    };


#
#   Function: BuildIndex
#
#   Define this function to create an index for the passed topic.  You can get the index from
#   &lt;NaturalDocs::SymbolTable-&gt;Index()&gt;.
#
#   The reason it's not passed directly to this function is because indexes may be time-consuming to create.  As such, they're
#   generated on demand because some output packages may choose not to implement them.
#
#   Parameters:
#
#       topic  - The &lt;TopicType&gt; to limit the index by.
#
sub BuildIndex #(topic)
    {
    };


#
#   Function: UpdateImage
#
#   Define this function to add or update the passed image in the output.
#
#   Parameters:
#
#       file - The image &lt;FileName&gt;
#
sub UpdateImage #(file)
    {
    };


#
#   Function: PurgeFiles
#
#   Define this function to make the package remove all output related to the passed files.  These files no longer have Natural Docs
#   content.
#
#   Parameters:
#
#       files - An existence hashref of the files to purge.
#
sub PurgeFiles #(files)
    {
    };


#
#   Function: PurgeIndexes
#
#   Define this function to make the package remove all output related to the passed indexes.  These indexes are no longer part
#   of the menu.
#
#   Parameters:
#
#       indexes  - An existence hashref of the &lt;TopicTypes&gt; of the indexes to purge.
#
sub PurgeIndexes #(indexes)
    {
    };


#
#   Function: PurgeImages
#
#   Define this function to make the package remove all output related to the passed image files.  These files are no longer used
#   by the documentation.
#
#   Parameters:
#
#       files - An existence hashref of the image &lt;FileNames&gt; to purge.
#
sub PurgeImages #(files)
    {
    };


#
#   Function: UpdateMenu
#
#   Define this function to make the package update the menu.  It will only be called if the menu changed.
#
sub UpdateMenu
    {
    };


1;
</pre></body></html>