sidereal.py: Internal maintenance specification

This function validates and converts a string containing an angle in mixed units, such as “34d18.37m” or “34d18m4.006s”. The degrees part is required; the minutes and seconds are optional.

# - - -   p a r s e A n g l e

def parseAngle ( s ):
    """Validate and convert an external angle.

      [ s is a string ->
          if s is a valid external angle ->
            return s in radians
          else -> raise SyntaxError ]
    """

The general approach is first to require the degrees part—a floating-point number—followed by “d” (either case). If there is anything after that, it must start with another float and letter “m”. If there is still more, it must be another float and “s”, and nothing more.

First we set up default values for the optional minutes and seconds. Then we process the degrees and its suffix.

    #-- 1 --
    minute  =  second  =  0.0
    #-- 2 --
    # [ if s starts with a float followed by 'd' or 'D' ->
    #     degree    :=  that float as type float
    #     minTail  :=  s after that float and suffix
    #   else -> raise SyntaxError ]
    degree, minTail  =  parseFloatSuffix ( s, D_PAT,
                          "Degrees followed by 'd'" )

    #-- 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 angle (degree, minute, second) in radians ]
    angleDegrees  =  dmsUnits.mixToSingle ( (degree, minute, second) )
    return  radians ( angleDegrees )