blob: 10a53dc9cbf51d53055abfffeb9a85eb4334ebc4 [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
89 def global_matches(self, text):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000090 """Compute matches when text is a simple name.
Guido van Rossum2781fbe1997-09-26 22:04:56 +000091
Neil Schemenauerdbab3e32002-03-23 23:44:51 +000092 Return a list of all keywords, built-in functions and names currently
93 defined in self.namespace that match.
Guido van Rossum2781fbe1997-09-26 22:04:56 +000094
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000095 """
96 import keyword
97 matches = []
98 n = len(text)
99 for list in [keyword.kwlist,
Georg Brandl1a3284e2007-12-02 09:40:06 +0000100 builtins.__dict__,
Raymond Hettingere0d49722002-06-02 18:55:56 +0000101 self.namespace]:
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000102 for word in list:
Fred Drake46bd9a62000-05-31 14:31:00 +0000103 if word[:n] == text and word != "__builtins__":
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000104 matches.append(word)
105 return matches
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000106
107 def attr_matches(self, text):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000108 """Compute matches when text contains a dot.
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000109
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000110 Assuming the text is of the form NAME.NAME....[NAME], and is
Neil Schemenauerdbab3e32002-03-23 23:44:51 +0000111 evaluatable in self.namespace, it will be evaluated and its attributes
112 (as revealed by dir()) are used as possible completions. (For class
Walter Dörwaldf0dfc7a2003-10-20 14:01:56 +0000113 instances, class members are also considered.)
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000114
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000115 WARNING: this can still invoke arbitrary C code, if an object
116 with a __getattr__ hook is evaluated.
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000117
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000118 """
119 import re
120 m = re.match(r"(\w+(\.\w+)*)\.(\w*)", text)
121 if not m:
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000122 return []
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000123 expr, attr = m.group(1, 3)
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +0000124 try:
125 object = eval(expr, self.namespace)
126 except Exception:
127 return []
Guido van Rossum4e20de51999-10-26 13:09:08 +0000128 words = dir(object)
129 if hasattr(object,'__class__'):
130 words.append('__class__')
131 words = words + get_class_members(object.__class__)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000132 matches = []
133 n = len(attr)
134 for word in words:
Fred Drake46bd9a62000-05-31 14:31:00 +0000135 if word[:n] == attr and word != "__builtins__":
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000136 matches.append("%s.%s" % (expr, word))
137 return matches
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000138
Guido van Rossum4e20de51999-10-26 13:09:08 +0000139def get_class_members(klass):
140 ret = dir(klass)
141 if hasattr(klass,'__bases__'):
142 for base in klass.__bases__:
143 ret = ret + get_class_members(base)
144 return ret
145
Thomas Wouters477c8d52006-05-27 19:21:47 +0000146try:
147 import readline
148except ImportError:
149 pass
150else:
151 readline.set_completer(Completer().complete)