regenerate 0.1.1 → 0.2.0

data/lib/regenerate.rb

@@ -1,4 +1,5 @@
-# A framework for static website generation which regenerates files in place.
+# A framework for static website generation which regenerates files in place 
+# (or, if you like, generates them into a different place)
 
 require 'regenerate/web-page.rb'
 require 'regenerate/site-regenerator.rb'

data/lib/regenerate/regenerate-utils.rb

@@ -2,6 +2,8 @@ module Regenerate
   
   module Utils
     
+    # If an old version of an output file exists, rename it to same file with "~" at the end.
+    # If that file (an earlier backup file) exists, delete it first.
     def makeBackupFile(outFile)
       backupFileName = outFile+"~"
       if File.exists? backupFileName
@@ -15,6 +17,8 @@ module Regenerate
       backupFileName
     end
     
+    # Cause a directory to be created if it does not already exist. 
+    # Raise an error if it does not exist and it cannot be created.
     def ensureDirectoryExists(directoryName)
       if File.exist? directoryName
         if not File.directory? directoryName

data/lib/regenerate/site-regenerator.rb

@@ -4,6 +4,7 @@ require 'regenerate/regenerate-utils.rb'
 
 module Regenerate
   
+  # An object to iterate over a directory path and all its parent directories
   class PathAndParents
     def initialize(path)
       @path = path
@@ -21,14 +22,24 @@ module Regenerate
     end
   end
   
+  # The main object representing the static website source and output directories
+  # where generation or regeneration will occur.
+  # There are three types of generation/regeneration, depending on how it is invoked:
+  # 1. Re-generate source file or files in-place
+  # 2. Generate output file or files from source file or files
+  # 3. Re-generate source file or files from output file or files (this is for when output files have been directly edited, 
+  #                                                                and when it is possible to re-generate the source)
   class SiteRegenerator
     
     include Regenerate::Utils
     
-    attr_accessor :checkNoChanges
-    
+    # an option to check for changes and throw an error before an existing output file is changed
+    # (use this option to test that certain changes in your code _don't_ change the result for your website)
+    attr_accessor :checkNoChanges 
+
+    # Initialise giving base directory of project, and sub-directories for source and output
+    # e.g. "/home/me/myproject", "src" and "output"
     def initialize(baseDir, sourceSubDir, outputSubDir)
-      
       @baseDir = File.expand_path(baseDir)
       @sourceSubDir = sourceSubDir
       @outputSubDir = outputSubDir
@@ -40,6 +51,7 @@ module Regenerate
       puts "SiteRegenerator, @baseDir = #{@baseDir.inspect}"
     end
     
+    # files & directories starting with "_" are not output files (they are other helper files)
     def checkNotSourceOnly(pathComponents)
       for component in pathComponents do
         if component.start_with?("_")
@@ -48,13 +60,17 @@ module Regenerate
       end
     end
     
+    # Extensions for types of files to be generated/regenerated
     REGENERATE_EXTENSIONS = [".htm", ".html", ".xml"]
     
+    # Copy a source file directly to an output file
     def copySrcToOutputFile(srcFile, outFile)
       makeBackupFile(outFile)
       FileUtils.cp(srcFile, outFile, :verbose => true)
     end
     
+    # Generate an output file from a source file
+    # (pathComponents represent the path from the root source directory to the actual file)
     def regenerateFileFromSource(srcFile, pathComponents)
       puts "regenerateFileFromSource, srcFile = #{srcFile}, pathComponents = #{pathComponents.inspect}"
       subPath = pathComponents.join("/")
@@ -70,6 +86,7 @@ module Regenerate
       end
     end
     
+    # Generate a source file from an output file (if that can be done)
     def regenerateSourceFromOutput(outFile, pathComponents)
       puts "regenerateSourceFromOutput, outFile = #{outFile}, pathComponents = #{pathComponents.inspect}"
       subPath = pathComponents.join("/")
@@ -85,6 +102,7 @@ module Regenerate
       end
     end
     
+    # Regenerate (or generate) a file, either from source file or from output file
     def regenerateFile(srcFile, pathComponents, sourceType)
       puts "regenerateFile, srcFile = #{srcFile}, sourceType = #{sourceType.inspect}"
       outFile = File.join(@sourceTypeDirs[@oppositeSourceType[sourceType]], File.join(pathComponents))
@@ -103,6 +121,8 @@ module Regenerate
       end
     end
     
+    # Regenerate (or generated) specified sub-directory or file in sub-directory
+    # of source or output root directory (according to sourceType)
     def regenerateSubPath(pathComponents, sourceType)
       puts "regenerateSubPath, pathComponents = #{pathComponents.inspect}, sourceType = #{sourceType.inspect}"
       srcPath = File.join(@sourceTypeDirs[sourceType], File.join(pathComponents))
@@ -120,6 +140,8 @@ module Regenerate
       end
     end
     
+    # Regenerate (or generate) from specified source file (according to whether the path is within
+    # the source or output root directory).
     def regeneratePath(path)
       path = File.expand_path(path)
       puts "SiteRegenerator.regeneratePath, path = #{path}"
@@ -141,6 +163,7 @@ module Regenerate
     
   end
   
+  # Searching upwards from the current directory, find a file ".regenerate.rb" in the root directory of the project
   def self.findRegenerateScript(path, fileName)
     for dir in PathAndParents.new(path) do
       scriptFileName = File.join(dir, fileName)
@@ -152,6 +175,11 @@ module Regenerate
     raise "File #{fileName} not found in #{path} or any or its parent directories"
   end
   
+  # Run the ".regenerate.rb" script that is in the root directory of the project
+  # (Note: .regenerate.rb is responsible for requiring Ruby scripts that define Ruby classes specific to the project, 
+  #  for creating a SiteRegenerator instance, and for invoking the regeneratePath method
+  #  on a file or directory name that has been set as the value of the "path" variable in the binding within which
+  #  .regenerate.rb is being evaluated.)
   def self.regeneratePath(path)
     regenerateScriptFileName = findRegenerateScript(path, ".regenerate.rb")
     regenerateScript = File.read(regenerateScriptFileName)

data/lib/regenerate/web-page.rb

@@ -5,74 +5,93 @@ require 'regenerate/regenerate-utils.rb'
 
 module Regenerate
   
-  # A component, which includes a sequence of lines which make up the text of that component
+  # The textual format for "regeneratable" files is HTML (or XML) with special comment lines that mark the beginnings
+  # and ends of particular "page components". Such components may include actual HTML (or XML) in which case there 
+  # are special start & end comment lines, or, they may consist entirely of one multi-line comment.
+  
+  # Base class for page components, defined by a sequence of lines in an HTML file which make up the text of that component
   class PageComponent
     attr_reader :text
     attr_accessor :parentPage
     
     def initialize
-      @lines = []
+      @lines = [] # No lines of text yet
       @text = nil # if text is nil, component is not yet finished
-      @parentPage = nil
+      @parentPage = nil # A link to the parent WebPage object, will get set from a method on that object
     end
     
     def processStartComment(parsedCommentLine)
-      @startName = parsedCommentLine.name
-      initializeFromStartComment(parsedCommentLine)
+      @startName = parsedCommentLine.name # remember the name in the start command, 
+                                          # because it has to match the name in the end command
+      initializeFromStartComment(parsedCommentLine) # do whatever has to be done to initialise this page component
       if parsedCommentLine.sectionEnd # section end in start comment line, so already finished
-        finishText
+        finishText # i.e. there will be no more text lines added to this component
       end
     end
     
     def processEndComment(parsedCommentLine)
-      finishText
-      if parsedCommentLine.name != @startName
+      finishText # there will be no more text lines added to this component
+      if parsedCommentLine.name != @startName # check match of name in end comment with name in start comment
         raise ParseException.new("Name #{parsedCommentLine.name.inspect} in end comment doesn't match name #{@startName.inspect} in start comment.")
       end
     end
-    
+
+    # Do whatever needs to be done to initialise this page component from the start command
     def initializeFromStartComment(parsedCommentLine)
-      # default do nothing
+      # default do nothing - over-ride this method in derived classes
     end
     
+    # Has this component finished
     def finished
-      @text != nil
+      @text != nil # finishText sets the value of @text, so use that as a test for "is it finished?"
     end
     
+    # Add a text line, by adding it to @lines
     def addLine(line)
       @lines << line
     end
     
+    # Do whatever needs to be done to the parent WebPage object for this page component
     def addToParentPage
-      # default do nothing
+      # default do nothing - over-ride this in derived classes
     end
     
+    # After all text lines have been added, join them together and put into @text
     def finishText
       @text = @lines.join("\n")
-      addToParentPage
+      addToParentPage # do whatever needs to be done to the parent WebPage object for this page component
     end
   end
   
-  # A component of static text which is not assigned to any variable, and which does not change
+  # A page component of static text which is not assigned to any variable, and which does not change when re-generated.
+  # Any sequence of line _not_ marked by special start and end lines will constitute static HTML.
   class StaticHtml < PageComponent
+    
+    # output the text as is (but with an extra eoln)
     def output(showSource = true)
       text + "\n"
     end
     
+    # varName is nil because no instance variable is associated with a static HTML page component
     def varName
       nil
     end
   end
   
-  class RubyCode<PageComponent
+  # A page component consisting of Ruby code which is to be evaluated in the context of the object that defines the page
+  # Defined by start line "<!-- [ruby" and end line "ruby] -->".
+  class RubyCode < PageComponent
     
+    # The line number, which matters for code evaluation so that Ruby can populate stack traces correctly
     attr_reader :lineNumber
     
+    # Initialise this page component, additionally initialising the line number
     def initialize(lineNumber)
       super()
       @lineNumber = lineNumber
     end
     
+    # Output this page component in a form that would be reparsed back into the same page component
     def output(showSource = true)
       if showSource
         "<!-- [ruby\n#{text}\nruby] -->\n"
@@ -81,18 +100,27 @@ module Regenerate
       end
     end
     
+    # Add to parent page, which requires adding to the page's list of Ruby page components (which will all
+    # get executed at some later stage)
     def addToParentPage
       @parentPage.addRubyComponent(self)
     end
   end
-  
-  class SetPageObjectClass<PageComponent
-    attr_reader :className
+
+  # A page component consisting of a single line which specifies the Ruby class which represents this page
+  # In the format "<!-- [class <classname>] -->" where <classname> is the name of a Ruby class.
+  # The Ruby class should generally have Regenerate::PageObject as a base class.
+  class SetPageObjectClass < PageComponent
+    
+    attr_reader :className # The name of the Ruby class of the page object
+    
+    # Initialise this page component, additionally initialising the class name    
     def initialize(className)
       super()
       @className = className
     end
     
+    # Output this page component in a form that would be reparsed back into the same page component
     def output(showSource = true)
       if showSource
         "<!-- [class #{@className}] -->\n"
@@ -102,31 +130,39 @@ module Regenerate
     end
     
     def addToParentPage
+      # Add to parent page, which creates a new page object of the specified class (replacing the default PageObject object)
       @parentPage.setPageObject(@className)
     end
   end
   
-  # Base class for the text variable types
+  # Base class for a page component defining a block of text (which may or may not be inside a comment)
+  # which is assigned to an instance variable of the object representing the page. (The text value for
+  # this instance variable may be both read and written by the Ruby code that runs in the context of the object.)
   class TextVariable<PageComponent
-    attr_reader :varName
+    attr_reader :varName # the name of the instance variable of the page object that will hold this value
     
+    # initialise, which sets the instance variable name
     def initializeFromStartComment(parsedCommentLine)
       @varName = parsedCommentLine.instanceVarName
     end
     
+    # add to parent WebPage by adding the specified instance variable to the page object
     def addToParentPage
       #puts "TextVariable.addToParentPage #{@varName} = #{@text.inspect}"
       @parentPage.setPageObjectInstanceVar(@varName, @text)
     end
     
+    # Get the textual value of the page object instance variable
     def textVariableValue
       @parentPage.getPageObjectInstanceVar(@varName)
     end
   end
   
-  # HtmlVariable Can be both source and result
+  # A page component for a block of HTML which is assigned to an instance variable of the page object
   class HtmlVariable < TextVariable
     
+    # Process the end command by finishing the page component definition, also check that the closing
+    # command has the correct form (must be a self-contained HTML comment line)
     def processEndComment(parsedCommentLine)
       super(parsedCommentLine)
       if !parsedCommentLine.hasCommentStart
@@ -134,6 +170,8 @@ module Regenerate
       end
     end
     
+    # Output in a form that would be reparsed as the same page component, but with whatever the current
+    # textual value of the associate page object instance variable is.
     def output(showSource = true)
       if showSource
         textValue = textVariableValue
@@ -148,8 +186,11 @@ module Regenerate
     end
   end
   
-  # CommentVariable Is an input only
+  # A page component for text inside an HTML comment which is assigned to an instance variable of the page object
   class CommentVariable < TextVariable
+    
+    # Process the end command by finishing the page component definition, also check that the closing
+    # command has the correct form (must be a line that ends an existing HTML comment)
     def processEndComment(parsedCommentLine)
       super(parsedCommentLine)
       if parsedCommentLine.hasCommentStart
@@ -157,6 +198,8 @@ module Regenerate
       end
     end
     
+    # Output in a form that would be reparsed as the same page component, but with whatever the current
+    # textual value of the associate page object instance variable is.
     def output(showSource = true)
       if showSource
         "<!-- [#{@varName}\n#{textVariableValue}\n#{@varName}] -->\n"
@@ -166,15 +209,51 @@ module Regenerate
     end
   end
   
-  COMMENT_LINE_REGEX = /^\s*(<!--\s*|)(\[|)((@|)[_a-zA-Z][_a-zA-Z0-9]*)(|\s+([_a-zA-Z0-9]*))(\]|)(\s*-->|)?\s*$/
+  # Regex that matches Regenerate comment line, with following components:
+  # * Optional whitespace
+  # * Possible ("<!--" + optional whitespace)
+  # * Possible "["
+  # * Possible Ruby identifier (alphanumeric or underscore with initial non-numeric) with optional "@" prefix
+  # * Possible (whitespace + alphanumeric/underscore value)
+  # * Possible "]"
+  # * Possible (optional whitespace + "-->")
+  # * Optional whitespace
+  COMMENT_LINE_REGEX = /^\s*(<!--\s*|)(\[|)((@|)[_a-zA-Z][_a-zA-Z0-9]*)(|\s+([_a-zA-Z0-9]+))(\]|)(\s*-->|)?\s*$/
   
-  class ParseException<Exception
+  # Any error that occurs when parsing a source file
+  class ParseException < Exception
   end
   
+  # Regenerate delimits page components ("sections") using special HTML comments. 
+  # The comment lines may - 1. start a comment, 2. end a comment, 
+  # 3. be a self-contained comment line (in which case the self-contained comment may a) start  or b) end a page component, 
+  #   or c) be a page component in itself.
+  # The components of a Regenerate comment line are defined by the regex COMMENT_LINE_REGEX, and 
+  # are identified as follows:
+  # * "<!--" Comment start
+  # * "[" Section start
+  # * Ruby instance variable name (identifier starting with "@"), or, 
+  #     a special section name (currently must be one of "ruby" or "class")
+  # * "]" Section end
+  # * "-->" Comment end
+  # To be identified as a Regenerate comment line, a line must contain at least one of a
+  # comment start and a comment end, and at least one of a section start and a section end.
+  
+  # An object which matches the regex used to identify Regenerate comment line commands
+  # (Note, however, a parsed line may match the regex, but if it doesn't have at least one of a comment
+  # start or a comment end and at least one of a section start or a section end, it will be assumed
+  # that it is a line which was not intended to be parsed as a Regenerate command.)
   class ParsedRegenerateCommentLine
     
-    attr_reader :isInstanceVar, :hasCommentStart, :hasCommentEnd, :sectionStart, :sectionEnd
-    attr_reader :isEmptySection, :line, :name, :value
+    attr_reader :line             # The full text line matched against
+    attr_reader :isInstanceVar    # Is there an associated page object instance variable?
+    attr_reader :hasCommentStart  # Does this command include the start of an HTML comment?
+    attr_reader :hasCommentEnd    # Does this command include the end of an HTML comment?
+    attr_reader :sectionStart     # Does this command include a section start indicator, i.e. "[" ?
+    attr_reader :sectionEnd       # Does this command include a section start indicator, i.e. "]" ?
+    attr_reader :isEmptySection   # Does this represent an empty section, because it starts and ends the same section?
+    attr_reader :name             # The instance variable name (@something) or special command name ("ruby" or "class")
+    attr_reader :value            # The optional value associated with a special command
     
     def initialize(line, match)
       @hasCommentStart = match[1] != ""
@@ -188,40 +267,51 @@ module Regenerate
       @isEmptySection = @sectionStart && @sectionEnd
     end
     
+    # Reconstruct a line which would re-parse the same (but possibly with reduced whitespace)
     def to_s
       "#{@hasCommentStart ? "<!-- ":""}#{@sectionStart ? "[ ":""}#{@isInstanceVar ? "@ ":""}#{@name.inspect}#{@value ? " "+@value:""}#{@sectionEnd ? " ]":""}#{@hasCommentEnd ? " -->":""}"
     end
     
-    def isRejennerCommentLine
+    # Is this line recognised as a Regenerate comment line command?
+    def isRegenerateCommentLine
       return (@hasCommentStart || @hasCommentEnd) && (@sectionStart || @sectionEnd)
     end
     
+    # Does this command start a Ruby page component (because it has special command name "ruby")?
     def isRuby
       !@isInstanceVar && @name == "ruby"
     end
     
+    # The name of the associated instance variable (assuming there is one)
     def instanceVarName
       return @name
     end
     
+    # Raise a parse exception due to an error within this command line
     def raiseParseException(message)
       raise ParseException.new("Error parsing line #{@line.inspect}: #{message}")
     end
     
-    # only call this method if isRejennerCommentLine returns true
+    # only call this method if isRegenerateCommentLine returns true - in other words, if it looks like
+    # it was intended to be a Regenerate comment line command, check that it is valid.
     def checkIsValid
+      # The "name" value has to be an instance variable name or "ruby" or "class"
       if !@isInstanceVar and !["ruby", "class"].include?(@name)
         raiseParseException("Unknown section name #{@name.inspect}")
       end
+      # An empty section has to be a self-contained comment line
       if @isEmptySection and (!@hasCommentStart && !@hasCommentEnd)
         raiseParseException("Empty section, but is not a closed comment")
       end
+      # If it's not a section start, it has to be a section end, so there has to be a comment end
       if !@sectionStart && !@hasCommentEnd
         raiseParseException("End of section in comment start")
       end
+      # If it's not a section end, it has to be a section start, so there has to be a comment start
       if !@sectionEnd && !@hasCommentStart
         raiseParseException("Start of section in comment end")
       end
+      # Empty Ruby page components aren't allowed.
       if (@sectionStart && @sectionEnd) && isRuby
         raiseParseException("Empty ruby section")
       end
@@ -229,14 +319,17 @@ module Regenerate
     
   end
   
-  class UnexpectedChangeError<Exception
+  # When running with "checkNoChanges" flag, raise this error if a change is observed
+  class UnexpectedChangeError < Exception
   end
-  
+
+  # A web page which is read from a source file and regenerated to an output file (which
+  # may be the same as the source file)
   class WebPage
     
     include Regenerate::Utils
     
-    attr_reader :fileName
+    attr_reader :fileName # The absolute name of the source file
     
     def initialize(fileName)
       @fileName = fileName
@@ -244,10 +337,22 @@ module Regenerate
       @currentComponent = nil
       @componentInstanceVariables = {}
       initializePageObject(PageObject.new)  # default, can be overridden by SetPageObjectClass
+      @pageObjectClassNameSpecified = nil # remember name if we have specified a page object class to override the default
       @rubyComponents = []
       readFileLines
     end
-    
+
+    # initialise the "page object", which is the object that "owns" the defined instance variables, 
+    # and the object in whose context the Ruby components are evaluated
+    # Three special instance variable values are set - @fileName, @baseDir, @baseFileName, 
+    # so that they can be accessed, if necessary, by Ruby code in the Ruby code components.
+    # (if this is called a second time, it overrides whatever was set the first time)
+    # Notes on special instance variables -
+    #  @fileName and @baseDir are the absolute paths of the source file and it's containing directory.
+    #  They would be used in Ruby code that looked for other files with names or locations relative to these two.
+    #  They would generally not be expected to appear in the output content.
+    #  @baseFileName is the name of the file without any directory path components. In some cases it might be 
+    #  used within output content.
     def initializePageObject(pageObject)
       @pageObject = pageObject
       setPageObjectInstanceVar("@fileName", @fileName)
@@ -256,32 +361,26 @@ module Regenerate
       @initialInstanceVariables = Set.new(@pageObject.instance_variables)
     end
     
+    # Get the value of an instance variable of the page object
     def getPageObjectInstanceVar(varName)
       @pageObject.instance_variable_get(varName)
     end
     
+    # Set the value of an instance variable of the page object
     def setPageObjectInstanceVar(varName, value)
       puts " setPageObjectInstanceVar, #{varName} = #{value.inspect}"
       @pageObject.instance_variable_set(varName, value)
     end
     
+    # Add a Ruby page component to this web page (so that later on it will be executed)
     def addRubyComponent(rubyComponent)
       @rubyComponents << rubyComponent
     end
     
-    def setInstanceVarValue(varName, value)
-      if @initialInstanceVariables.member? varName
-        raise Exception, "Instance variable #{varName} is a pre-existing instance variable"
-      end
-      if @componentInstanceVariables.member? varName
-        raise Exception, "Instance variable #{varName} is a already defined for a component"
-      end
-      instance_variable_set(varName, value)
-      componentInstanceVariables << varName
-    end
-    
+    # Add a newly started page component to this page
+    # Also process the start comment, unless it was a static HTML component, in which case there is 
+    # not start comment.
     def startNewComponent(component, startComment = nil)
-      
       component.parentPage = self
       @currentComponent = component
       #puts "startNewComponent, @currentComponent = #{@currentComponent.inspect}"
@@ -291,6 +390,8 @@ module Regenerate
       end
     end
     
+    # Process a text line, by adding to the current page component, or if there is none, starting a new
+    # StaticHtml component.
     def processTextLine(line, lineNumber)
       #puts "text: #{line}"
       if @currentComponent == nil
@@ -299,56 +400,67 @@ module Regenerate
       @currentComponent.addLine(line)
     end
     
+    # Get a Ruby class from a normal Ruby class name formatted using "::" separators
     def classFromString(str)
+      # Start with Object, and look up the module one path component at a time
       str.split('::').inject(Object) do |mod, class_name|
         mod.const_get(class_name)
       end
     end
     
+    # Set the page object to be an object with the specified class name (this can only be done once)
     def setPageObject(className)
+      if @pageObjectClassNameSpecified
+        raise ParseException("Page object class name specified more than once")
+      end
+      @pageObjectClassNameSpecified = className
       pageObjectClass = classFromString(className)
       initializePageObject(pageObjectClass.new)
     end
     
+    # Process a line of source text that has been identified as a Regenerate start and/or end of comment line
     def processCommandLine(parsedCommandLine, lineNumber)
       #puts "command: #{parsedCommandLine}"
-      if @currentComponent && (@currentComponent.is_a? StaticHtml)
+      if @currentComponent && (@currentComponent.is_a? StaticHtml) # finish any current static HTML component
         @currentComponent.finishText
         @currentComponent = nil
       end
-      if @currentComponent
-        if parsedCommandLine.sectionStart
+      if @currentComponent # we are in a page component other than a static HTML component
+        if parsedCommandLine.sectionStart # we have already started, so we cannot start again
           raise ParseException.new("Unexpected section start #{parsedCommandLine} inside component")
         end
-        @currentComponent.processEndComment(parsedCommandLine)
+        @currentComponent.processEndComment(parsedCommandLine) # so, command must be a command to end the page component
         @currentComponent = nil
-      else
-        if !parsedCommandLine.sectionStart
+      else # not in any page component, so we need to start a new one
+        if !parsedCommandLine.sectionStart # if it's an end command, error, because there is nothing to end
           raise ParseException.new("Unexpected section end #{parsedCommandLine}, outside of component")
         end
-        if parsedCommandLine.isInstanceVar
-          if parsedCommandLine.hasCommentEnd
+        if parsedCommandLine.isInstanceVar # it's a page component that defines an instance variable value
+          if parsedCommandLine.hasCommentEnd # the value will be an HTML value
             startNewComponent(HtmlVariable.new, parsedCommandLine)
-          else
+          else # the value will be an HTML-commented value
             startNewComponent(CommentVariable.new, parsedCommandLine)
           end
-        else
-          if parsedCommandLine.name == "ruby"
+        else # not an instance var, so it must be a special command
+          if parsedCommandLine.name == "ruby" # Ruby page component containing Ruby that will be executed in the 
+                                              # context of the page object
             startNewComponent(RubyCode.new(lineNumber+1), parsedCommandLine)
-          elsif parsedCommandLine.name == "class"
+          elsif parsedCommandLine.name == "class" # Specify Ruby class for the page object
             startNewComponent(SetPageObjectClass.new(parsedCommandLine.value), parsedCommandLine)
-          else
+          else # not a known special command
             raise ParseException.new("Unknown section type #{parsedCommandLine.name.inspect}")
           end
         end
-        if @currentComponent.finished
-          @currentComponent = nil
+        if @currentComponent.finished # Did the processing cause the current page component to be finished?
+          @currentComponent = nil # clear the current component
         end
       end
       
     end
     
-    def finish
+    # Finish the current page component after we are at the end of the source file
+    # Anything other than static HTML should be explicitly finished, and if it isn't finished, raise an error.
+    def finishAtEndOfSourceFile
       if @currentComponent
         if @currentComponent.is_a? StaticHtml
           @currentComponent.finishText
@@ -359,6 +471,7 @@ module Regenerate
       end
     end
     
+    # Report the difference between two strings (that should be the same)
     def diffReport(newString, oldString)
       i = 0
       minLength = [newString.length, oldString.length].min
@@ -372,7 +485,10 @@ module Regenerate
       "Different from position #{diffPos}: \n  #{newString[startPos...newStringEndPos].inspect}\n !=\n  #{oldString[startPos...newStringEndPos].inspect}"
     end
     
-    def checkOutputFileUnchanged(outFile, oldFile)
+    # Check that a newly created output file has the same contents as another (backup) file containing the old contents
+    # If it has changed, actually reset the new file to have ".new" at the end of its name, 
+    # and rename the backup file to be the output file (in effect reverting the newly written output).
+    def checkAndEnsureOutputFileUnchanged(outFile, oldFile)
       if File.exists? oldFile
         oldFileContents = File.read(oldFile)
         newFileContents = File.read(outFile)
@@ -388,6 +504,8 @@ module Regenerate
       end
     end
     
+    # Write the output of the page components to the output file (optionally checking that 
+    # there are no differences between the new output and the existing output.
     def writeRegeneratedFile(outFile, checkNoChanges)
       backupFileName = makeBackupFile(outFile)
       puts "Outputting regenerated page to #{outFile} ..."
@@ -398,46 +516,51 @@ module Regenerate
       end
       puts "Finished writing #{outFile}"
       if checkNoChanges
-        checkOutputFileUnchanged(outFile, backupFileName)
+        checkAndEnsureOutputFileUnchanged(outFile, backupFileName)
       end
     end
     
+    # Read in and parse lines from source file
     def readFileLines
       puts "Opening #{@fileName} ..."
       lineNumber = 0
       File.open(@fileName).each_line do |line|
         line.chomp!
-        lineNumber += 1
+        lineNumber += 1 # track line numbers for when Ruby code needs to be executed (i.e. to populate stack traces)
         #puts "line #{lineNumber}: #{line}"
         commentLineMatch = COMMENT_LINE_REGEX.match(line)
-        if commentLineMatch
+        if commentLineMatch # it matches the Regenerate command line regex (but might not actually be a command ...)
           parsedCommandLine = ParsedRegenerateCommentLine.new(line, commentLineMatch)
           #puts "parsedCommandLine = #{parsedCommandLine}"
-          if parsedCommandLine.isRejennerCommentLine
-            parsedCommandLine.checkIsValid
-            processCommandLine(parsedCommandLine, lineNumber)
+          if parsedCommandLine.isRegenerateCommentLine # if it is a Regenerate command line
+            parsedCommandLine.checkIsValid # check it is valid, and then, 
+            processCommandLine(parsedCommandLine, lineNumber) # process the command line
           else
-            processTextLine(line, lineNumber)
+            processTextLine(line, lineNumber) # process a text line which is not a Regenerate command line
           end
         else
-          processTextLine(line, lineNumber)
+          processTextLine(line, lineNumber) # process a text line which is not a Regenerate command line
         end
       end
-      finish
+      # After processing all source lines, the only unfinished page component permitted is a static HTML component.
+      finishAtEndOfSourceFile
       #puts "Finished reading #{@fileName}."
     end
     
+    # Regenerate the source file (in-place)
     def regenerate
       executeRubyComponents
       writeRegeneratedFile(@fileName)
       #display
     end
     
+    # Regenerate from the source file into the output file
     def regenerateToOutputFile(outFile, checkNoChanges = false)
       executeRubyComponents
       writeRegeneratedFile(outFile, checkNoChanges)
     end
     
+    # Execute the Ruby components which consist of Ruby code to be evaluated in the context of the page object
     def executeRubyComponents
       fileDir = File.dirname(@fileName)
       puts "Executing ruby components in directory #{fileDir} ..."
@@ -462,10 +585,14 @@ module Regenerate
       end
     end
   end
-  
+
+  # The Ruby object contained within a web page. Instance variables defined in the HTML
+  # belong to this object, and Ruby code defined in the page is executed in the context of this object.
+  # This class is the base class for classes that define particular types of web pages
   class PageObject
     include Regenerate::Utils
     
+    # Method to render an ERB template file in the context of this object
     def erb(templateFileName)
       @binding = binding
       File.open(relative_path(templateFileName), "r") do |input|
@@ -475,22 +602,32 @@ module Regenerate
         result = template.result(@binding)
       end
     end
-    
+
+    # Method to render an ERB template (defined in-line) in the context of this object
     def erbFromString(templateString)
       @binding = binding
       template = ERB.new(templateString, nil, nil)
       template.result(@binding)
     end
-      
     
+    # Calculate absolute path given path relative to the directory containing the source file for the web page
     def relative_path(path)
       File.expand_path(File.join(@baseDir, path.to_str))
     end
 
+    # Require a Ruby file given a path relative to the web page source file.
     def require_relative(path)
       require relative_path(path)
     end
-    
+
+    # Save some of the page object's instance variable values to a file as JSON
+    # This method depends on the following defined in the actual page object class:
+    # * propertiesToSave instance method, to return an array of symbols
+    # * propertiesFileName class method, to return name of properties file as a function of the web page source file name
+    #  (propertiesFileName is a class method, because it needs to be invoked by other code that _reads_ the properties
+    #   file when the page object itself does not exist)
+    # Example of useage: an index file for a blog needs to read properties of each blog page, 
+    # where the blog page objects have saved their details into the individual property files.
     def saveProperties
       properties = {}
       for property in propertiesToSave

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: regenerate
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-10 00:00:00.000000000 Z
+date: 2013-06-11 00:00:00.000000000 Z
 dependencies: []
 description: Use to regenerate to write a web page with embedded instance variable
   definitions and embedded ruby code which executes to regenerate the same web page