sidereal.py: Internal maintenance specification

# - - -   p a r s e H o u r s

def parseHours ( s ):
    """Validate and convert a quantity in hours.

      [ s is a non-empty string ->
          if s is a valid mixed hours expression ->
            return the value of s as decimal hours
          else -> raise SyntaxError ]
    """

First we'll set the optional minute and second to their default values of zero. The only required part is a floating hours followed by “h” (case-insensitive). We'll use Section 9.15, “parseFloatSuffix: Parse a number followed by a code” to process both the float and the suffix letter. The process is repeated for the minutes and seconds if present.

    #-- 1 --
    minute  =  second  =  0.0

    #-- 2 --
    # [ if s starts with a float followed by 'h' or 'H' ->
    #     hour  :=  that float as type float
    #     minTail  :=  s after that float and suffix
    #   else -> raise SyntaxError ]
    hour, minTail  =  parseFloatSuffix ( s, H_PAT,
                          "Hours followed by 'h'" )

    #-- 3 --
    # [ if minTail is empty -> I
    #   else if minTail has the form "(float)m" ->
    #     minute  :=  that (float)
    #   else if minTail has the form "(float)m(float)s" ->
    #     minute  :=  the first (float)
    #     second  :=  the second (float)
    #   else -> raise SyntaxError ]
    if  len(minTail) != 0:
        #-- 3.1 --
        # [ if minTail starts with a float followed by 'm' or 'M' ->
        #     minute  :=  that float as type float
        #     secTail  :=  minTail after all that
        #   else -> raise SyntaxError ]
        minute, secTail  =  parseFloatSuffix ( minTail, M_PAT,
                                "Minutes followed by 'm'" )

        #-- 3.2 --
        # [ if secTail is empty -> I
        #   else if secTail starts with a float followed by
        #   's' or 'S' ->
        #     second  :=  that float as type float
        #     checkTail  :=  secTail after all that
        #   else -> raise SyntaxError ]
        if  len(secTail) != 0:
            second, checkTail  =  parseFloatSuffix ( secTail,
                S_PAT, "Seconds followed by 's'" )
            if  len(checkTail) != 0:
                raise SyntaxError, ( "Unidentifiable angle parts: "
                                     "'%s'" % checkTail )

To convert from mixed units, we use Section 11, “dmsUnits: Mixed-units converter”.

    #-- 4 --
    # [ return the quantity (hour, minute, second) in hours ]
    result  =  dmsUnits.mixToSingle ( (hour, minute, second) )
    return  result