A source extractor for lightweight literate programming

The SAX interface requires that the content handler class define a method named .startElement() to observe start tags.

# - - -   A r t i c l e H a n d l e r . s t a r t E l e m e n t   - - -

    def startElement ( self, name, attrs ):
        """Handle a start tag.

          [ (name is the element name) and
            (attrs is a dictionary containing the attribute names |->
            attribute values) ->
              if this tag starts a fragment ->
                self.outFileName  :=  the fragment's file name
                self.outFile      :=  the fragment's output file
                self.fileMap      :=  self.fileMap with an entry
                    mapping the fragment's file name |-> the
                    fragment's output file
              else -> I ]
        """

If this start tag isn't a programlisting element, or it doesn't have a role attribute, we don't care about it. Otherwise, we save the role attribute the variable role.

        #-- 1 --
        if  name != PROG_ELT:
            return

        #-- 2 --
        # [ if attrs has a key ROLE_ATTR ->
        #     role  :=  that attribute's value
        #   else -> return ]
        try:
            role  =  attrs [ ROLE_ATTR ]
        except KeyError:
            return

If the role attribute starts with outFile:, we store the rest in self.outFileName, signifying that we are now inside a code fragment. If it's not one of our role attributes, we return to the caller.

        #-- 3 --
        # [ if role starts with ROLE_PREFIX ->
        #     self.outFileName  :=  the rest of role
        #   else -> return ]
        if  role.startswith ( ROLE_PREFIX ):
            self.outFileName  =  role [ len ( ROLE_PREFIX ) : ]
        else:
            return

Next we need an output file handle so that the .characters() method will know where to write the code content. If the self.fileMap dictionary already has an output file handle in it for this file name, we use that, saving it in self.outFile. Otherwise, we open it now and save the file handle in self.outFile and also in the self.fileMap. Failure to open the output file is a fatal error.

        #-- 4 --
        # [ if self.fileMap has no key self.outFileName ->
        #     self.fileMap  :=  self.fileMap with an entry mapping
        #         self.outFileName |-> a writeable file handle for
        #             self.outFileName
        #     self.outfile  :=  that same file handle
        #   else ->
        #     self.outFile  :=  the corresponding value from
        #                       self.fileMap ]
        try:
            self.outFile  =  self.fileMap [ self.outFileName ]
        except KeyError:
            try:
                self.outFile  =  open ( self.outFileName, "w" )
                self.fileMap[self.outFileName]  =  self.outFile
            except IOError, detail:
                print >> sys.stderr, ( "*** Can't open file "
                    "'%s' for writing." % self.outFileName )
                sys.exit(1)