birdnotes.py: Objects to represent bird note files

The given parent node must be one that has narrative content in the RNC schema. This static method turns that content into a Narrative instance. For the constructor, see Section 18.1, “Narrative.__init__(): Constructor”.

# - - -   N a r r a t i v e . r e a d N o d e

    @staticmethod
    def readNode(parent):
        """Create a Narrative instance from XML narrative content.
        """

        #-- 1 --
        # [ result  :=  a new, empty Narrative instance ]
        result = Narrative()

Our first task is to distinguish between the two cases of the narrative pattern: is it a sequence of para elements, or the para-content pattern (which is effectively a para without the wrapper)?

If parent has no child elements, then clearly it is the para-content case. Otherwise, we look at the first child: if it is not para, again it is the para-content case. See Paragraph-readNode.

        #-- 2 --
        # [ if (parent has no element children) or
        #   (parent's first element child is not rnc.PARA_N) ->
        #     result  :=  result with one Paragraph instance added
        #                 containing para-content from parent
        #   else ->
        #     result  :=  result with Paragraph instances added,
        #         made from the rnc.PARA_N children of parent ]
        if (( len(parent) == 0) or
             (parent[0].tag != rnc.PARA_N)):
            #-- 2.1 --
            # [ result  :=  result with one Paragraph instance added
            #               containing para-content from parent ]
            paragraph = Paragraph.readNode(parent)
            result.addPara(paragraph)
        else:
            #-- 2.2 --
            # [ parent's element children are all rnc.PARA_N ->
            #     result  :=  result with Paragraph instances added,
            #         made from those children ]
            for  child in parent:
                paragraph = Paragraph.readNode(child)
                result.addPara(paragraph)

The code above assumes that the input XML has been validated against the schema. It also assumes that if the first element child of the parent is para, then all the elements are. This saves a lot of error-checking.

        #-- 3 --
        return result