Providing a more interesting command template for LLDB

This one actually exploits the SB API to obtain information about your inferior process

llvm-svn: 181500

lldb/examples/python/cmdtemplate.py

@@ -14,47 +14,63 @@ import commands
 import optparse
 import shlex
 
-def create_ls_options():
-    usage = "usage: %prog [options] <PATH> [PATH ...]"
-    description='''This command lets you run the /bin/ls shell command from
-within lldb. This code is designed to demonstrate the best principles that 
-should be used when creating a new LLDB command through python.
-Creating the options in a separate function allows the parser to be
-created without running the command. The usage string is generated by the
-optparse module and can be used to populate the ls.__doc__ documentation
-string in the command interpreter function prior to registering the
-command with LLDB. The allows the output of "ls --help" to exactly match
-the output of "help ls" when both commands are run from within LLDB.
+def create_framestats_options():
+    usage = "usage: %prog [options]"
+    description='''This command is meant to be an example of how to make an LLDB command that
+does something useful, follows best practices, and exploits the SB API.
+Specifically, this command computes the aggregate and average size of the variables in the current frame
+and allows you to tweak exactly which variables are to be accounted in the computation.
 '''
-    parser = optparse.OptionParser(description=description, prog='ls',usage=usage)
-    parser.add_option('-v', '--verbose', action='store_true', dest='verbose', help='display verbose debug info', default=False)
+    parser = optparse.OptionParser(description=description, prog='framestats',usage=usage)
+    parser.add_option('-i', '--in-scope', action='store_true', dest='inscope', help='in_scope_only = True', default=False)
+    parser.add_option('-a', '--arguments', action='store_true', dest='arguments', help='arguments = True', default=False)
+    parser.add_option('-l', '--locals', action='store_true', dest='locals', help='locals = True', default=False)
+    parser.add_option('-s', '--statics', action='store_true', dest='statics', help='statics = True', default=False)
     return parser
 
-def ls(debugger, command, result, dict):
+def the_framestats_command(debugger, command, result, dict):
     # Use the Shell Lexer to properly parse up command options just like a 
     # shell would
     command_args = shlex.split(command)
-    parser = create_ls_options()
+    parser = create_framestats_options()
     try:
         (options, args) = parser.parse_args(command_args)
     except:
         # if you don't handle exceptions, passing an incorrect argument to the OptionParser will cause LLDB to exit
         # (courtesy of OptParse dealing with argument errors by throwing SystemExit)
         result.SetStatus (lldb.eReturnStatusFailed)
-        return
+        return "option parsing failed" # returning a string is the same as returning an error whose description is the string
     
-    for arg in args:
-        if options.verbose:
-            result.PutCString(commands.getoutput('/bin/ls "%s"' % arg))
-        else:
-            result.PutCString(commands.getoutput('/bin/ls -lAF "%s"' % arg))
+    # in a command - the lldb.* convenience variables are not to be used
+    # and their values (if any) are undefined
+    # this is the best practice to access those objects from within a command
+    target = debugger.GetSelectedTarget()
+    process = target.GetProcess()
+    thread = process.GetSelectedThread()
+    frame = thread.GetSelectedFrame()
+    if not frame.IsValid():
+        return "no frame here"
+    # from now on, replace lldb.<thing>.whatever with <thing>.whatever
+    variables_list = frame.GetVariables(options.arguments, options.locals, options.statics, options.inscope)
+    variables_count = variables_list.GetSize()
+    if variables_count == 0:
+        result.PutCString("no variables here")
+        return
+    total_size = 0
+    for i in range(0,variables_count):
+        variable = variables_list.GetValueAtIndex(i)
+        variable_type = variable.GetType()
+        total_size = total_size + variable_type.GetByteSize()
+    average_size = float(total_size) / variables_count
+    result.PutCString("Your frame has %d variables. Their total size is %d bytes. The average size is %f bytes" % (variables_count,total_size,average_size))
+    # not returning anything is askin to returning success
 
 def __lldb_init_module (debugger, dict):
     # This initializer is being run from LLDB in the embedded command interpreter    
     # Make the options so we can generate the help text for the new LLDB 
     # command line command prior to registering it with LLDB below
-    parser = create_ls_options()
-    ls.__doc__ = parser.format_help()
+    parser = create_framestats_options()
+    the_framestats_command.__doc__ = parser.format_help()
     # Add any commands contained in this module to LLDB
-    debugger.HandleCommand('command script add -f cmdtemplate.ls ls')
-    print 'The "ls" command has been installed, type "help ls" or "ls --help" for detailed help.'
+    debugger.HandleCommand('command script add -f cmdtemplate.the_framestats_command framestats')
+    print 'The "framestats" command has been installed, type "help framestats" or "framestats --help" for detailed help.'

lldb/www/python-reference.html

@@ -448,7 +448,7 @@ total 365848
 -rw-r--r--@  1 someuser  wheel         6148 Jan 19 17:27 .DS_Store
 -rw-------   1 someuser  wheel         7331 Jan 19 15:37 crash.log
 </tt></pre></code>
-        <p>A template has been created in the source repository that can help you to create
+        <p>A more interesting template has been created in the source repository that can help you to create
             lldb command quickly:</p>
         <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/cmdtemplate.py">cmdtemplate.py</a>
 		<p>