birdnotes.py: Objects to represent bird note files

This class represents the narrative element in the Relax NG schema. Specifically, it represents either a sequence of text paragraphs as para elements, or the mixed content that is allowed inside a para element—in the latter case, it is effectively a single para without the enclosing element.

Accordingly, the obvious internal representation of a Narrative instance is as a sequence of paragraphs, each represented as a Paragraph instance.

There is one important special case. If there is only one paragraph in the instance, we don't need to wrap its content in a para element.

# - - - - -   c l a s s   N a r r a t i v e

class Narrative:
    """Represents an instance of the narrative pattern.

      Exports:
        Narrative():
          [ return a new, empty Narrative instance ]
        .addPara(p):
          [ p is a Paragraph instance ->
              self  :=  self with p added as its new last paragraph ]
        .__len__(self):
          [ return the number of paragraphs in self ]
        .genParas():
          [ generate the contents of self as a sequence of
            Paragraph instances ]
        .writeNode(parent):
          [ parent is an et.Element ->
              if self's content has only one paragraph ->
                  parent  :=  parent with that content added
              else ->
                  parent  :=  parent with self's content added
                      as a sequence of rnc.PARA_N elements ]
        Narrative.readNode(parent):  # Static method
          [ parent is an et.Element ->
              return a new Narrative instance made from
              narrative children of parent ]

The .readChild() method is useful for extracting Narrative content from an optional child node.

        Narrative.readChild(parent, childName):  # Static method
          [ (parent is an et.Element) and
            (childName is a node name as a string) ->
              if  parent has at least one child named (childName) ->
                return a new Narrative element representing the
                narrative content of that child
              else -> return None ]

      State/Invariants:
        ._paraList:  [ list of component Paragraph instances ]
    """

# - - -   N a r r a t i v e . _ _ i n i t _ _

    def __init__(self):
        """Constructor for Narrative.
        """
        self._paraList = []