Next / Previous / Contents / Shipman's homepage

4.8. processDoc(): Process one document tree

Given a document tree, this function finds all the literate program elements, attempts to open output files for them if they are not already open, and writes the code fragments to those files.

# - - -   p r o c e s s  D o c

def processDoc(fileMap, doc):
    '''Process one document tree

      [ (fileMap is a dictionary whose keys are file names and
        each corresponding value is a writeable file handle
        for that file) and
        (doc is an et.ElementTree) ->
          fileMap  :=  fileMap with new output files added from
              lit-elts in doc whose lit-dests can be opened anew
          files named in fileMap  :=  lit-content of those files
          sys.stderr  +:=  error messages for lit-dests that
              cannot be opened for output, if any ]

To find the root element of doc, we use its ElementTree.getroot() method. Then we use the Element.findall() method to locate all the programlisting elements anywhere in the tree.

The xml.ElementTree.etree package uses a vaguely XPath-like syntax, not a full XPath implementation. Here, “.” indicates a path relative to the root, “//” means what it means in XPath: any descendant. It returns a list of matching elements. See Section 4.4.4, “PROG_ELT.

    #-- 1
    # [ eltList  :=  a list of all the PROG_ELT elements in doc,
    #                in document order ]
    root = doc.getroot()
    eltList = root.findall(".//" + PROG_ELT)

For each potentially literate element, we look to see if it has a ROLE_ATTR attribute, and if so, whether that attribute's value starts with ROLE_PREFIX. If so, it is a literate element, and is sent for processing to Section 4.9, “processElt(): Process one literate element”.

    #-- 2
    # [ fileMap  :=  fileMap with new file names added from lit-dests
    #                in eltList whose lit-dest files could be opened
    #   files named in fileMap  :=  lit-content of those files
    #   sys.stderr  +:=  error messages from failures to open
    #       those files, if any ]
    for elt in eltList:
        #-- 2 body
        # [ if elt is not a lit-elt ->
        #     I
        #   else if lit-dest(elt) is a key in fileMap ->
        #     fileMap[lit-dest(elt)]  +:=  lit-content(elt)
        #   else if a new file named lit-dest(elt) can be opened
        #   for writing ->
        #     fileMap[lit-dest(elt)]  :=  that new file
        #     that new file  :=  lit-content(elt)
        #   else ->
        #     sys.stderr  +:=  error message
        #     return ]

These conditions must be met for a literate element.

See Section 4.9, “processElt(): Process one literate element”.

            attrValue = elt.attrib[ROLE_ATTR]
            if  attrValue.startswith(ROLE_PREFIX):
                outName = attrValue[len(ROLE_PREFIX):]
                processElt(fileMap, outName, elt)
        except KeyError: