def find(what, flags=''):
    """
    >> find <regexp> [<flags>]
    
    Succeed if the regular expression is on the page.  Sets the local
    variable __match__ to the matching text.

    Flags is a string consisting of the following characters:

    * i: ignorecase
    * m: multiline
    * s: dotall

    For explanations of these, please see the Python re module
    documentation.
    """
    regexp = re.compile(what, _parseFindFlags(flags))
    page = browser.get_html()

    m = regexp.search(page)
    if not m:
        raise TwillAssertionError("no match to '%s'" % (what,))

    if m.groups():
        match_str = m.group(1)
    else:
        match_str = m.group(0)

    _, local_dict = get_twill_glocals()
    local_dict['__match__'] = match_str

    def init(self, **kw):
        if kw.has_key('stdin'):
            cmd.Cmd.__init__(self, None, stdin=kw['stdin'])
            self.use_rawinput = False
        else:
            cmd.Cmd.__init__(self)

        # initialize a new local namespace.
        namespaces.new_local_dict()

        # import readline history, if available.
        if readline:
            try:
                readline.read_history_file('.twill-history')
            except IOError:
                pass

        # fail on unknown commands? for test-shell, primarily.
        self.fail_on_unknown = kw.get('fail_on_unknown', False)

        # handle initial URL argument
        if kw.get('initial_url'):
            commands.go(kw['initial_url'])
            
        self._set_prompt()

        self.names = []
        
        global_dict, local_dict = namespaces.get_twill_glocals()

        ### add all of the commands from twill.
        for command in parse.command_list:
            fn = global_dict.get(command)
            self.add_command(command, fn.__doc__)

def url(should_be):
    """
    >> url <regexp>

    Check to make sure that the current URL matches the regexp.  The local
    variable __match__ is set to the matching part of the URL.
    """
    regexp = re.compile(should_be)
    current_url = browser.get_url()

    m = None
    if current_url is not None:
        m = regexp.search(current_url)
    else:
        current_url = ''

    if not m:
        raise TwillAssertionError("""\
current url is '%s';
does not match '%s'
""" % (current_url, should_be,))

    if m.groups():
        match_str = m.group(1)
    else:
        match_str = m.group(0)

    global_dict, local_dict = get_twill_glocals()
    local_dict['__match__'] = match_str
    return match_str

def setlocal(name, value):
    """
    setlocal <name> <value>

    Sets the variable <name> to the value <value> in the local namespace.
    """
    global_dict, local_dict = get_twill_glocals()
    local_dict[name] = value

def runfile(*files):
    """
    >> runfile <file1> [ <file2> ... ]

    """
    import parse
    global_dict, local_dict = get_twill_glocals()

    for f in files:
        parse.execute_file(f, no_reset=True)

    def do_cmd(rest_of_line, cmd=cmd):
        global_dict, local_dict = namespaces.get_twill_glocals()

        args = []
        if rest_of_line.strip() != "":
            try:
                args = parse.arguments.parseString(rest_of_line)[0]
                args = parse.process_args(args, global_dict,local_dict)
            except Exception, e:
                logger.error('INPUT ERROR: %s\n', str(e))
                return

def getinput(prompt):
    """
    >> getinput <prompt>
    Get input, store it in '__input__'.
    """
    _, local_dict = get_twill_glocals()

    inp = raw_input(prompt)

    local_dict['__input__'] = inp
    return inp

def getpassword(prompt):
    """
    >> getpassword <prompt>
    
    Get a password ("invisible input"), store it in '__password__'.
    """
    _, local_dict = get_twill_glocals()

    inp = getpass.getpass(prompt)

    local_dict['__password__'] = inp
    return inp

def extend_with(module_name):
    """
    >> extend_with <module>
    
    Import contents of given module.
    """
    global_dict, local_dict = get_twill_glocals()

    exec "from %s import *" % (module_name,) in global_dict

    ### now add the commands into the commands available for the shell,
    ### and print out some nice stuff about what the extension module does.

    import sys

    mod = sys.modules.get(module_name)

    ###

    import twill.shell, twill.parse

    fnlist = getattr(mod, "__all__", None)
    if fnlist is None:
        fnlist = [fn for fn in dir(mod) if callable(getattr(mod, fn))]

    for command in fnlist:
        fn = getattr(mod, command)
        twill.shell.add_command(command, fn.__doc__)
        twill.parse.command_list.append(command)

    ###

    print >> OUT, "Imported extension module '%s'." % (module_name,)
    print >> OUT, "(at %s)\n" % (mod.__file__,)

    if twill.shell.interactive:
        if mod.__doc__:
            print >> OUT, "Description:\n\n%s\n" % (mod.__doc__.strip(),)
        else:
            if fnlist:
                print >> OUT, "New commands:\n"
                for name in fnlist:
                    print >> OUT, "\t", name

                print >> OUT, ""

def run(cmd):
    """
    >> run <command>

    <command> can be any valid python command; 'exec' is used to run it.
    """
    # @CTB: use pyparsing to grok the command?  make sure that quoting works...
    
    # execute command.
    global_dict, local_dict = get_twill_glocals()
    
    import commands

    # set __url__
    local_dict['__cmd__'] = cmd
    local_dict['__url__'] = commands.browser.get_url()

    exec(cmd, global_dict, local_dict)

def title(what):
    """
    >> title <regexp>
    
    Succeed if the regular expression is in the page title.
    """
    regexp = re.compile(what)
    title = browser.get_title()

    print>>OUT, "title is '%s'." % (title,)

    m = regexp.search(title)
    if not m:
        raise TwillAssertionError("title does not contain '%s'" % (what,))

    if m.groups():
        match_str = m.group(1)
    else:
        match_str = m.group(0)

    global_dict, local_dict = get_twill_glocals()
    local_dict['__match__'] = match_str
    return match_str

    def default(self, line):
        "Called when unknown command is executed."

        # empty lines ==> emptyline(); here we just want to remove
        # leading whitespace.
        line = line.strip()

        # look for command
        global_dict, local_dict = namespaces.get_twill_glocals()
        cmd, args = parse.parse_command(line, global_dict, local_dict)

        # ignore comments & empty stuff
        if cmd is None:
            return

        try:
            parse.execute_command(cmd, args, global_dict, local_dict,
                                  "<shell>")
        except SystemExit:
            raise
        except Exception, e:
            logger.error('%s\n' % (str(e),))
            if self.fail_on_unknown:
                raise

def _execute_script(inp, **kw):
    """
    Execute lines taken from a file-like iterator.
    """
    # initialize new local dictionary & get global + current local
    namespaces.new_local_dict()
    globals_dict, locals_dict = namespaces.get_twill_glocals()
    
    locals_dict['__url__'] = commands.browser.get_url()

    # reset browser
    if not kw.get('no_reset'):
        commands.reset_browser()

    # go to a specific URL?
    init_url = kw.get('initial_url')
    if init_url:
        commands.go(init_url)
        locals_dict['__url__'] = commands.browser.get_url()

    # should we catch exceptions on failure?
    catch_errors = False
    if kw.get('never_fail'):
        catch_errors = True

    # sourceinfo stuff
    sourceinfo = kw.get('source', "<input>")
    
    try:

        for n, line in enumerate(inp):
            if not line.strip():            # skip empty lines
                continue

            cmdinfo = "%s:%d" % (sourceinfo, n,)
            print 'AT LINE:', cmdinfo

            cmd, args = parse_command(line, globals_dict, locals_dict)
            if cmd is None:
                continue

            try:
                execute_command(cmd, args, globals_dict, locals_dict, cmdinfo)
            except SystemExit:
                # abort script execution, if a SystemExit is raised.
                return
            except TwillAssertionError, e:
                print>>commands.ERR, '''\
Oops!  Twill assertion error on line %d of '%s' while executing

  >> %s

%s
''' % (n, sourceinfo, line.strip(), e)
                if not catch_errors:
                    raise
            except Exception, e:
                print>>commands.ERR, '''\
EXCEPTION raised at line %d of '%s'

      %s

Error message: '%s'

''' % (n, sourceinfo, line.strip(),str(e).strip(),)

                if not catch_errors:
                    raise