blob: 6eb1b3d0e93fe7ac9b6da8d09c34070419263886 [file] [log] [blame]
Guido van Rossum2781fbe1997-09-26 22:04:56 +00001"""Word completion for GNU readline 2.0.
2
Neil Schemenauerdbab3e32002-03-23 23:44:51 +00003This requires the latest extension to the readline module. The completer
4completes keywords, built-ins and globals in a selectable namespace (which
5defaults to __main__); when completing NAME.NAME..., it evaluates (!) the
6expression up to the last dot and completes its attributes.
Guido van Rossum2781fbe1997-09-26 22:04:56 +00007
Walter Dörwald65230a22002-06-03 15:58:32 +00008It's very cool to do "import sys" type "sys.", hit the
Guido van Rossum2781fbe1997-09-26 22:04:56 +00009completion key (twice), and see the list of names defined by the
Walter Dörwald65230a22002-06-03 15:58:32 +000010sys module!
Guido van Rossum2781fbe1997-09-26 22:04:56 +000011
12Tip: to use the tab key as the completion key, call
13
14 readline.parse_and_bind("tab: complete")
15
16Notes:
17
18- Exceptions raised by the completer function are *ignored* (and
19generally cause the completion to fail). This is a feature -- since
20readline sets the tty device in raw (or cbreak) mode, printing a
21traceback wouldn't work well without some complicated hoopla to save,
22reset and restore the tty state.
23
24- The evaluation of the NAME.NAME... form may cause arbitrary
25application defined code to be executed if an object with a
26__getattr__ hook is found. Since it is the responsibility of the
27application (or the user) to enable this feature, I consider this an
28acceptable risk. More complicated expressions (e.g. function calls or
29indexing operations) are *not* evaluated.
30
Guido van Rossum2781fbe1997-09-26 22:04:56 +000031- When the original stdin is not a tty device, GNU readline is never
32used, and this module (and the readline module) are silently inactive.
33
34"""
35
Georg Brandl1a3284e2007-12-02 09:40:06 +000036import builtins
Guido van Rossum2781fbe1997-09-26 22:04:56 +000037import __main__
Guido van Rossum2781fbe1997-09-26 22:04:56 +000038
Skip Montanaro0de65802001-02-15 22:15:14 +000039__all__ = ["Completer"]
40
Guido van Rossum2781fbe1997-09-26 22:04:56 +000041class Completer:
Neil Schemenauerdbab3e32002-03-23 23:44:51 +000042 def __init__(self, namespace = None):
43 """Create a new completer for the command line.
44
45 Completer([namespace]) -> completer instance.
46
47 If unspecified, the default namespace where completions are performed
48 is __main__ (technically, __main__.__dict__). Namespaces should be
49 given as dictionaries.
50
51 Completer instances should be used as the completion mechanism of
52 readline via the set_completer() call:
53
54 readline.set_completer(Completer(my_namespace).complete)
55 """
Tim Peters863ac442002-04-16 01:38:40 +000056
Neil Schemenauerdbab3e32002-03-23 23:44:51 +000057 if namespace and not isinstance(namespace, dict):
Collin Winterce36ad82007-08-30 01:19:48 +000058 raise TypeError('namespace must be a dictionary')
Neil Schemenauerdbab3e32002-03-23 23:44:51 +000059
60 # Don't bind to namespace quite yet, but flag whether the user wants a
61 # specific namespace or to use __main__.__dict__. This will allow us
62 # to bind to __main__.__dict__ at completion time, not now.
63 if namespace is None:
64 self.use_main_ns = 1
65 else:
66 self.use_main_ns = 0
67 self.namespace = namespace
Guido van Rossum2781fbe1997-09-26 22:04:56 +000068
69 def complete(self, text, state):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000070 """Return the next possible completion for 'text'.
Guido van Rossum2781fbe1997-09-26 22:04:56 +000071
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000072 This is called successively with state == 0, 1, 2, ... until it
73 returns None. The completion should begin with 'text'.
Guido van Rossum2781fbe1997-09-26 22:04:56 +000074
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000075 """
Neil Schemenauerdbab3e32002-03-23 23:44:51 +000076 if self.use_main_ns:
77 self.namespace = __main__.__dict__
Tim Peters863ac442002-04-16 01:38:40 +000078
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000079 if state == 0:
80 if "." in text:
81 self.matches = self.attr_matches(text)
82 else:
83 self.matches = self.global_matches(text)
Guido van Rossumd458faa1998-06-12 19:42:14 +000084 try:
85 return self.matches[state]
86 except IndexError:
87 return None
Guido van Rossum2781fbe1997-09-26 22:04:56 +000088
Benjamin Peterson41181742008-07-02 20:22:54 +000089 def _callable_postfix(self, val, word):
Benjamin Petersonbebfbe22008-07-05 21:20:33 +000090 if hasattr(val, '__call__'):
Benjamin Peterson41181742008-07-02 20:22:54 +000091 word = word + "("
92 return word
93
Guido van Rossum2781fbe1997-09-26 22:04:56 +000094 def global_matches(self, text):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000095 """Compute matches when text is a simple name.
Guido van Rossum2781fbe1997-09-26 22:04:56 +000096
Neil Schemenauerdbab3e32002-03-23 23:44:51 +000097 Return a list of all keywords, built-in functions and names currently
98 defined in self.namespace that match.
Guido van Rossum2781fbe1997-09-26 22:04:56 +000099
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000100 """
101 import keyword
102 matches = []
103 n = len(text)
Benjamin Peterson41181742008-07-02 20:22:54 +0000104 for word in keyword.kwlist:
105 if word[:n] == text:
106 matches.append(word)
107 for nspace in [builtins.__dict__, self.namespace]:
108 for word, val in nspace.items():
Benjamin Petersonf3854852008-07-05 20:59:18 +0000109 if word[:n] == text and word != "__builtins__":
Benjamin Peterson41181742008-07-02 20:22:54 +0000110 matches.append(self._callable_postfix(val, word))
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000111 return matches
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000112
113 def attr_matches(self, text):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000114 """Compute matches when text contains a dot.
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000115
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000116 Assuming the text is of the form NAME.NAME....[NAME], and is
Neil Schemenauerdbab3e32002-03-23 23:44:51 +0000117 evaluatable in self.namespace, it will be evaluated and its attributes
118 (as revealed by dir()) are used as possible completions. (For class
Walter Dörwaldf0dfc7a2003-10-20 14:01:56 +0000119 instances, class members are also considered.)
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000120
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000121 WARNING: this can still invoke arbitrary C code, if an object
122 with a __getattr__ hook is evaluated.
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000123
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000124 """
125 import re
126 m = re.match(r"(\w+(\.\w+)*)\.(\w*)", text)
127 if not m:
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000128 return []
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000129 expr, attr = m.group(1, 3)
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +0000130 try:
Benjamin Peterson095c1192008-07-21 16:32:10 +0000131 thisobject = eval(expr, self.namespace)
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +0000132 except Exception:
133 return []
Benjamin Peterson095c1192008-07-21 16:32:10 +0000134
135 # get the content of the object, except __builtins__
136 words = dir(thisobject)
137 if "__builtins__" in words:
138 words.remove("__builtins__")
139
140 if hasattr(thisobject, '__class__'):
Guido van Rossum4e20de51999-10-26 13:09:08 +0000141 words.append('__class__')
Benjamin Peterson095c1192008-07-21 16:32:10 +0000142 words.extend(get_class_members(thisobject.__class__))
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000143 matches = []
144 n = len(attr)
145 for word in words:
Benjamin Peterson095c1192008-07-21 16:32:10 +0000146 if word[:n] == attr and hasattr(thisobject, word):
147 val = getattr(thisobject, word)
Benjamin Peterson41181742008-07-02 20:22:54 +0000148 word = self._callable_postfix(val, "%s.%s" % (expr, word))
149 matches.append(word)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000150 return matches
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000151
Guido van Rossum4e20de51999-10-26 13:09:08 +0000152def get_class_members(klass):
153 ret = dir(klass)
154 if hasattr(klass,'__bases__'):
155 for base in klass.__bases__:
156 ret = ret + get_class_members(base)
157 return ret
158
Thomas Wouters477c8d52006-05-27 19:21:47 +0000159try:
160 import readline
161except ImportError:
162 pass
163else:
164 readline.set_completer(Completer().complete)