nomcompile3: Build a set of nomenclature files

# - - -   T x n y . _ _ a p p e n d T a x o n

    def __appendTaxon ( self, scan, rawTaxon ):
        '''Try to add a new Taxon to the tree.

          [ (scan is a Scan instance) and
            (rawTaxon is a RawTaxon instance) ->
              if rawTaxon can be appended to self.taxaTree ->
                self.taxaTree  +:=  a new Taxon instance made from
                    rawTaxon as its root node
                return that new Taxon
              else ->
                Log()  +:=  error message(s)
                raise SyntaxError ]
        '''

There are two main cases.

First, handle the special case when the tree is empty. For the logic that checks whether the new taxon can be a root, and sets it if so, see Section 18.2, “TaxaTree.setRoot(): Store the root taxon”.

        #-- 1 --
        # [ if self.taxaTree is empty ->
        #     if rawTaxon represents a valid root node ->
        #       self.taxaTree  :=  self.taxaTree with that root node
        #     else ->
        #       Log()  +:=  error message(s)
        #       raise SyntaxError
        #   else -> I ]
        if self.taxaTree.root is None:
            #-- 1.1 --
            # [ newRoot  :=  a new Taxon instance with hierarchy
            #       (self.hier), no parent, and attributes from
            #       rawTaxon ]
            newRoot = self.taxaTree.addTaxon ( None, rawTaxon )

            #-- 1.2 --
            # [ if newRoot's depth is 0 ->
            #     self.taxaTree  :=  self.TaxaTree with a new
            #         root Taxon (newRoot)
            #     return that Taxon
            #   else ->
            #     Log()  +:=  error message(s)
            #     raise SyntaxError ]
            try:
                self.taxaTree.setRoot ( newRoot )
                return newRoot
            except ValueError, detail:
                scan.syntax ( "Can't set the root taxon: %s" % detail )

At this point we know that the tree is not empty. First try to find an appropriate parent node for the new taxon; see Section 18.3, “TaxaTree.rankParent(): Under what parent does a new taxon go?”.

        #-- 2 --
        # [ if a taxon of rank (rawTaxon.rankCode) can be added as
        #   self.taxaTree as its last node in preorder ->
        #     parent  :=  rank-parent ( self.taxaTree,
        #                     rawTaxon.rankCode )
        #   else ->
        #     Log()  +:=  error message(s)
        #     raise SyntaxError ]
        try:
            parent = self.taxaTree.rankParent ( rawTaxon.rankCode )
        except ValueError, detail:
            scan.syntax ( detail )

Just because parent has the right rank does not imply that the new taxon can be added. For example, if the parent is a family and has subfamily children, a new genus cannot be added to that family. See Section 18.4, “TaxaTree.canAddChild()”.

        #-- 3 --
        # [ if can-add-child ( self.hier, parent, Rank for
        #   rawTaxon.rankCode) ->
        #     I
        #   else ->
        #     Log()  +:=  error message(s)
        #     raise SyntaxError ]
        try:
            self.taxaTree.canAddChild ( parent, rawTaxon.rankCode )
        except ValueError, detail:
            scan.syntax ( detail )

Everything is now ready for the addition of the new taxon to the tree. See Section 18.5, “TaxaTree.addTaxon()”.

        #-- 4 --
        # [ parent  :=  parent with a new Taxon child made from
        #               rawTaxon
        #   taxon  :=  that new Taxon ]
        taxon = self.taxaTree.addTaxon ( parent, rawTaxon )

        #-- 5 --
        return taxon