[lldb] Add lldb.find helper function

[kastiglione]

Summary

Add lldb.find(), a function for interactive lookup and discovery of SB API.

From the lldb console, this function can be used as follows:

(lldb) script lldb.find("register")
lldb.SBFrame.FindRegister
lldb.SBFrame.GetRegisters
lldb.SBFrame.get_registers_access
lldb.SBFrame.register
lldb.SBFrame.registers

(lldb) sc lldb.find("Disassemble")
Help on function Disassemble in lldb.SBFrame:

lldb.SBFrame.Disassemble = Disassemble(self) -> 'char const *'
    Disassemble(SBFrame self) -> char const *

In the first case, multiple matches were printed. In the second case, only one
match was found, and so its help() documentation was printed.

The results compose with the builtin help() function:

(lldb) sc help(lldb.SBFrame.FindRegister)
...

If called often enough, a command regex can come in handy:

command regex findapi
s/(.+)/script lldb.find("%1")/

Which allows it to be called as findapi register.

[jasonmolenda]

Nice. tbh when I'm SB API scripting, I am often sitting in include/lldb/API and grepping for keywords, because I can't remember exactly which class provides the API, or what arguments it takes or whatever.

[mib]

LGTM! Could you add a little test to exercise the command ?

[kastiglione]

@jasonmolenda one advantage this has over grepping is that the python specific extensions to SB are visible.

[kastiglione]

lldb/bindings/python/python-extensions.swig

528–533

oh, I need to figure out the right way to manage imports in this swig extension. It seems that the re module is used (as a default argument) before importing it, and yet this code works.

[mib]

lldb/bindings/python/python-extensions.swig

528–533

Can't you just import it after the %pythoncode %{ statement instead of doing it in the function ?

[kastiglione]

lldb/bindings/python/python-extensions.swig

528–533

That's what I plan to try. I figure it's best to put a %pythoncode %{ at the top of the file, where all imports can go, like a normal source file.

[mib]

lldb/bindings/python/python-extensions.swig

528–533

👍🏼

[jasonmolenda]

In D120292#3338155, @kastiglione wrote:

@jasonmolenda one advantage this has over grepping is that the python specific extensions to SB are visible.

That's true too. I mostly meant my comment as in, "I find this feature very helpful when writing SB API python, and this provides it to people who don't have an lldb checkout sitting around".

[JDevlieghere]

This is really great, this is going to save me a lot of time.

I wonder if we should take this even further and make it a first class command in lldb, similar to apropos. (I wouldn't make it part of apropos, because it can already be overwhelming.) By making it its own command, we can have the same command for all the supported scripting languages. Similar to script it would look at the current scripting language by default, but you could also search other supported language with a flag. I think the implementation could remain the same. Every script interpreter plugin could have a find method that it implements (or doesn't). For the Python case, it could call the find command you have here.

What do you think?

[kastiglione]

It's too bad script doesn't have subcommands, because that might have been a natural place for such a command. Are there any commands you think this could be added? Or would this have to be a new top level command? A new top-level command seems unfortunate.

Speaking of apropos, this tool could have an apropos-like mode where it also searches docstrings in addition to method/property names. I am not sure how useful that would be, but it's worth mentioning.

[jingham]

Could you use help --scripting (help -s) or maybe help --api? Then you could also do apropos -s if you ended up adding an apropos feature in the script interface, which would be consistent and fairly discoverable. Then for folks that used it all the time they could alias it to something shorter (though h -s isn't really so bad...)

In D120292#3343566, @kastiglione wrote:

It's too bad script doesn't have subcommands, because that might have been a natural place for such a command. Are there any commands you think this could be added? Or would this have to be a new top level command? A new top-level command seems unfortunate.

Speaking of apropos, this tool could have an apropos-like mode where it also searches docstrings in addition to method/property names. I am not sure how useful that would be, but it's worth mentioning.

[JDevlieghere]

I like Jim's suggestion

[mib]

In D120292#3346030, @JDevlieghere wrote:

I like Jim's suggestion

Same same !

[mib]

Jim's suggestion made me think that if we make a subcommand for this, it would be nice to have some completion handling. I know it would probably require you to move away from the python function but this is just a suggestion for later improvements.

lldb/bindings/python/python-extensions.swig

def __eq__(self, other):
                 other_val = other.sbvalue.GetValueAsUnsigned(other_err)
                 if other_err.fail:
                         raise ValueError("unable to extract value of other")
                 return self_val == other_val
         raise TypeError("Unknown type %s, No equality operation defined." % str(type(other)))
 
     def __ne__(self, other):
         return not self.__eq__(other)
-%}
 
-%pythoncode %{
+
+def find(pattern, flags=re.I):
+    """
+    Find matching SB methods/properties. See also Python's builtin `help()`.
+    """
+    import lldb
+    import re
+
+    regex = re.compile(pattern, flags)
+
+    # Gather matching methods and properties.
+    methods = []
+
+    for attr in dir(lldb):
+        value = getattr(lldb, attr)
+        if not isinstance(value, type):
+            continue
+
+        class_name = attr
+        class_type = value
+        for method_name in dir(class_type):
+            if regex.search(method_name):
+                methods.append(f"lldb.{class_name}.{method_name}")
+
+    if len(methods) == 1:
+        # For one match, print its help.
+        help(methods[0])
+        return
+
+    # Print the name of each matching method or property.
+    print(*methods, sep="\n")
+
 
 class SBSyntheticValueProvider(object):
     def __init__(self,valobj):
         pass
 
     def num_children(self):
         return 0
 
     def get_child_index(self,name):
         return None
 
     def get_child_at_index(self,idx):
         return None
 
     def update(self):
         pass
 
     def has_children(self):
         return False
 
 
-%}
-
-%pythoncode %{
-
 # given an lldb.SBBasicType it returns a tuple
 # (is_numeric, is_signed)
 # the value of is_signed is undefined if is_numeric == false
 def is_numeric_type(basic_type):
     if basic_type == eBasicTypeInvalid: return (False,False)
     if basic_type == eBasicTypeVoid: return (False,False)
     if basic_type == eBasicTypeChar: return (True,False)
     if basic_type == eBasicTypeSignedChar: return (True,True)