def chgid(name, gid):
    '''
    Change the default group of the user

    CLI Example:

    .. code-block:: bash

        salt '*' user.chgid foo 4376
    '''
    if not isinstance(gid, int):
        raise SaltInvocationError('gid must be an integer')
    pre_info = info(name)
    if not pre_info:
        raise CommandExecutionError('User {0!r} does not exist'.format(name))
    if gid == pre_info['gid']:
        return True
    _dscl(
        '/Users/{0} PrimaryGroupID {1!r} {2!r}'.format(
            _cmd_quote(name), _cmd_quote(pre_info['gid']),
            _cmd_quote(gid)),
        ctype='change'
    )
    # dscl buffers changes, sleep 1 second before checking if new value
    # matches desired value
    time.sleep(1)
    return info(name).get('gid') == gid

def chhome(name, home):
    '''
    Change the home directory of the user

    CLI Example:

    .. code-block:: bash

        salt '*' user.chhome foo /Users/foo
    '''
    pre_info = info(name)
    if not pre_info:
        raise CommandExecutionError('User {0!r} does not exist'.format(name))
    if home == pre_info['home']:
        return True
    _dscl(
        '/Users/{0} NFSHomeDirectory {1!r} {2!r}'.format(
            _cmd_quote(name),
            _cmd_quote(pre_info['home']),
           _cmd_quote(home)),
        ctype='change'
    )
    # dscl buffers changes, sleep 1 second before checking if new value
    # matches desired value
    time.sleep(1)
    return info(name).get('home') == home

def update(gems, ruby=None, runas=None, gem_bin=None):
    '''
    Update one or several gems.

    :param gems: string
        The gems to update.
    :param gem_bin: string : None
        Full path to ``gem`` binary to use.
    :param ruby: string : None
        If RVM or rbenv are installed, the ruby version and gemset to use.
        Ignored if ``gem_bin`` is specified.
    :param runas: string : None
        The user to run gem as.

    CLI Example:

    .. code-block:: bash

        salt '*' gem.update vagrant
    '''
    # Check for injection
    if gems:
        gems = ' '.join([_cmd_quote(gem) for gem in gems.split()])
    if ruby:
        ruby = _cmd_quote(ruby)
    if gem_bin:
        gem_bin = _cmd_quote(gem_bin)

    return _gem('update {gems}'.format(gems=gems),
                ruby,
                gem_bin=gem_bin,
                runas=runas)

def _rbenv_exec(command, args='', env=None, runas=None, ret=None):
    if not is_installed(runas):
        return False

    binary = _rbenv_bin(runas)
    path = _rbenv_path(runas)

    environ = {}
    for token in _cmd_split(env):
        try:
            var, val = token.split('=')
            environ[var] = val
        except Exception:
            pass  # if token != var=val, it's not a proper env anyway
    environ['RBENV_ROOT'] = path

    args = ' '.join([_cmd_quote(arg) for arg in _cmd_split(args)])

    result = __salt__['cmd.run_all'](
        '{0} {1} {2}'.format(binary, _cmd_quote(command), args),
        runas=runas,
        env=environ
    )

    if isinstance(ret, dict):
        ret.update(result)
        return ret

    if result['retcode'] == 0:
        return result['stdout']
    else:
        return False

def pair(address, key):
    '''
    Pair the bluetooth adapter with a device

    CLI Example:

    .. code-block:: bash

        salt '*' bluetooth.pair DE:AD:BE:EF:CA:FE 1234

    Where DE:AD:BE:EF:CA:FE is the address of the device to pair with, and 1234
    is the passphrase.

    TODO: This function is currently broken, as the bluez-simple-agent program
    no longer ships with BlueZ >= 5.0. It needs to be refactored.
    '''
    if not salt.utils.validate.net.mac(address):
        raise CommandExecutionError(
            'Invalid BD address passed to bluetooth.pair'
        )

    try:
        int(key)
    except Exception:
        raise CommandExecutionError(
            'bluetooth.pair requires a numerical key to be used'
        )

    addy = address_()
    cmd = 'echo {0} | bluez-simple-agent {1} {2}'.format(
        _cmd_quote(addy['device']), _cmd_quote(address), _cmd_quote(key)
    )
    out = __salt__['cmd.run'](cmd, python_shell=True).splitlines()
    return out

def removegroup(name, group):
    '''
    Remove user from a group

    :param str name:
        user name to remove from the group

    :param str group:
        name of the group from which to remove the user

    :return:
        True if successful. False is unsuccessful.
    :rtype: bool

    CLI Example:

    .. code-block:: bash

        salt '*' user.removegroup jsnuffy 'Power Users'
    '''
    name = _cmd_quote(name)
    group = _cmd_quote(group).lstrip('\'').rstrip('\'')

    user = info(name)

    if not user:
        return False

    if group not in user['groups']:
        return True

    cmd = 'net localgroup "{0}" {1} /delete'.format(group, name)
    ret = __salt__['cmd.run_all'](cmd, python_shell=True)

    return ret['retcode'] == 0

def do(cmdline=None, runas=None):
    '''
    Execute a python command with pyenv's shims from the user or the system.

    CLI Example:

    .. code-block:: bash

        salt '*' pyenv.do 'gem list bundler'
        salt '*' pyenv.do 'gem list bundler' deploy
    '''
    path = _pyenv_path(runas)
    cmd_split = cmdline.split()
    quoted_line = ''
    for cmd in cmd_split:
        quoted_line = quoted_line + ' ' + _cmd_quote(cmd)
    result = __salt__['cmd.run_all'](
        'env PATH={0}/shims:$PATH {1}'.format(_cmd_quote(path), quoted_line),
        runas=runas,
        python_shell=True
    )

    if result['retcode'] == 0:
        rehash(runas=runas)
        return result['stdout']
    else:
        return False

def sources_remove(source_uri, ruby=None, runas=None, gem_bin=None):
    '''
    Remove a gem source.

    :param source_uri: string
        The source URI to remove.
    :param gem_bin: string : None
        Full path to ``gem`` binary to use.
    :param ruby: string : None
        If RVM or rbenv are installed, the ruby version and gemset to use.
        Ignored if ``gem_bin`` is specified.
    :param runas: string : None
        The user to run gem as.

    CLI Example:

    .. code-block:: bash

        salt '*' gem.sources_remove http://rubygems.org/
    '''
    # Check for injection
    if source_uri:
        source_uri = _cmd_quote(source_uri)
    if ruby:
        ruby = _cmd_quote(ruby)
    if gem_bin:
        gem_bin = _cmd_quote(gem_bin)

    return _gem('sources --remove {source_uri}'.format(source_uri=source_uri),
                ruby,
                gem_bin=gem_bin,
                runas=runas)

def removegroup(name, group):
    '''
    Remove user from a group

    CLI Example:

    .. code-block:: bash

        salt '*' user.removegroup username groupname
    '''
    name = _cmd_quote(name)
    group = _cmd_quote(group).lstrip('\'').rstrip('\'')

    user = info(name)

    if not user:
        return False

    if group not in user['groups']:
        return True

    cmd = 'net localgroup "{0}" {1} /delete'.format(group, name)
    ret = __salt__['cmd.run_all'](cmd, python_shell=True)

    return ret['retcode'] == 0

def chfullname(name, fullname):
    '''
    Change the full name of the user

    CLI Example:

    .. code-block:: bash

        salt '*' user.chfullname user 'First Last'
    '''
    pre_info = info(name)

    if not pre_info:
        return False

    name = _cmd_quote(name)
    fullname_qts = _cmd_quote(fullname).replace("'", "\"")

    if fullname == pre_info['fullname']:
        return True
    if __salt__['cmd.retcode']('net user {0} /fullname:{1}'.format(
            name, fullname_qts), python_shell=True) != 0:
        return False

    post_info = info(name)
    if post_info['fullname'] != pre_info['fullname']:
        return post_info['fullname'] == fullname

    return False

def version_cmp(pkg1, pkg2):
    '''
    Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if
    pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem
    making the comparison.

    CLI Example:

    .. code-block:: bash

        salt '*' pkg.version_cmp '0.2.4-0' '0.2.4.1-0'
    '''
    cmd_compare = ['opkg-compare-versions']
    for oper, ret in (("<<", -1), ("=", 0), (">>", 1)):
        cmd = cmd_compare[:]
        cmd.append(_cmd_quote(pkg1))
        cmd.append(oper)
        cmd.append(_cmd_quote(pkg2))
        retcode = __salt__['cmd.retcode'](cmd,
                                          output_loglevel='trace',
                                          ignore_retcode=True,
                                          python_shell=False)
        if retcode == 0:
            return ret
    return None

def sources_list(ruby=None, runas=None, gem_bin=None):
    '''
    List the configured gem sources.

    :param gem_bin: string : None
        Full path to ``gem`` binary to use.
    :param ruby: string : None
        If RVM or rbenv are installed, the ruby version and gemset to use.
        Ignored if ``gem_bin`` is specified.
    :param runas: string : None
        The user to run gem as.

    CLI Example:

    .. code-block:: bash

        salt '*' gem.sources_list
    '''
    # Check for injection
    if ruby:
        ruby = _cmd_quote(ruby)
    if gem_bin:
        gem_bin = _cmd_quote(gem_bin)

    ret = _gem('sources', ruby, gem_bin=gem_bin, runas=runas)
    return [] if ret is False else ret.splitlines()[2:]

def version_cmp(pkg1, pkg2, ignore_epoch=False):
    '''
    Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if
    pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem
    making the comparison.

    ignore_epoch : False
        Set to ``True`` to ignore the epoch when comparing versions

        .. versionadded:: 2016.3.4

    CLI Example:

    .. code-block:: bash

        salt '*' pkg.version_cmp '0.2.4-0' '0.2.4.1-0'
    '''
    normalize = lambda x: str(x).split(':', 1)[-1] if ignore_epoch else str(x)
    pkg1 = normalize(pkg1)
    pkg2 = normalize(pkg2)

    cmd_compare = ['opkg-compare-versions']
    for oper, ret in (("<<", -1), ("=", 0), (">>", 1)):
        cmd = cmd_compare[:]
        cmd.append(_cmd_quote(pkg1))
        cmd.append(oper)
        cmd.append(_cmd_quote(pkg2))
        retcode = __salt__['cmd.retcode'](cmd,
                                          output_loglevel='trace',
                                          ignore_retcode=True,
                                          python_shell=False)
        if retcode == 0:
            return ret
    return None

def _rbenv_exec(command, args='', env=None, runas=None, ret=None):
    if not is_installed(runas):
        return False

    binary = _rbenv_bin(runas)
    path = _rbenv_path(runas)

    environ = _parse_env(env)
    environ['RBENV_ROOT'] = path

    args = ' '.join([_cmd_quote(arg) for arg in _shlex_split(args)])

    result = __salt__['cmd.run_all'](
        '{0} {1} {2}'.format(binary, _cmd_quote(command), args),
        runas=runas,
        env=environ
    )

    if isinstance(ret, dict):
        ret.update(result)
        return ret

    if result['retcode'] == 0:
        return result['stdout']
    else:
        return False

def chshell(name, shell):
    '''
    Change the default shell of the user

    CLI Example:

    .. code-block:: bash

        salt '*' user.chshell foo /bin/zsh
    '''
    pre_info = info(name)
    if not pre_info:
        raise CommandExecutionError('User {0!r} does not exist'.format(name))
    if shell == pre_info['shell']:
        return True
    _dscl(
        '/Users/{0} UserShell {1!r} {2!r}'.format(
            _cmd_quote(name),
            _cmd_quote(pre_info['shell']),
            _cmd_quote(shell)),
        ctype='change'
    )
    # dscl buffers changes, sleep 1 second before checking if new value
    # matches desired value
    time.sleep(1)
    return info(name).get('shell') == shell

def update_system(version='', ruby=None, runas=None, gem_bin=None):
    '''
    Update rubygems.

    :param version: string : (newest)
        The version of rubygems to install.
    :param gem_bin: string : None
        Full path to ``gem`` binary to use.
    :param ruby: string : None
        If RVM or rbenv are installed, the ruby version and gemset to use.
        Ignored if ``gem_bin`` is specified.
    :param runas: string : None
        The user to run gem as.

    CLI Example:

    .. code-block:: bash

        salt '*' gem.update_system
    '''
    # Check for injection
    if version:
        version = _cmd_quote(version)
    if ruby:
        ruby = _cmd_quote(ruby)
    if gem_bin:
        gem_bin = _cmd_quote(gem_bin)

    return _gem('update --system {version}'.format(version=version),
                ruby,
                gem_bin=gem_bin,
                runas=runas)

def chfullname(name, fullname):
    '''
    Change the user's Full Name

    CLI Example:

    .. code-block:: bash

        salt '*' user.chfullname foo 'Foo Bar'
    '''
    fullname = str(fullname)
    pre_info = info(name)
    if not pre_info:
        raise CommandExecutionError('User {0!r} does not exist'.format(name))
    if fullname == pre_info['fullname']:
        return True
    _dscl(
        '/Users/{0} RealName {1!r}'.format(_cmd_quote(name),
                                           _cmd_quote(fullname)),
        # use a "create" command, because a "change" command would fail if
        # current fullname is an empty string. The "create" will just overwrite
        # this field.
        ctype='create'
    )
    # dscl buffers changes, sleep 1 second before checking if new value
    # matches desired value
    time.sleep(1)
    return info(name).get('fullname') == fullname

def chgroups(name, groups, append=False):
    '''
    Change the groups to which the user belongs. Note that the user's primary
    group does not have to be one of the groups passed, membership in the
    user's primary group is automatically assumed.

    groups
        Groups to which the user should belong, can be passed either as a
        python list or a comma-separated string

    append
        Instead of removing user from groups not included in the ``groups``
        parameter, just add user to any groups for which they are not members

    CLI Example:

    .. code-block:: bash

        salt '*' user.chgroups foo wheel,root
    '''
    ### NOTE: **args isn't used here but needs to be included in this
    ### function for compatibility with the user.present state
    uinfo = info(name)
    if not uinfo:
        raise CommandExecutionError('User {0!r} does not exist'.format(name))
    if isinstance(groups, string_types):
        groups = groups.split(',')

    bad_groups = [x for x in groups if salt.utils.contains_whitespace(x)]
    if bad_groups:
        raise SaltInvocationError(
            'Invalid group name(s): {0}'.format(', '.join(bad_groups))
        )
    ugrps = set(list_groups(name))
    desired = set(str(x) for x in groups if bool(str(x)))
    primary_group = __salt__['file.gid_to_group'](uinfo['gid'])
    if primary_group:
        desired.add(primary_group)
    if ugrps == desired:
        return True
    # Add groups from which user is missing
    for group in desired - ugrps:
        _dscl(
            '/Groups/{0} GroupMembership {1}'.format(_cmd_quote(group),
                                                     _cmd_quote(name)),
            ctype='append'
        )
    if not append:
        # Remove from extra groups
        for group in ugrps - desired:
            _dscl(
                '/Groups/{0} GroupMembership {1}'.format(_cmd_quote(group),
                                                         _cmd_quote(name)),
                ctype='delete'
            )
    time.sleep(1)
    return set(list_groups(name)) == desired

def _bootstrap_pacman(root, pkg_confs="/etc/pacman*", img_format="dir", pkgs=None, exclude_pkgs=None):
    """
    Bootstrap an image using the pacman tools

    root
        The root of the image to install to. Will be created as a directory if
        if does not exist. (e.x.: /root/arch)

    pkg_confs
        The location of the conf files to copy into the image, to point pacman
        to the right repos and configuration.

    img_format
        The image format to be used. The ``dir`` type needs no special
        treatment, but others need special treatement.

    pkgs
        A list of packages to be installed on this image. For Arch Linux, this
        will include ``pacman``, ``linux``, ``grub``, and ``systemd-sysvcompat``
        by default.

    exclude_pkgs
        A list of packages to be excluded. If you do not want to install the
        defaults, you need to include them in this list.
    """
    _make_nodes(root)

    if pkgs is None:
        pkgs = []

    default_pkgs = ("pacman", "linux", "systemd-sysvcompat", "grub")
    for pkg in default_pkgs:
        if pkg not in pkgs:
            pkgs.append(pkg)

    if exclude_pkgs is None:
        exclude_pkgs = []

    for pkg in exclude_pkgs:
        pkgs.remove(pkg)

    if img_format != "dir":
        __salt__["mount.mount"]("{0}/proc".format(root), "/proc", fstype="", opts="bind")
        __salt__["mount.mount"]("{0}/dev".format(root), "/dev", fstype="", opts="bind")

    __salt__["file.mkdir"]("{0}/var/lib/pacman/local".format(root), "root", "root", "755")
    pac_files = [rf for rf in os.listdir("/etc") if rf.startswith("pacman.")]
    for pac_file in pac_files:
        __salt__["cmd.run"]("cp -r /etc/{0} {1}/etc".format(pac_file, _cmd_quote(root)))
    __salt__["file.copy"]("/var/lib/pacman/sync", "{0}/var/lib/pacman/sync".format(root), recurse=True)

    pacman_args = ["pacman", "--noconfirm", "-r", _cmd_quote(root), "-S"] + pkgs
    __salt__["cmd.run"](pacman_args, python_shell=False)

    if img_format != "dir":
        __salt__["mount.umount"]("{0}/proc".format(root))
        __salt__["mount.umount"]("{0}/dev".format(root))

def chgroups(name, groups, append=True):
    '''
    Change the groups this user belongs to, add append=False to make the user a
    member of only the specified groups

    :param str name:
        user name for which to change groups

    :param groups:
        a single group or a list of groups to assign to the user
    :type groups: list, str

    :param bool append:
        True adds the passed groups to the user's current groups
        False sets the user's groups to the passed groups only

    :return:
        True if successful. False is unsuccessful.
    :rtype: bool

    CLI Example:

    .. code-block:: bash

        salt '*' user.chgroups jsnuffy Administrators,Users True
    '''
    if isinstance(groups, string_types):
        groups = groups.split(',')

    groups = [x.strip(' *') for x in groups]
    ugrps = set(list_groups(name))
    if ugrps == set(groups):
        return True

    name = _cmd_quote(name)

    if not append:
        for group in ugrps:
            group = _cmd_quote(group).lstrip('\'').rstrip('\'')
            if group not in groups:
                cmd = 'net localgroup "{0}" {1} /delete'.format(group, name)
                __salt__['cmd.run_all'](cmd, python_shell=True)

    for group in groups:
        if group in ugrps:
            continue
        group = _cmd_quote(group).lstrip('\'').rstrip('\'')
        cmd = 'net localgroup "{0}" {1} /add'.format(group, name)
        out = __salt__['cmd.run_all'](cmd, python_shell=True)
        if out['retcode'] != 0:
            log.error(out['stdout'])
            return False

    agrps = set(list_groups(name))
    return len(ugrps - agrps) == 0