nomcompile3: Build a set of nomenclature files

# - - -   T a x a T r e e . r a n k P a r e n t

    def rankParent ( self, newRankCode ):
        '''Find the parent of a new taxon of a given rank code.
        '''

For the related verification function, see Section 7.9, “rank-parent: What taxon is the parent of a new taxon of a given rank?”.

First we dispense with the trivial case where the tree is empty. If the tree isn't empty, we set local variable node to the root.

        #-- 1 --
        # [ rankCode is a code in self.hier ->
        #     if self.root is None ->
        #       raise ValueError
        #     else ->
        #       node  :=  self.root
        #       newRank  :=  Rank instance from self.hier with
        #                    code newRankCode ]
        if self.root is None:
            raise ValueError ( "No taxon can be added because the "
                "tree is empty." )
        node = self.root
        newRank = self.hier.lookupRankCode ( newRankCode )

Next we walk down the tree, visiting the last child of each node, until we reach a node that either has no children, or it has a child at the new rank's level (or lower, which is an error condition that will be caught elsewhere). We can index a Taxon as if it were a sequence of its children, so the last child is index [-1]; see Section 19.3, “Taxon.__getitem__(): Return the (n)th child”. Also, Rank instances are ordered by increasing depth; see Section 16.1, “Rank.__cmp__()”.

        #-- 2 --
        # [ node is a Taxon with rank < newRank ->
        #     node  :=  last node (in preorder) in node's subtree
        #         that has no children or its children have rank
        #         >= newRank ]
        while ( ( len(node) > 0 ) and
                ( node[-1].rank < newRank ) ):
            node = node[-1]

        #-- 3 --
        return node