.. versionchanged:: 2017.7.0

    Remove a job from queue

    jobid: string|int
        Specific jobid to remove

    tag : string
        Job's tag

    runas : string
        Runs user-specified jobs

    kwargs
        Addition kwargs can be provided to filter jobs.
        See output of `at.jobcheck` for more.

    .. code-block:: yaml

        example1:
          at.absent:

    .. warning::
        this will remove all jobs!

    .. code-block:: yaml

        example2:
          at.absent:
            - year: 13

    .. code-block:: yaml

        example3:
          at.absent:
            - tag: rose

    .. code-block:: yaml

        example4:
          at.absent:
            - tag: rose
            - day: 13
            - hour: 16

    .. code-block:: yaml

        example5:
          at.absent:
            - jobid: 4

    .. note:
        all other filters are ignored and only job with id 4 is removed

def absent(name, jobid=None, **kwargs):
    '''
    .. versionchanged:: 2017.7.0

    Remove a job from queue

    jobid: string|int
        Specific jobid to remove

    tag : string
        Job's tag

    runas : string
        Runs user-specified jobs

    kwargs
        Addition kwargs can be provided to filter jobs.
        See output of `at.jobcheck` for more.

    .. code-block:: yaml

        example1:
          at.absent:

    .. warning::
        this will remove all jobs!

    .. code-block:: yaml

        example2:
          at.absent:
            - year: 13

    .. code-block:: yaml

        example3:
          at.absent:
            - tag: rose

    .. code-block:: yaml

        example4:
          at.absent:
            - tag: rose
            - day: 13
            - hour: 16

    .. code-block:: yaml

        example5:
          at.absent:
            - jobid: 4

    .. note:
        all other filters are ignored and only job with id 4 is removed
    '''
    ret = {'name': name,
           'changes': {},
           'result': True,
           'comment': ''}

    # limit was never support
    if 'limit' in kwargs:
        ret['comment'] = 'limit parameter not supported {0}'.format(name)
        ret['result'] = False
        return ret

    # quick return on test=True
    if __opts__['test']:
        ret['result'] = None
        ret['comment'] = 'removed ? job(s)'
        return ret

    # remove specific job
    if jobid:
        jobs = __salt__['at.atq'](jobid)
        if jobs.get('jobs'):
            ret['result'] = True
            ret['comment'] = 'job with id {jobid} not present'.format(
                jobid=jobid
            )
            return ret
        elif 'jobs' in jobs and len(jobs['jobs']) == 1:
            if 'job' in jobs['jobs'][0] and jobs['jobs'][0]['job']:
                res = __salt__['at.atrm'](jobid)
                ret['result'] = jobid in res['jobs']['removed']
                if ret['result']:
                    ret['comment'] = 'job with id {jobid} was removed'.format(
                        jobid=jobid
                    )
                else:
                    ret['comment'] = 'failed to remove job with id {jobid}'.format(
                        jobid=jobid
                    )
                ret['changes']['removed'] = res['jobs']['removed']
                return ret
        else:
            ret['result'] = False
            ret['comment'] = 'more than one job was return for job with id {jobid}'.format(
                jobid=jobid
            )
            return ret

    # remove jobs based on filter
    if kwargs:
        # we pass kwargs to at.jobcheck
        opts = list(list(map(str, [j['job'] for j in __salt__['at.jobcheck'](**kwargs)['jobs']])))
        res = __salt__['at.atrm'](*opts)
    else:
        # arguments to filter with, removing everything!
        res = __salt__['at.atrm']('all')

    if res['jobs']['removed']:
        ret['changes']['removed'] = res['jobs']['removed']
    ret['comment'] = 'removed {count} job(s)'.format(
        count=len(res['jobs']['removed'])
    )
    return ret