nomcompile3: Build a set of nomenclature files

# - - -   T a x o n . _ _ i n i t _ _

    def __init__ ( self, hier, parent, rawTaxon ):
        '''Constructor for Taxon.
        '''

Because the scientific and English names are destined for a flat file with fields of limited length, we need to enforce those limits before proceeding to set up the instance. See Section 6.19, “L_SCI” and Section 6.20, “L_ENG”.

        #-- 1 --
        # [ if ((len(rawTaxon.sci) > L_SCI) or
        #   (len(rawTaxon.eng) > L_ENG)) ->
        #     raise ValueError
        #   else -> I ]
        if len(rawTaxon.sci) > L_SCI:
            raise SyntaxError ( "Scientific name '%s' is %d "
                "characters long, but the flat file holds only "
                "%d characters." %
                (rawTaxon.sci, len(rawTaxon.sci), L_SCI) )

        if len(rawTaxon.eng) > L_ENG:
            raise SyntaxError ( "English name '%s' is %d "
                "characters long, but the flat file holds only "
                "%d characters." %
                (rawTaxon.eng, len(rawTaxon.eng), L_ENG) )

        #-- 2 --
        # [ rawTaxon.rankCode is in self.hier ->
        #     self.rank  :=  the Rank for that rankCode ]
        self.rank = hier.lookupRankCode ( rawTaxon.rankCode )

        #-- 3 --
        self.hier = hier
        self.parent = parent
        self.sci = rawTaxon.sci
        self.eng = rawTaxon.eng
        self.status = rawTaxon.status
        self.canon = rawTaxon.canon
        self.disamb = rawTaxon.disamb
        self.__childList = []

Having stored all the arguments and set up the child list, we need to set up three more attributes. The birth order is defined as zero for the root of the tree; otherwise it is the number of children that the parent already had (before we are added).

The other attributes to be computed are the taxonomic key in its short and full-length form. The short form .shortTxKey lacks trailing zeroes, so it is useful for building the key number for its children. The .txKey attribute has all the trailing zeroes in place. The taxonomic key is that of the parent, with one or more digits added for the new taxon's birth order plus one. The number of digits is specified by the .keyLen attribute of the new taxon's rank, but the key length for the highest rank is always zero.

Finally, except for the root taxon, add the new taxon to the parent's child list.

        #-- 4 --
        # [ if parent is None ->
        #     self.birthOrder = 0
        #     self.shortTxKey = ''
        #   else ->
        #     parent  :=  parent with self added as its new last child
        #     self.birthOrder  :=  number of parent's children
        #     self.shortTxKey  :=  (parent.shortTxKey) +
        #         (number of parent's children, left-zero-padded
        #         to the key length of self's rank) ]
        if parent is None:
            self.birthOrder = 0
            self.shortTxKey = ''
        else:
            self.birthOrder = len(parent)
            self.shortTxKey = parent.childKey ( self.rank )
            parent.__childList.append ( self )

For the logic that fills out a short taxonomic key to its full length, see Section 15.8, “Hier.txKeyFill(): Right-zero-pad a taxonomic key”.

        #-- 5 --
        self.txKey = self.hier.txKeyFill ( self.shortTxKey )