'Parse options passed to an argument string.
The interface is similar to that of :func:`getopt.getopt`, but it
returns a :class:`~IPython.utils.struct.Struct` with the options as keys
and the stripped argument string still as a string.
arg_str is quoted as a true sys.argv vector by using shlex.split.
This allows us to easily expand variables, glob files, quote
arguments, etc.
Parameters
arg_str : str
The arguments to parse.
opt_str : str
The options specification.
mode : str, default \'string\'
If given as \'list\', the argument string is returned as a list (split
on whitespace) instead of a string.
list_all : bool, default False
Put all option values in lists. Normally only options
appearing more than once are put in a list.
posix : bool, default True
Whether to split the input line in POSIX mode or not, as per the
conventions outlined in the :mod:`shlex` module from the standard
library.'

def parse_options(self, arg_str, opt_str, *long_opts, **kw):

    caller = sys._getframe(1).f_code.co_name
    arg_str = ('%s    %s' % (self.options_table.get(caller, ''), arg_str))
    mode = kw.get('mode', 'string')
    if (mode not in ['string', 'list']):
        raise ValueError(('incorrect    mode    given:    %s' % mode))
    list_all = kw.get('list_all', 0)
    posix = kw.get('posix', (os.name == 'posix'))
    strict = kw.get('strict', True)
    odict = {}
    args = arg_str.split()
    if (len(args) >= 1):
        argv = arg_split(arg_str, posix, strict)
        try:
            (opts, args) = getopt(argv, opt_str, long_opts)
        except GetoptError as e:
            raise UsageError(('%s    (    allowed:    "%s"    %s)' % (e.msg, opt_str, '    '.join(long_opts))))
        for (o, a) in opts:
            if o.startswith('--'):
                o = o[2:]
            else:
                o = o[1:]
            try:
                odict[o].append(a)
            except AttributeError:
                odict[o] = [odict[o], a]
            except KeyError:
                if list_all:
                    odict[o] = [a]
                else:
                    odict[o] = a
    opts = Struct(odict)
    if (mode == 'string'):
        args = '    '.join(args)
    return (opts, args)
