blob: 6b44f26413202f1089d851b96dd396d02839be91 [file] [log] [blame]
Johnny Chen14097802011-04-28 21:31:18 +00001#
Johnny Chenc6220052011-04-28 23:53:16 +00002# modify-lldb-python.py
Johnny Chen14097802011-04-28 21:31:18 +00003#
4# This script modifies the lldb module (which was automatically generated via
Johnny Chen22e418a2011-04-29 19:22:24 +00005# running swig) to support iteration and/or equality operations for certain lldb
Johnny Chene5637d22011-05-24 21:05:16 +00006# objects, implements truth value testing for certain lldb objects, and adds a
7# global variable 'debugger_unique_id' which is initialized to 0.
Johnny Chen14097802011-04-28 21:31:18 +00008#
Johnny Chen09e0a422011-07-01 22:14:07 +00009# As a cleanup step, it also removes the 'residues' from the autodoc features of
10# swig. For an example, take a look at SBTarget.h header file, where we take
Johnny Chen2c77fa42011-07-02 20:01:09 +000011# advantage of the already existing doxygen C++-docblock and make it the Python
Johnny Chen09e0a422011-07-01 22:14:07 +000012# docstring for the same method. The 'residues' in this context include the
Johnny Chenf6ce70a2011-07-03 19:55:50 +000013# '#endif', the '#ifdef SWIG', the c comment marker, the trailing blank (SPC's)
14# line, and the doxygen comment start marker.
Johnny Chen09e0a422011-07-01 22:14:07 +000015#
Johnny Chen37811372011-07-06 21:55:45 +000016# In addition to the 'residues' removal during the cleanup step, it also
17# transforms the 'char' data type (which was actually 'char *' but the 'autodoc'
18# feature of swig removes ' *' from it into 'str' (as a Python str type).
19#
Johnny Chen14097802011-04-28 21:31:18 +000020# It also calls SBDebugger.Initialize() to initialize the lldb debugger
21# subsystem.
22#
23
24import sys, re, StringIO
25
26if len (sys.argv) != 2:
27 output_name = "./lldb.py"
28else:
29 output_name = sys.argv[1] + "/lldb.py"
30
31# print "output_name is '" + output_name + "'"
32
Johnny Chen37811372011-07-06 21:55:45 +000033#
Johnny Chen09e0a422011-07-01 22:14:07 +000034# Residues to be removed.
Johnny Chen37811372011-07-06 21:55:45 +000035#
Johnny Chen09e0a422011-07-01 22:14:07 +000036c_endif_swig = "#endif"
37c_ifdef_swig = "#ifdef SWIG"
Johnny Chen2c77fa42011-07-02 20:01:09 +000038c_comment_marker = "//------------"
39# The pattern for recognizing the doxygen comment block line.
Johnny Chenebd63b22011-07-16 21:15:39 +000040doxygen_comment_start = re.compile("^\s*(/// ?)")
Johnny Chenf6ce70a2011-07-03 19:55:50 +000041# The demarcation point for turning on/off residue removal state.
42# When bracketed by the lines, the CLEANUP_DOCSTRING state (see below) is ON.
43toggle_docstring_cleanup_line = ' """'
Johnny Chen09e0a422011-07-01 22:14:07 +000044
Johnny Chen37811372011-07-06 21:55:45 +000045def char_to_str_xform(line):
46 """This transforms the 'char', i.e, 'char *' to 'str', Python string."""
47 line = line.replace(' char', ' str')
48 line = line.replace('char ', 'str ')
Johnny Chen2de7ce62011-07-14 00:17:49 +000049 # Special case handling of 'char **argv' and 'char **envp'.
50 line = line.replace('str argv', 'list argv')
51 line = line.replace('str envp', 'list envp')
Johnny Chen37811372011-07-06 21:55:45 +000052 return line
53
54#
55# The one-liner docstring also needs char_to_str transformation, btw.
56#
Johnny Chen21c0fd12011-07-08 23:57:20 +000057TWO_SPACES = ' ' * 2
58EIGHT_SPACES = ' ' * 8
59one_liner_docstring_pattern = re.compile('^(%s|%s)""".*"""$' % (TWO_SPACES, EIGHT_SPACES))
Johnny Chen37811372011-07-06 21:55:45 +000060
Johnny Chen14097802011-04-28 21:31:18 +000061#
Johnny Chenec5e0a22011-06-01 18:40:11 +000062# lldb_iter() should appear before our first SB* class definition.
Johnny Chen14097802011-04-28 21:31:18 +000063#
64lldb_iter_def = '''
65# ===================================
66# Iterator for lldb container objects
67# ===================================
68def lldb_iter(obj, getsize, getelem):
69 """A generator adaptor to support iteration for lldb container objects."""
70 size = getattr(obj, getsize)
71 elem = getattr(obj, getelem)
72 for i in range(size()):
73 yield elem(i)
74
Johnny Chen81422202011-06-01 19:21:08 +000075# ==============================================================================
76# The modify-python-lldb.py script is responsible for post-processing this SWIG-
77# generated lldb.py module. It is responsible for adding the above lldb_iter()
78# function definition as well as the supports, in the following, for iteration
79# protocol: __iter__, rich comparison methods: __eq__ and __ne__, truth value
80# testing (and built-in operation bool()): __nonzero__, and built-in function
81# len(): __len__.
82# ==============================================================================
Johnny Chen14097802011-04-28 21:31:18 +000083'''
84
Johnny Chenfbebbc92011-07-25 19:32:35 +000085#
86# linked_list_iter() is a special purpose iterator to treat the SBValue as a
87# list data structure, where you specify the child member name which points to
88# the next item on the list and you specify the end-of-list function which takes
89# an SBValue and returns True if EOL is reached and False if not.
90#
91linked_list_iter_def = '''
92 # ==================================================
93 # Iterator for lldb.SBValue treated as a linked list
94 # ==================================================
95 def linked_list_iter(self, next_item_name, end_of_list):
96 """A generator adaptor to support iteration for SBValue as a linked list.
97
98 For example,
99
100 # Test function to determine end of list.
101 def eol(val):
102 if not val:
103 return True
104 try:
105 # Test the semantics of the item we got.
106 id = val.GetChildMemberWithName("id")
107 if int(id.GetValue()) > 0:
108 return False
109 except:
110 pass
111
112 # If we fall through to here. It could be that exception
113 # occurred or the "id" child member does not qualify as a
114 # valid item. Return True for EOL.
115 return True
116
117 # Get Frame #0.
118 ...
119
120 # Get variable 'task_head'.
121 task_head = frame0.FindVariable('task_head')
122 ...
123
124 for t in task_head.linked_list_iter('next', eol):
125 print t
126 """
127 try:
128 item = self.GetChildMemberWithName(next_item_name)
129 while item:
130 yield item
131 # Prepare for the next iteration.
132 item = item.GetChildMemberWithName(next_item_name)
133 if end_of_list(item):
134 break
135 except:
136 # Exception occurred. Stop the generator.
137 pass
138
139 return
140'''
141
Johnny Chen14097802011-04-28 21:31:18 +0000142# This supports the iteration protocol.
Johnny Chen14097802011-04-28 21:31:18 +0000143iter_def = " def __iter__(self): return lldb_iter(self, '%s', '%s')"
144module_iter = " def module_iter(self): return lldb_iter(self, '%s', '%s')"
145breakpoint_iter = " def breakpoint_iter(self): return lldb_iter(self, '%s', '%s')"
Johnny Chen2077f0d2011-05-17 22:14:39 +0000146
Johnny Chena79a21c2011-05-16 20:31:18 +0000147# Called to implement the built-in function len().
148# Eligible objects are those containers with unambiguous iteration support.
Johnny Chena79a21c2011-05-16 20:31:18 +0000149len_def = " def __len__(self): return self.%s()"
Johnny Chen2077f0d2011-05-17 22:14:39 +0000150
Johnny Chen3a3d6592011-04-29 19:03:02 +0000151# This supports the rich comparison methods of __eq__ and __ne__.
Johnny Chen7616cb92011-05-02 19:05:52 +0000152eq_def = " def __eq__(self, other): return isinstance(other, %s) and %s"
Johnny Chen3a3d6592011-04-29 19:03:02 +0000153ne_def = " def __ne__(self, other): return not self.__eq__(other)"
Johnny Chen14097802011-04-28 21:31:18 +0000154
Johnny Chen2077f0d2011-05-17 22:14:39 +0000155# Called to implement truth value testing and the built-in operation bool();
156# should return False or True, or their integer equivalents 0 or 1.
157# Delegate to self.IsValid() if it is defined for the current lldb object.
158nonzero_def = " def __nonzero__(self): return self.IsValid()"
159
Johnny Chen14097802011-04-28 21:31:18 +0000160#
Johnny Chena6303ef2011-05-24 22:53:03 +0000161# This dictionary defines a mapping from classname to (getsize, getelem) tuple.
Johnny Chen14097802011-04-28 21:31:18 +0000162#
163d = { 'SBBreakpoint': ('GetNumLocations', 'GetLocationAtIndex'),
164 'SBCompileUnit': ('GetNumLineEntries', 'GetLineEntryAtIndex'),
165 'SBDebugger': ('GetNumTargets', 'GetTargetAtIndex'),
166 'SBModule': ('GetNumSymbols', 'GetSymbolAtIndex'),
167 'SBProcess': ('GetNumThreads', 'GetThreadAtIndex'),
168 'SBThread': ('GetNumFrames', 'GetFrameAtIndex'),
169
170 'SBInstructionList': ('GetSize', 'GetInstructionAtIndex'),
171 'SBStringList': ('GetSize', 'GetStringAtIndex',),
172 'SBSymbolContextList': ('GetSize', 'GetContextAtIndex'),
173 'SBValueList': ('GetSize', 'GetValueAtIndex'),
174
175 'SBType': ('GetNumberChildren', 'GetChildAtIndex'),
176 'SBValue': ('GetNumChildren', 'GetChildAtIndex'),
177
Johnny Chen08477f52011-05-24 22:57:42 +0000178 # SBTarget needs special processing, see below.
Johnny Chen14097802011-04-28 21:31:18 +0000179 'SBTarget': {'module': ('GetNumModules', 'GetModuleAtIndex'),
180 'breakpoint': ('GetNumBreakpoints', 'GetBreakpointAtIndex')
181 }
182 }
183
Johnny Chen3a3d6592011-04-29 19:03:02 +0000184#
Johnny Chen7616cb92011-05-02 19:05:52 +0000185# This dictionary defines a mapping from classname to equality method name(s).
Johnny Chen3a3d6592011-04-29 19:03:02 +0000186#
Johnny Chen694cfd02011-06-09 22:04:56 +0000187e = { 'SBAddress': ['GetFileAddress', 'GetModule'],
188 'SBBreakpoint': ['GetID'],
Johnny Chen7616cb92011-05-02 19:05:52 +0000189 'SBFileSpec': ['GetFilename', 'GetDirectory'],
190 'SBModule': ['GetFileSpec', 'GetUUIDString']
191 }
192
193def list_to_frag(list):
194 """Transform a list to equality program fragment.
195
196 For example, ['GetID'] is transformed to 'self.GetID() == other.GetID()',
197 and ['GetFilename', 'GetDirectory'] to 'self.GetFilename() == other.GetFilename()
198 and self.GetDirectory() == other.GetDirectory()'.
199 """
200 if not list:
201 raise Exception("list should be non-empty")
202 frag = StringIO.StringIO()
203 for i in range(len(list)):
204 if i > 0:
205 frag.write(" and ")
206 frag.write("self.{0}() == other.{0}()".format(list[i]))
207 return frag.getvalue()
Johnny Chen3a3d6592011-04-29 19:03:02 +0000208
Johnny Chenebd63b22011-07-16 21:15:39 +0000209class NewContent(StringIO.StringIO):
210 """Simple facade to keep track of the previous line to be committed."""
211 def __init__(self):
212 StringIO.StringIO.__init__(self)
213 self.prev_line = None
214 def add_line(self, a_line):
215 """Add a line to the content, if there is a previous line, commit it."""
216 if self.prev_line != None:
217 print >> self, self.prev_line
218 self.prev_line = a_line
219 def del_line(self):
220 """Forget about the previous line, do not commit it."""
221 self.prev_line = None
222 def del_blank_line(self):
223 """Forget about the previous line if it is a blank line."""
224 if self.prev_line != None and not self.prev_line.strip():
225 self.prev_line = None
226 def finish(self):
227 """Call this when you're finished with populating content."""
228 if self.prev_line != None:
229 print >> self, self.prev_line
230 self.prev_line = None
231
Johnny Chen14097802011-04-28 21:31:18 +0000232# The new content will have the iteration protocol defined for our lldb objects.
Johnny Chenebd63b22011-07-16 21:15:39 +0000233new_content = NewContent()
Johnny Chen14097802011-04-28 21:31:18 +0000234
235with open(output_name, 'r') as f_in:
236 content = f_in.read()
237
238# The pattern for recognizing the beginning of an SB class definition.
239class_pattern = re.compile("^class (SB.*)\(_object\):$")
240
241# The pattern for recognizing the beginning of the __init__ method definition.
242init_pattern = re.compile("^ def __init__\(self, \*args\):")
243
Johnny Chen2077f0d2011-05-17 22:14:39 +0000244# The pattern for recognizing the beginning of the IsValid method definition.
Peter Collingbournef2084532011-06-14 03:55:41 +0000245isvalid_pattern = re.compile("^ def IsValid\(")
Johnny Chen2077f0d2011-05-17 22:14:39 +0000246
Johnny Chena79a21c2011-05-16 20:31:18 +0000247# These define the states of our finite state machine.
Johnny Chen14097802011-04-28 21:31:18 +0000248NORMAL = 0
249DEFINING_ITERATOR = 1
Johnny Chen3a3d6592011-04-29 19:03:02 +0000250DEFINING_EQUALITY = 2
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000251CLEANUP_DOCSTRING = 4
Johnny Chen14097802011-04-28 21:31:18 +0000252
253# The lldb_iter_def only needs to be inserted once.
254lldb_iter_defined = False;
255
Johnny Chen2077f0d2011-05-17 22:14:39 +0000256# Our FSM begins its life in the NORMAL state, and transitions to the
257# DEFINING_ITERATOR and/or DEFINING_EQUALITY state whenever it encounters the
258# beginning of certain class definitions, see dictionaries 'd' and 'e' above.
259#
260# Note that the two states DEFINING_ITERATOR and DEFINING_EQUALITY are
261# orthogonal in that our FSM can be in one, the other, or both states at the
262# same time. During such time, the FSM is eagerly searching for the __init__
263# method definition in order to insert the appropriate method(s) into the lldb
264# module.
265#
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000266# The state CLEANUP_DOCSTRING can be entered from either the NORMAL or the
267# DEFINING_ITERATOR/EQUALITY states. While in this state, the FSM is fixing/
268# cleaning the Python docstrings generated by the swig docstring features.
269#
Johnny Chenb72d1772011-05-24 22:29:49 +0000270# The FSM, in all possible states, also checks the current input for IsValid()
271# definition, and inserts a __nonzero__() method definition to implement truth
272# value testing and the built-in operation bool().
Johnny Chen14097802011-04-28 21:31:18 +0000273state = NORMAL
274for line in content.splitlines():
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000275 # Handle the state transition into CLEANUP_DOCSTRING state as it is possible
276 # to enter this state from either NORMAL or DEFINING_ITERATOR/EQUALITY.
277 #
278 # If ' """' is the sole line, prepare to transition to the
279 # CLEANUP_DOCSTRING state or out of it.
280 if line == toggle_docstring_cleanup_line:
281 if state & CLEANUP_DOCSTRING:
Johnny Chenebd63b22011-07-16 21:15:39 +0000282 # Special handling of the trailing blank line right before the '"""'
283 # end docstring marker.
284 new_content.del_blank_line()
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000285 state ^= CLEANUP_DOCSTRING
286 else:
287 state |= CLEANUP_DOCSTRING
Johnny Chen09e0a422011-07-01 22:14:07 +0000288
Johnny Chen14097802011-04-28 21:31:18 +0000289 if state == NORMAL:
290 match = class_pattern.search(line)
Johnny Chen2077f0d2011-05-17 22:14:39 +0000291 # Inserts the lldb_iter() definition before the first class definition.
Johnny Chen14097802011-04-28 21:31:18 +0000292 if not lldb_iter_defined and match:
Johnny Chenebd63b22011-07-16 21:15:39 +0000293 new_content.add_line(lldb_iter_def)
Johnny Chen14097802011-04-28 21:31:18 +0000294 lldb_iter_defined = True
Johnny Chen2077f0d2011-05-17 22:14:39 +0000295
296 # If we are at the beginning of the class definitions, prepare to
297 # transition to the DEFINING_ITERATOR/DEFINING_EQUALITY state for the
298 # right class names.
Johnny Chen3a3d6592011-04-29 19:03:02 +0000299 if match:
Johnny Chen14097802011-04-28 21:31:18 +0000300 cls = match.group(1)
Johnny Chen3a3d6592011-04-29 19:03:02 +0000301 if cls in d:
302 # Adding support for iteration for the matched SB class.
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000303 state |= DEFINING_ITERATOR
Johnny Chen3a3d6592011-04-29 19:03:02 +0000304 if cls in e:
305 # Adding support for eq and ne for the matched SB class.
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000306 state |= DEFINING_EQUALITY
307
Johnny Chen533ed2f2011-07-15 20:46:19 +0000308 if (state & DEFINING_ITERATOR) or (state & DEFINING_EQUALITY):
Johnny Chen14097802011-04-28 21:31:18 +0000309 match = init_pattern.search(line)
310 if match:
311 # We found the beginning of the __init__ method definition.
Johnny Chen3a3d6592011-04-29 19:03:02 +0000312 # This is a good spot to insert the iter and/or eq-ne support.
Johnny Chen14097802011-04-28 21:31:18 +0000313 #
314 # But note that SBTarget has two types of iterations.
315 if cls == "SBTarget":
Johnny Chenebd63b22011-07-16 21:15:39 +0000316 new_content.add_line(module_iter % (d[cls]['module']))
317 new_content.add_line(breakpoint_iter % (d[cls]['breakpoint']))
Johnny Chen14097802011-04-28 21:31:18 +0000318 else:
Johnny Chen3a3d6592011-04-29 19:03:02 +0000319 if (state & DEFINING_ITERATOR):
Johnny Chenebd63b22011-07-16 21:15:39 +0000320 new_content.add_line(iter_def % d[cls])
321 new_content.add_line(len_def % d[cls][0])
Johnny Chen3a3d6592011-04-29 19:03:02 +0000322 if (state & DEFINING_EQUALITY):
Johnny Chenebd63b22011-07-16 21:15:39 +0000323 new_content.add_line(eq_def % (cls, list_to_frag(e[cls])))
324 new_content.add_line(ne_def)
Johnny Chena2f86e82011-04-29 19:19:13 +0000325
Johnny Chenfbebbc92011-07-25 19:32:35 +0000326 # This special purpose iterator is for SBValue only!!!
327 if cls == "SBValue":
328 new_content.add_line(linked_list_iter_def)
329
Johnny Chena2f86e82011-04-29 19:19:13 +0000330 # Next state will be NORMAL.
331 state = NORMAL
Johnny Chen14097802011-04-28 21:31:18 +0000332
Johnny Chen533ed2f2011-07-15 20:46:19 +0000333 if (state & CLEANUP_DOCSTRING):
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000334 # Cleanse the lldb.py of the autodoc'ed residues.
335 if c_ifdef_swig in line or c_endif_swig in line:
336 continue
Johnny Chenebd63b22011-07-16 21:15:39 +0000337 # As well as the comment marker line.
338 if c_comment_marker in line:
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000339 continue
Johnny Chenebd63b22011-07-16 21:15:39 +0000340
Johnny Chen533ed2f2011-07-15 20:46:19 +0000341 # Also remove the '\a ' and '\b 'substrings.
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000342 line = line.replace('\a ', '')
Johnny Chen533ed2f2011-07-15 20:46:19 +0000343 line = line.replace('\b ', '')
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000344 # And the leading '///' substring.
345 doxygen_comment_match = doxygen_comment_start.match(line)
346 if doxygen_comment_match:
347 line = line.replace(doxygen_comment_match.group(1), '', 1)
348
Johnny Chen37811372011-07-06 21:55:45 +0000349 line = char_to_str_xform(line)
350
Johnny Chenf6ce70a2011-07-03 19:55:50 +0000351 # Note that the transition out of CLEANUP_DOCSTRING is handled at the
352 # beginning of this function already.
353
Johnny Chen37811372011-07-06 21:55:45 +0000354 # This deals with one-liner docstring, for example, SBThread.GetName:
355 # """GetName(self) -> char""".
356 if one_liner_docstring_pattern.match(line):
357 line = char_to_str_xform(line)
358
Johnny Chenb72d1772011-05-24 22:29:49 +0000359 # Look for 'def IsValid(*args):', and once located, add implementation
360 # of truth value testing for this object by delegation.
361 if isvalid_pattern.search(line):
Johnny Chenebd63b22011-07-16 21:15:39 +0000362 new_content.add_line(nonzero_def)
Johnny Chenb72d1772011-05-24 22:29:49 +0000363
Johnny Chen6ea16c72011-05-02 17:53:04 +0000364 # Pass the original line of content to new_content.
Johnny Chenebd63b22011-07-16 21:15:39 +0000365 new_content.add_line(line)
366
367# We are finished with recording new content.
368new_content.finish()
369
Johnny Chen14097802011-04-28 21:31:18 +0000370with open(output_name, 'w') as f_out:
371 f_out.write(new_content.getvalue())
372 f_out.write("debugger_unique_id = 0\n")
373 f_out.write("SBDebugger.Initialize()\n")