blob: dab0cb9eaa394769af1ec094ed977a6526d1cd06 [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
31- GNU readline is also used by the built-in functions input() and
32raw_input(), and thus these also benefit/suffer from the completer
33features. Clearly an interactive application can benefit by
34specifying its own completer function and using raw_input() for all
35its input.
36
37- When the original stdin is not a tty device, GNU readline is never
38used, and this module (and the readline module) are silently inactive.
39
40"""
41
Guido van Rossum2781fbe1997-09-26 22:04:56 +000042import __builtin__
43import __main__
Guido van Rossum2781fbe1997-09-26 22:04:56 +000044
Skip Montanaro0de65802001-02-15 22:15:14 +000045__all__ = ["Completer"]
46
Guido van Rossum2781fbe1997-09-26 22:04:56 +000047class Completer:
Neil Schemenauerdbab3e32002-03-23 23:44:51 +000048 def __init__(self, namespace = None):
49 """Create a new completer for the command line.
50
51 Completer([namespace]) -> completer instance.
52
53 If unspecified, the default namespace where completions are performed
54 is __main__ (technically, __main__.__dict__). Namespaces should be
55 given as dictionaries.
56
57 Completer instances should be used as the completion mechanism of
58 readline via the set_completer() call:
59
60 readline.set_completer(Completer(my_namespace).complete)
61 """
Tim Peters863ac442002-04-16 01:38:40 +000062
Neil Schemenauerdbab3e32002-03-23 23:44:51 +000063 if namespace and not isinstance(namespace, dict):
64 raise TypeError,'namespace must be a dictionary'
65
66 # Don't bind to namespace quite yet, but flag whether the user wants a
67 # specific namespace or to use __main__.__dict__. This will allow us
68 # to bind to __main__.__dict__ at completion time, not now.
69 if namespace is None:
70 self.use_main_ns = 1
71 else:
72 self.use_main_ns = 0
73 self.namespace = namespace
Guido van Rossum2781fbe1997-09-26 22:04:56 +000074
75 def complete(self, text, state):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000076 """Return the next possible completion for 'text'.
Guido van Rossum2781fbe1997-09-26 22:04:56 +000077
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000078 This is called successively with state == 0, 1, 2, ... until it
79 returns None. The completion should begin with 'text'.
Guido van Rossum2781fbe1997-09-26 22:04:56 +000080
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000081 """
Neil Schemenauerdbab3e32002-03-23 23:44:51 +000082 if self.use_main_ns:
83 self.namespace = __main__.__dict__
Tim Peters863ac442002-04-16 01:38:40 +000084
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000085 if state == 0:
86 if "." in text:
87 self.matches = self.attr_matches(text)
88 else:
89 self.matches = self.global_matches(text)
Guido van Rossumd458faa1998-06-12 19:42:14 +000090 try:
91 return self.matches[state]
92 except IndexError:
93 return None
Guido van Rossum2781fbe1997-09-26 22:04:56 +000094
95 def global_matches(self, text):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000096 """Compute matches when text is a simple name.
Guido van Rossum2781fbe1997-09-26 22:04:56 +000097
Neil Schemenauerdbab3e32002-03-23 23:44:51 +000098 Return a list of all keywords, built-in functions and names currently
99 defined in self.namespace that match.
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000100
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000101 """
102 import keyword
103 matches = []
104 n = len(text)
105 for list in [keyword.kwlist,
Raymond Hettingere0d49722002-06-02 18:55:56 +0000106 __builtin__.__dict__,
107 self.namespace]:
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000108 for word in list:
Fred Drake46bd9a62000-05-31 14:31:00 +0000109 if word[:n] == text and word != "__builtins__":
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000110 matches.append(word)
111 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:
128 return
129 expr, attr = m.group(1, 3)
Neil Schemenauerdbab3e32002-03-23 23:44:51 +0000130 object = eval(expr, self.namespace)
Guido van Rossum4e20de51999-10-26 13:09:08 +0000131 words = dir(object)
132 if hasattr(object,'__class__'):
133 words.append('__class__')
134 words = words + get_class_members(object.__class__)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000135 matches = []
136 n = len(attr)
137 for word in words:
Fred Drake46bd9a62000-05-31 14:31:00 +0000138 if word[:n] == attr and word != "__builtins__":
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000139 matches.append("%s.%s" % (expr, word))
140 return matches
Guido van Rossum2781fbe1997-09-26 22:04:56 +0000141
Guido van Rossum4e20de51999-10-26 13:09:08 +0000142def get_class_members(klass):
143 ret = dir(klass)
144 if hasattr(klass,'__bases__'):
145 for base in klass.__bases__:
146 ret = ret + get_class_members(base)
147 return ret
148
Georg Brandl3583cff2006-04-30 18:14:54 +0000149try:
150 import readline
151except ImportError:
152 pass
153else:
154 readline.set_completer(Completer().complete)