blob: 0adf888b9cc842afc1540082a24623cccd219f54 [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
13# '#endif' and the '#ifdef SWIG' lines.
14#
Johnny Chen14097802011-04-28 21:31:18 +000015# It also calls SBDebugger.Initialize() to initialize the lldb debugger
16# subsystem.
17#
18
19import sys, re, StringIO
20
21if len (sys.argv) != 2:
22 output_name = "./lldb.py"
23else:
24 output_name = sys.argv[1] + "/lldb.py"
25
26# print "output_name is '" + output_name + "'"
27
Johnny Chen09e0a422011-07-01 22:14:07 +000028# Residues to be removed.
29c_endif_swig = "#endif"
30c_ifdef_swig = "#ifdef SWIG"
Johnny Chen2c77fa42011-07-02 20:01:09 +000031c_comment_marker = "//------------"
32# The pattern for recognizing the doxygen comment block line.
33doxygen_comment_start = re.compile("^\s*( /// ?)")
Johnny Chen09e0a422011-07-01 22:14:07 +000034
Johnny Chen14097802011-04-28 21:31:18 +000035#
Johnny Chenec5e0a22011-06-01 18:40:11 +000036# lldb_iter() should appear before our first SB* class definition.
Johnny Chen14097802011-04-28 21:31:18 +000037#
38lldb_iter_def = '''
39# ===================================
40# Iterator for lldb container objects
41# ===================================
42def lldb_iter(obj, getsize, getelem):
43 """A generator adaptor to support iteration for lldb container objects."""
44 size = getattr(obj, getsize)
45 elem = getattr(obj, getelem)
46 for i in range(size()):
47 yield elem(i)
48
Johnny Chen81422202011-06-01 19:21:08 +000049# ==============================================================================
50# The modify-python-lldb.py script is responsible for post-processing this SWIG-
51# generated lldb.py module. It is responsible for adding the above lldb_iter()
52# function definition as well as the supports, in the following, for iteration
53# protocol: __iter__, rich comparison methods: __eq__ and __ne__, truth value
54# testing (and built-in operation bool()): __nonzero__, and built-in function
55# len(): __len__.
56# ==============================================================================
Johnny Chen14097802011-04-28 21:31:18 +000057'''
58
Johnny Chen14097802011-04-28 21:31:18 +000059# This supports the iteration protocol.
Johnny Chen14097802011-04-28 21:31:18 +000060iter_def = " def __iter__(self): return lldb_iter(self, '%s', '%s')"
61module_iter = " def module_iter(self): return lldb_iter(self, '%s', '%s')"
62breakpoint_iter = " def breakpoint_iter(self): return lldb_iter(self, '%s', '%s')"
Johnny Chen2077f0d2011-05-17 22:14:39 +000063
Johnny Chena79a21c2011-05-16 20:31:18 +000064# Called to implement the built-in function len().
65# Eligible objects are those containers with unambiguous iteration support.
Johnny Chena79a21c2011-05-16 20:31:18 +000066len_def = " def __len__(self): return self.%s()"
Johnny Chen2077f0d2011-05-17 22:14:39 +000067
Johnny Chen3a3d6592011-04-29 19:03:02 +000068# This supports the rich comparison methods of __eq__ and __ne__.
Johnny Chen7616cb92011-05-02 19:05:52 +000069eq_def = " def __eq__(self, other): return isinstance(other, %s) and %s"
Johnny Chen3a3d6592011-04-29 19:03:02 +000070ne_def = " def __ne__(self, other): return not self.__eq__(other)"
Johnny Chen14097802011-04-28 21:31:18 +000071
Johnny Chen2077f0d2011-05-17 22:14:39 +000072# Called to implement truth value testing and the built-in operation bool();
73# should return False or True, or their integer equivalents 0 or 1.
74# Delegate to self.IsValid() if it is defined for the current lldb object.
75nonzero_def = " def __nonzero__(self): return self.IsValid()"
76
Johnny Chen14097802011-04-28 21:31:18 +000077#
Johnny Chena6303ef2011-05-24 22:53:03 +000078# This dictionary defines a mapping from classname to (getsize, getelem) tuple.
Johnny Chen14097802011-04-28 21:31:18 +000079#
80d = { 'SBBreakpoint': ('GetNumLocations', 'GetLocationAtIndex'),
81 'SBCompileUnit': ('GetNumLineEntries', 'GetLineEntryAtIndex'),
82 'SBDebugger': ('GetNumTargets', 'GetTargetAtIndex'),
83 'SBModule': ('GetNumSymbols', 'GetSymbolAtIndex'),
84 'SBProcess': ('GetNumThreads', 'GetThreadAtIndex'),
85 'SBThread': ('GetNumFrames', 'GetFrameAtIndex'),
86
87 'SBInstructionList': ('GetSize', 'GetInstructionAtIndex'),
88 'SBStringList': ('GetSize', 'GetStringAtIndex',),
89 'SBSymbolContextList': ('GetSize', 'GetContextAtIndex'),
90 'SBValueList': ('GetSize', 'GetValueAtIndex'),
91
92 'SBType': ('GetNumberChildren', 'GetChildAtIndex'),
93 'SBValue': ('GetNumChildren', 'GetChildAtIndex'),
94
Johnny Chen08477f52011-05-24 22:57:42 +000095 # SBTarget needs special processing, see below.
Johnny Chen14097802011-04-28 21:31:18 +000096 'SBTarget': {'module': ('GetNumModules', 'GetModuleAtIndex'),
97 'breakpoint': ('GetNumBreakpoints', 'GetBreakpointAtIndex')
98 }
99 }
100
Johnny Chen3a3d6592011-04-29 19:03:02 +0000101#
Johnny Chen7616cb92011-05-02 19:05:52 +0000102# This dictionary defines a mapping from classname to equality method name(s).
Johnny Chen3a3d6592011-04-29 19:03:02 +0000103#
Johnny Chen694cfd02011-06-09 22:04:56 +0000104e = { 'SBAddress': ['GetFileAddress', 'GetModule'],
105 'SBBreakpoint': ['GetID'],
Johnny Chen7616cb92011-05-02 19:05:52 +0000106 'SBFileSpec': ['GetFilename', 'GetDirectory'],
107 'SBModule': ['GetFileSpec', 'GetUUIDString']
108 }
109
110def list_to_frag(list):
111 """Transform a list to equality program fragment.
112
113 For example, ['GetID'] is transformed to 'self.GetID() == other.GetID()',
114 and ['GetFilename', 'GetDirectory'] to 'self.GetFilename() == other.GetFilename()
115 and self.GetDirectory() == other.GetDirectory()'.
116 """
117 if not list:
118 raise Exception("list should be non-empty")
119 frag = StringIO.StringIO()
120 for i in range(len(list)):
121 if i > 0:
122 frag.write(" and ")
123 frag.write("self.{0}() == other.{0}()".format(list[i]))
124 return frag.getvalue()
Johnny Chen3a3d6592011-04-29 19:03:02 +0000125
Johnny Chen14097802011-04-28 21:31:18 +0000126# The new content will have the iteration protocol defined for our lldb objects.
127new_content = StringIO.StringIO()
128
129with open(output_name, 'r') as f_in:
130 content = f_in.read()
131
132# The pattern for recognizing the beginning of an SB class definition.
133class_pattern = re.compile("^class (SB.*)\(_object\):$")
134
135# The pattern for recognizing the beginning of the __init__ method definition.
136init_pattern = re.compile("^ def __init__\(self, \*args\):")
137
Johnny Chen2077f0d2011-05-17 22:14:39 +0000138# The pattern for recognizing the beginning of the IsValid method definition.
Peter Collingbournef2084532011-06-14 03:55:41 +0000139isvalid_pattern = re.compile("^ def IsValid\(")
Johnny Chen2077f0d2011-05-17 22:14:39 +0000140
Johnny Chena79a21c2011-05-16 20:31:18 +0000141# These define the states of our finite state machine.
Johnny Chen14097802011-04-28 21:31:18 +0000142NORMAL = 0
143DEFINING_ITERATOR = 1
Johnny Chen3a3d6592011-04-29 19:03:02 +0000144DEFINING_EQUALITY = 2
Johnny Chen14097802011-04-28 21:31:18 +0000145
146# The lldb_iter_def only needs to be inserted once.
147lldb_iter_defined = False;
148
Johnny Chen2077f0d2011-05-17 22:14:39 +0000149# Our FSM begins its life in the NORMAL state, and transitions to the
150# DEFINING_ITERATOR and/or DEFINING_EQUALITY state whenever it encounters the
151# beginning of certain class definitions, see dictionaries 'd' and 'e' above.
152#
153# Note that the two states DEFINING_ITERATOR and DEFINING_EQUALITY are
154# orthogonal in that our FSM can be in one, the other, or both states at the
155# same time. During such time, the FSM is eagerly searching for the __init__
156# method definition in order to insert the appropriate method(s) into the lldb
157# module.
158#
Johnny Chenb72d1772011-05-24 22:29:49 +0000159# The FSM, in all possible states, also checks the current input for IsValid()
160# definition, and inserts a __nonzero__() method definition to implement truth
161# value testing and the built-in operation bool().
Johnny Chen14097802011-04-28 21:31:18 +0000162state = NORMAL
163for line in content.splitlines():
Johnny Chen09e0a422011-07-01 22:14:07 +0000164 # Cleanse the lldb.py of the autodoc'ed residues.
165 if c_ifdef_swig in line or c_endif_swig in line:
166 continue
Johnny Chen2c77fa42011-07-02 20:01:09 +0000167 # As well as the comment marker line.
168 if c_comment_marker in line:
169 continue
Johnny Chen09e0a422011-07-01 22:14:07 +0000170 # Also remove the '\a ' substrings.
171 line = line.replace('\a ', '')
Johnny Chen2c77fa42011-07-02 20:01:09 +0000172 # And the leading '///' substring.
173 doxygen_comment_match = doxygen_comment_start.match(line)
174 if doxygen_comment_match:
175 line = line.replace(doxygen_comment_match.group(1), '', 1)
Johnny Chen09e0a422011-07-01 22:14:07 +0000176
Johnny Chen14097802011-04-28 21:31:18 +0000177 if state == NORMAL:
178 match = class_pattern.search(line)
Johnny Chen2077f0d2011-05-17 22:14:39 +0000179 # Inserts the lldb_iter() definition before the first class definition.
Johnny Chen14097802011-04-28 21:31:18 +0000180 if not lldb_iter_defined and match:
181 print >> new_content, lldb_iter_def
182 lldb_iter_defined = True
Johnny Chen2077f0d2011-05-17 22:14:39 +0000183
184 # If we are at the beginning of the class definitions, prepare to
185 # transition to the DEFINING_ITERATOR/DEFINING_EQUALITY state for the
186 # right class names.
Johnny Chen3a3d6592011-04-29 19:03:02 +0000187 if match:
Johnny Chen14097802011-04-28 21:31:18 +0000188 cls = match.group(1)
Johnny Chen3a3d6592011-04-29 19:03:02 +0000189 if cls in d:
190 # Adding support for iteration for the matched SB class.
191 state = (state | DEFINING_ITERATOR)
192 if cls in e:
193 # Adding support for eq and ne for the matched SB class.
194 state = (state | DEFINING_EQUALITY)
195 elif state > NORMAL:
Johnny Chen14097802011-04-28 21:31:18 +0000196 match = init_pattern.search(line)
197 if match:
198 # We found the beginning of the __init__ method definition.
Johnny Chen3a3d6592011-04-29 19:03:02 +0000199 # This is a good spot to insert the iter and/or eq-ne support.
Johnny Chen14097802011-04-28 21:31:18 +0000200 #
201 # But note that SBTarget has two types of iterations.
202 if cls == "SBTarget":
203 print >> new_content, module_iter % (d[cls]['module'])
204 print >> new_content, breakpoint_iter % (d[cls]['breakpoint'])
205 else:
Johnny Chen3a3d6592011-04-29 19:03:02 +0000206 if (state & DEFINING_ITERATOR):
207 print >> new_content, iter_def % d[cls]
Johnny Chena79a21c2011-05-16 20:31:18 +0000208 print >> new_content, len_def % d[cls][0]
Johnny Chen3a3d6592011-04-29 19:03:02 +0000209 if (state & DEFINING_EQUALITY):
Johnny Chen7616cb92011-05-02 19:05:52 +0000210 print >> new_content, eq_def % (cls, list_to_frag(e[cls]))
Johnny Chen3a3d6592011-04-29 19:03:02 +0000211 print >> new_content, ne_def
Johnny Chena2f86e82011-04-29 19:19:13 +0000212
213 # Next state will be NORMAL.
214 state = NORMAL
Johnny Chen14097802011-04-28 21:31:18 +0000215
Johnny Chenb72d1772011-05-24 22:29:49 +0000216 # Look for 'def IsValid(*args):', and once located, add implementation
217 # of truth value testing for this object by delegation.
218 if isvalid_pattern.search(line):
219 print >> new_content, nonzero_def
220
Johnny Chen6ea16c72011-05-02 17:53:04 +0000221 # Pass the original line of content to new_content.
Johnny Chen14097802011-04-28 21:31:18 +0000222 print >> new_content, line
223
224with open(output_name, 'w') as f_out:
225 f_out.write(new_content.getvalue())
226 f_out.write("debugger_unique_id = 0\n")
227 f_out.write("SBDebugger.Initialize()\n")