Callback validating the at_time commit option.

    Purpose: Validates the `at time` option for the commit command. Only the
           | the following two formats are supported: 'hh:mm[:ss]' or
           | 'yyyy-mm-dd hh:mm[:ss]' (seconds are optional).

    @param ctx: The click context paramter, for receiving the object dictionary
              | being manipulated by other previous functions. Needed by any
              | function with the @click.pass_context decorator. Callback
              | functions such as this one receive this automatically.
    @type ctx: click.Context
    @param param: param is passed into a validation callback function by click.
                | We do not use it.
    @type param: None
    @param value: The value that the user supplied for the at_time option.
    @type value: str

    @returns: The value that the user supplied, if it passed validation.
            | Otherwise, raises click.BadParameter
    @rtype: str

def at_time_validate(ctx, param, value):
    """ Callback validating the at_time commit option.

    Purpose: Validates the `at time` option for the commit command. Only the
           | the following two formats are supported: 'hh:mm[:ss]' or
           | 'yyyy-mm-dd hh:mm[:ss]' (seconds are optional).

    @param ctx: The click context paramter, for receiving the object dictionary
              | being manipulated by other previous functions. Needed by any
              | function with the @click.pass_context decorator. Callback
              | functions such as this one receive this automatically.
    @type ctx: click.Context
    @param param: param is passed into a validation callback function by click.
                | We do not use it.
    @type param: None
    @param value: The value that the user supplied for the at_time option.
    @type value: str

    @returns: The value that the user supplied, if it passed validation.
            | Otherwise, raises click.BadParameter
    @rtype: str
    """
    # if they are doing commit_at, ensure the input is formatted correctly.
    if value is not None:
        if (re.search(r'([0-2]\d)(:[0-5]\d){1,2}', value) is None and
            re.search(r'\d{4}-[01]\d-[0-3]\d [0-2]\d:[0-5]\d(:[0-5]\d)?',
                      value) is None):
            raise click.BadParameter("A commit at time must be in one of the "
                                     "two formats: 'hh:mm[:ss]' or "
                                     "'yyyy-mm-dd hh:mm[:ss]' (seconds are "
                                     "optional).")
    ctx.obj['at_time'] = value
    return value