1//===-- SearchFilter.h ------------------------------------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef liblldb_SearchFilter_h_
11#define liblldb_SearchFilter_h_
12
13// C Includes
14// C++ Includes
15// Other libraries and framework includes
16// Project includes
17#include "lldb/lldb-private.h"
18#include "lldb/Core/FileSpecList.h"
19
20namespace lldb_private {
21
22//----------------------------------------------------------------------
23/// @class Searcher SearchFilter.h "lldb/Core/SearchFilter.h"
24/// @brief Class that is driven by the SearchFilter to search the
25/// SymbolContext space of the target program.
26//----------------------------------------------------------------------
27
28//----------------------------------------------------------------------
29/// General Outline:
30/// Provides the callback and search depth for the SearchFilter search.
31//----------------------------------------------------------------------
32
33class Searcher
34{
35public:
36    typedef enum {
37        eCallbackReturnStop = 0,  // Stop the iteration
38        eCallbackReturnContinue,  // Continue the iteration
39        eCallbackReturnPop        // Pop one level up and continue iterating
40    } CallbackReturn;
41
42    typedef enum {
43        eDepthTarget,
44        eDepthModule,
45        eDepthCompUnit,
46        eDepthFunction,
47        eDepthBlock,
48        eDepthAddress
49    } Depth;
50
51    Searcher ();
52
53    virtual ~Searcher ();
54
55    virtual CallbackReturn
56    SearchCallback (SearchFilter &filter,
57                    SymbolContext &context,
58                    Address *addr,
59                    bool complete) = 0;
60
61    virtual Depth
62    GetDepth () = 0;
63
64    //------------------------------------------------------------------
65    /// Prints a canonical description for the searcher to the stream \a s.
66    ///
67    /// @param[in] s
68    ///   Stream to which the output is copied.
69    //------------------------------------------------------------------
70    virtual void
71    GetDescription(Stream *s);
72};
73
74//----------------------------------------------------------------------
75/// @class SearchFilter SearchFilter.h "lldb/Core/SearchFilter.h"
76/// @brief Class descends through the SymbolContext space of the target,
77/// applying a filter at each stage till it reaches the depth specified by
78/// the GetDepth method of the searcher, and calls its callback at that point.
79//----------------------------------------------------------------------
80
81//----------------------------------------------------------------------
82/// General Outline:
83/// Provides the callback and search depth for the SearchFilter search.
84///
85/// The search is done by cooperation between the search filter and the searcher.
86/// The search filter does the heavy work of recursing through the SymbolContext
87/// space of the target program's symbol space.  The Searcher specifies the depth
88/// at which it wants its callback to be invoked.  Note that since the resolution
89/// of the Searcher may be greater than that of the SearchFilter, before the
90/// Searcher qualifies an address it should pass it to "AddressPasses."
91/// The default implementation is "Everything Passes."
92//----------------------------------------------------------------------
93
94class SearchFilter
95{
96public:
97
98    //------------------------------------------------------------------
99    /// The basic constructor takes a Target, which gives the space to search.
100    ///
101    /// @param[in] target
102    ///    The Target that provides the module list to search.
103    //------------------------------------------------------------------
104    SearchFilter (const lldb::TargetSP &target_sp);
105
106    SearchFilter (const SearchFilter& rhs);
107
108    virtual
109    ~SearchFilter ();
110
111    const SearchFilter&
112    operator=(const SearchFilter& rhs);
113
114    //------------------------------------------------------------------
115    /// Call this method with a file spec to see if that spec passes the filter.
116    ///
117    /// @param[in] spec
118    ///    The file spec to check against the filter.
119    /// @return
120    ///    \b true if \a spec passes, and \b false otherwise.
121    //------------------------------------------------------------------
122    virtual bool
123    ModulePasses (const FileSpec &spec);
124
125    //------------------------------------------------------------------
126    /// Call this method with a Module to see if that module passes the filter.
127    ///
128    /// @param[in] module
129    ///    The Module to check against the filter.
130    ///
131    /// @return
132    ///    \b true if \a module passes, and \b false otherwise.
133    //------------------------------------------------------------------
134    virtual bool
135    ModulePasses (const lldb::ModuleSP &module_sp);
136
137    //------------------------------------------------------------------
138    /// Call this method with a Address to see if \a address passes the filter.
139    ///
140    /// @param[in] addr
141    ///    The address to check against the filter.
142    ///
143    /// @return
144    ///    \b true if \a address passes, and \b false otherwise.
145    //------------------------------------------------------------------
146    virtual bool
147    AddressPasses (Address &addr);
148
149    //------------------------------------------------------------------
150    /// Call this method with a FileSpec to see if \a file spec passes the filter
151    /// as the name of a compilation unit.
152    ///
153    /// @param[in] fileSpec
154    ///    The file spec to check against the filter.
155    ///
156    /// @return
157    ///    \b true if \a file spec passes, and \b false otherwise.
158    //------------------------------------------------------------------
159    virtual bool
160    CompUnitPasses (FileSpec &fileSpec);
161
162    //------------------------------------------------------------------
163    /// Call this method with a CompileUnit to see if \a comp unit passes the filter.
164    ///
165    /// @param[in] compUnit
166    ///    The CompileUnit to check against the filter.
167    ///
168    /// @return
169    ///    \b true if \a Comp Unit passes, and \b false otherwise.
170    //------------------------------------------------------------------
171    virtual bool
172    CompUnitPasses (CompileUnit &compUnit);
173
174    //------------------------------------------------------------------
175    /// Call this method to do the search using the Searcher.
176    ///
177    /// @param[in] searcher
178    ///    The searcher to drive with this search.
179    ///
180    //------------------------------------------------------------------
181    virtual void
182    Search (Searcher &searcher);
183
184    //------------------------------------------------------------------
185    /// Call this method to do the search using the Searcher in the module list
186    /// \a modules.
187    ///
188    /// @param[in] searcher
189    ///    The searcher to drive with this search.
190    ///
191    /// @param[in] modules
192    ///    The module list within which to restrict the search.
193    ///
194    //------------------------------------------------------------------
195    virtual void
196    SearchInModuleList (Searcher &searcher, ModuleList &modules);
197
198    //------------------------------------------------------------------
199    /// This determines which items are REQUIRED for the filter to pass.
200    /// For instance, if you are filtering by Compilation Unit, obviously
201    /// symbols that have no compilation unit can't pass  So return eSymbolContextCU
202    /// and search callbacks can then short cut the search to avoid looking at
203    /// things that obviously won't pass.
204    ///
205    /// @return
206    ///    The required elements for the search, which is an or'ed together
207    ///    set of lldb:SearchContextItem enum's.
208    ///
209    //------------------------------------------------------------------
210    virtual uint32_t
211    GetFilterRequiredItems ();
212
213    //------------------------------------------------------------------
214    /// Prints a canonical description for the search filter to the stream \a s.
215    ///
216    /// @param[in] s
217    ///   Stream to which the output is copied.
218    //------------------------------------------------------------------
219    virtual void
220    GetDescription(Stream *s);
221
222    //------------------------------------------------------------------
223    /// Standard "Dump" method.  At present it does nothing.
224    //------------------------------------------------------------------
225    virtual void
226    Dump (Stream *s) const;
227
228protected:
229
230    // These are utility functions to assist with the search iteration.  They are used by the
231    // default Search method.
232
233    Searcher::CallbackReturn
234    DoModuleIteration (const SymbolContext &context,
235                       Searcher &searcher);
236
237    Searcher::CallbackReturn
238    DoModuleIteration (const lldb::ModuleSP& module_sp,
239                       Searcher &searcher);
240
241    Searcher::CallbackReturn
242    DoCUIteration (const lldb::ModuleSP& module_sp,
243                   const SymbolContext &context,
244                   Searcher &searcher);
245
246    Searcher::CallbackReturn
247    DoFunctionIteration (Function *function,
248                         const SymbolContext &context,
249                         Searcher &searcher);
250
251    lldb::TargetSP m_target_sp;   // Every filter has to be associated with a target for
252                                  // now since you need a starting place for the search.
253};
254
255//----------------------------------------------------------------------
256/// @class SearchFilterForNonModuleSpecificSearches SearchFilter.h "lldb/Core/SearchFilter.h"
257/// @brief This is a SearchFilter that searches through all modules.  It also consults the Target::ModuleIsExcludedForNonModuleSpecificSearches.
258//----------------------------------------------------------------------
259class SearchFilterForNonModuleSpecificSearches :
260    public SearchFilter
261{
262public:
263    SearchFilterForNonModuleSpecificSearches (const lldb::TargetSP &targetSP) : SearchFilter(targetSP) {}
264    ~SearchFilterForNonModuleSpecificSearches () {}
265
266    virtual bool
267    ModulePasses (const FileSpec &module_spec);
268
269    virtual bool
270    ModulePasses (const lldb::ModuleSP &module_sp);
271};
272
273//----------------------------------------------------------------------
274/// @class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h"
275/// @brief This is a SearchFilter that restricts the search to a given module.
276//----------------------------------------------------------------------
277
278class SearchFilterByModule :
279    public SearchFilter
280{
281public:
282
283    //------------------------------------------------------------------
284    /// The basic constructor takes a Target, which gives the space to search,
285    /// and the module to restrict the search to.
286    ///
287    /// @param[in] target
288    ///    The Target that provides the module list to search.
289    ///
290    /// @param[in] module
291    ///    The Module that limits the search.
292    //------------------------------------------------------------------
293    SearchFilterByModule (const lldb::TargetSP &targetSP,
294                          const FileSpec &module);
295
296    SearchFilterByModule (const SearchFilterByModule& rhs);
297
298    virtual
299    ~SearchFilterByModule ();
300
301    const SearchFilterByModule&
302    operator=(const SearchFilterByModule& rhs);
303
304    virtual bool
305    ModulePasses (const lldb::ModuleSP &module_sp);
306
307    virtual bool
308    ModulePasses (const FileSpec &spec);
309
310    virtual bool
311    AddressPasses (Address &address);
312
313    virtual bool
314    CompUnitPasses (FileSpec &fileSpec);
315
316    virtual bool
317    CompUnitPasses (CompileUnit &compUnit);
318
319    virtual void
320    GetDescription(Stream *s);
321
322    virtual uint32_t
323    GetFilterRequiredItems ();
324
325    virtual void
326    Dump (Stream *s) const;
327
328    virtual void
329    Search (Searcher &searcher);
330
331private:
332    FileSpec m_module_spec;
333};
334
335class SearchFilterByModuleList :
336    public SearchFilter
337{
338public:
339
340    //------------------------------------------------------------------
341    /// The basic constructor takes a Target, which gives the space to search,
342    /// and the module list to restrict the search to.
343    ///
344    /// @param[in] target
345    ///    The Target that provides the module list to search.
346    ///
347    /// @param[in] module
348    ///    The Module that limits the search.
349    //------------------------------------------------------------------
350    SearchFilterByModuleList (const lldb::TargetSP &targetSP,
351                              const FileSpecList &module_list);
352
353    SearchFilterByModuleList (const SearchFilterByModuleList& rhs);
354
355    virtual
356    ~SearchFilterByModuleList ();
357
358    const SearchFilterByModuleList&
359    operator=(const SearchFilterByModuleList& rhs);
360
361    virtual bool
362    ModulePasses (const lldb::ModuleSP &module_sp);
363
364    virtual bool
365    ModulePasses (const FileSpec &spec);
366
367    virtual bool
368    AddressPasses (Address &address);
369
370    virtual bool
371    CompUnitPasses (FileSpec &fileSpec);
372
373    virtual bool
374    CompUnitPasses (CompileUnit &compUnit);
375
376    virtual void
377    GetDescription(Stream *s);
378
379    virtual uint32_t
380    GetFilterRequiredItems ();
381
382    virtual void
383    Dump (Stream *s) const;
384
385    virtual void
386    Search (Searcher &searcher);
387
388private:
389    FileSpecList m_module_spec_list;
390};
391
392class SearchFilterByModuleListAndCU :
393    public SearchFilterByModuleList
394{
395public:
396
397    //------------------------------------------------------------------
398    /// The basic constructor takes a Target, which gives the space to search,
399    /// and the module list to restrict the search to.
400    ///
401    /// @param[in] target
402    ///    The Target that provides the module list to search.
403    ///
404    /// @param[in] module
405    ///    The Module that limits the search.
406    //------------------------------------------------------------------
407    SearchFilterByModuleListAndCU (const lldb::TargetSP &targetSP,
408                                   const FileSpecList &module_list,
409                                   const FileSpecList &cu_list);
410
411    SearchFilterByModuleListAndCU (const SearchFilterByModuleListAndCU& rhs);
412
413    virtual
414    ~SearchFilterByModuleListAndCU ();
415
416    const SearchFilterByModuleListAndCU&
417    operator=(const SearchFilterByModuleListAndCU& rhs);
418
419    virtual bool
420    AddressPasses (Address &address);
421
422    virtual bool
423    CompUnitPasses (FileSpec &fileSpec);
424
425    virtual bool
426    CompUnitPasses (CompileUnit &compUnit);
427
428    virtual void
429    GetDescription(Stream *s);
430
431    virtual uint32_t
432    GetFilterRequiredItems ();
433
434    virtual void
435    Dump (Stream *s) const;
436
437    virtual void
438    Search (Searcher &searcher);
439
440private:
441    FileSpecList m_module_spec_list;
442    FileSpecList m_cu_spec_list;
443};
444
445} // namespace lldb_private
446
447#endif  // liblldb_SearchFilter_h_
448