class_docstr: Base class for implementing magic functions.
  
  Shell functions which can be reached as %function_name. All magic
  functions should accept a string, which they can parse for their own
  needs. This can make some functions easier to type, eg `%cd ../`
  vs. `%cd("../")`
  
  Classes providing magic functions need to subclass this class, and they
  MUST:
  
  - Use the method decorators `@line_magic` and `@cell_magic` to decorate
    individual methods as magic functions, AND
  
  - Use the class decorator `@magics_class` to ensure that the magic
    methods are properly registered at the instance level upon instance
    initialization.
  
  See :mod:`magic_functions` for examples of actual implementation classes.
class_docstr_tok: ["Base","class","for","implementing","magic","functions",".","Shell","functions","which","can","be","reached","as","%","function_name",".","All","magic","functions","should","accept","a","string",",","which","they","can","parse","for","their","own","needs",".","This","can","make","some","functions","easier","to","type",",","eg","`","%","cd","..","\/","`","vs.","`","%","cd","(","``","..","\/","''",")","`","Classes","providing","magic","functions","need","to","subclass","this","class",",","and","they","MUST",":","-","Use","the","method","decorators","`","@","line_magic","`","and","`","@","cell_magic","`","to","decorate","individual","methods","as","magic","functions",",","AND","-","Use","the","class","decorator","`","@","magics_class","`","to","ensure","that","the","magic","methods","are","properly","registered","at","the","instance","level","upon","instance","initialization",".","See",":","mod",":","`","magic_functions","`","for","examples","of","actual","implementation","classes","."]
docstr: 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.
docstr_tok: ["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","."]
code: def parse_options(self, arg_str, opt_str, *long_opts, **kw):
      """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.
      """
  
      # inject default options at the beginning of the input line
      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)
      # Get options
      list_all = kw.get("list_all", 0)
      posix = kw.get("posix", os.name == "posix")
      strict = kw.get("strict", True)
  
      # Check if we have more than one argument to warrant extra processing:
      odict = {}  # Dictionary with options
      args = arg_str.split()
      if len(args) >= 1:
          # If the list of inputs only has 0 or 1 thing in it, there's no
          # need to look for options
          argv = arg_split(arg_str, posix, strict)
          # Do regular option processing
          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
  
      # Prepare opts,args for return
      opts = Struct(odict)
      if mode == "string":
          args = " ".join(args)
  
      return opts, args
  
imports: from __future__ import print_function
  import os
  import re
  import sys
  import types
  from getopt import getopt, GetoptError
  from traitlets.config.configurable import Configurable
  from IPython.core import oinspect
  from IPython.core.error import UsageError
  from IPython.core.inputsplitter import ESC_MAGIC, ESC_MAGIC2
  from decorator import decorator
  from IPython.utils.ipstruct import Struct
  from IPython.utils.process import arg_split
  from IPython.utils.py3compat import string_types, iteritems
  from IPython.utils.text import dedent
  from traitlets import Bool, Dict, Instance, observe
  from logging import error
label_desc: Use image node_id 4 for calling the Magics obj's underlying member method code with example usage: obj.parse_options(arg_str, opt_str) and returns: opts,  args