Add the ability to define custom completers to the parsed_cmd templat… · llvm/llvm-project@04b443e (original) (raw)

`@@ -551,7 +551,7 @@ command definition form can't do the right thing.

551

`Since lldb 3.7, Python commands can also be implemented by means of a class

552

`which should implement the following interface:

553

554

.. code-block:: python

555

556

`class CommandObjectType:

557

`def init(self, debugger, internal_dict):

`@@ -586,20 +586,193 @@ which should implement the following interface:

586

`As a convenience, you can treat the result object as a Python file object, and

587

`say

588

589

.. code-block:: python

590

591

`print >>result, "my command does lots of cool stuff"

592

593

`SBCommandReturnObject and SBStream both support this file-like behavior by

594

`providing write() and flush() calls at the Python layer.

595

596

The commands that are added using this class definition are what lldb calls

597

"raw" commands. The command interpreter doesn't attempt to parse the command,

598

doesn't handle option values, neither generating help for them, or their

599

completion. Raw commands are useful when the arguments passed to the command

600

are unstructured, and having to protect them against lldb command parsing would

601

be onerous. For instance, "expr" is a raw command.

602

+

603

You can also add scripted commands that implement the "parsed command", where

604

the options and their types are specified, as well as the argument and argument

605

types. These commands look and act like the majority of lldb commands, and you

606

can also add custom completions for the options and/or the arguments if you have

607

special needs.

608

+

609

The easiest way to do this is to derive your new command from the lldb.ParsedCommand

610

class. That responds in the same way to the help & repeat command interfaces, and

611

provides some convenience methods, and most importantly an LLDBOptionValueParser,

612

accessed throught lldb.ParsedCommand.get_parser(). The parser is used to set

613

your command definitions, and to retrieve option values in the call method.

614

+

615

To set up the command definition, implement the ParsedCommand abstract method:

616

+

617

.. code-block:: python

618

+

619

def setup_command_definition(self):

620

+

621

This is called when your command is added to lldb. In this method you add the

622

options and their types, the option help strings, etc. to the command using the API:

623

+

624

.. code-block:: python

625

+

626

def add_option(self, short_option, long_option, help, default,

627

dest = None, required=False, groups = None,

628

value_type=lldb.eArgTypeNone, completion_type=None,

629

enum_values=None):

630

"""

631

short_option: one character, must be unique, not required

632

long_option: no spaces, must be unique, required

633

help: a usage string for this option, will print in the command help

634

default: the initial value for this option (if it has a value)

635

dest: the name of the property that gives you access to the value for

636

this value. Defaults to the long option if not provided.

637

required: if true, this option must be provided or the command will error out

638

groups: Which "option groups" does this option belong to. This can either be

639

a simple list (e.g. [1, 3, 4, 5]) or you can specify ranges by sublists:

640

so [1, [3,5]] is the same as [1, 3, 4, 5].

641

value_type: one of the lldb.eArgType enum values. Some of the common arg

642

types also have default completers, which will be applied automatically.

643

completion_type: currently these are values form the lldb.CompletionType enum. If

644

you need custom completions, implement handle_option_argument_completion.

645

enum_values: An array of duples: ["element_name", "element_help"]. If provided,

646

only one of the enum elements is allowed. The value will be the

647

element_name for the chosen enum element as a string.

648

"""

649

+

650

Similarly, you can add argument types to the command:

651

+

652

.. code-block:: python

653

+

654

def make_argument_element(self, arg_type, repeat = "optional", groups = None):

655

"""

656

arg_type: The argument type, one of the lldb.eArgType enum values.

657

repeat: Choose from the following options:

658

"plain" - one value

659

"optional" - zero or more values

660

"plus" - one or more values

661

groups: As with add_option.

662

"""

663

+

664

Then implement the body of the command by defining:

665

+

666

.. code-block:: python

667

+

668

def call(self, debugger, args_array, exe_ctx, result):

669

"""This is the command callback. The option values are

670

provided by the 'dest' properties on the parser.

671

+

672

args_array: This is the list of arguments provided.

673

exe_ctx: Gives the SBExecutionContext on which the

674

command should operate.

675

result: Any results of the command should be

676

written into this SBCommandReturnObject.

677

"""

678

+

679

This differs from the "raw" command's call in that the arguments are already

680

parsed into the args_array, and the option values are set in the parser, and

681

can be accessed using their property name. The LLDBOptionValueParser class has

682

a couple of other handy methods:

683

+

684

.. code-block:: python

685

def was_set(self, long_option_name):

686

+

687

returns True if the option was specified on the command line.

688

+

689

.. code-block:: python

690

+

691

def dest_for_option(self, long_option_name):

692

"""

693

This will return the value of the dest variable you defined for opt_name.

694

Mostly useful for handle_completion where you get passed the long option.

695

"""

696

+

697

lldb will handle completing your option names, and all your enum values

698

automatically. If your option or argument types have associated built-in completers,

699

then lldb will also handle that completion for you. But if you have a need for

700

custom completions, either in your arguments or option values, you can handle

701

completion by hand as well. To handle completion of option value arguments,

702

your lldb.ParsedCommand subclass should implement:

703

+

704

.. code-block:: python

705

+

706

def handle_option_argument_completion(self, long_option, cursor_pos):

707

"""

708

long_option: The long option name of the option whose value you are

709

asked to complete.

710

cursor_pos: The cursor position in the value for that option - which

711

you can get from the option parser.

712

"""

713

+

714

And to handle the completion of arguments:

715

+

716

.. code-block:: python

717

+

718

def handle_argument_completion(self, args, arg_pos, cursor_pos):

719

"""

720

args: A list of the arguments to the command

721

arg_pos: An index into the args list of the argument with the cursor

722

cursor_pos: The cursor position in the arg specified by arg_pos

723

"""

724

+

725

When either of these API's is called, the command line will have been parsed up to

726

the word containing the cursor, and any option values set in that part of the command

727

string are available from the option value parser. That's useful for instance

728

if you have a --shared-library option that would constrain the completions for,

729

say, a symbol name option or argument.

730

+

731

The return value specifies what the completion options are. You have four

732

choices:

733

+

734

`` +

True: the completion was handled with no completions.

735

+

736

`` +

False: the completion was not handled, forward it to the regular

737

completion machinery.

738

+

739

A dictionary with the key: "completion": there is one candidate,

740

whose value is the value of the "completion" key. Optionally you can pass a

741

"mode" key whose value is either "partial" or "complete". Return partial if

742

the "completion" string is a prefix for all the completed value.

743

+

744

For instance, if the string you are completing is "Test" and the available completions are:

745

"Test1", "Test11" and "Test111", you should return the dictionary:

746

+

747

.. code-block:: python

748

+

749

return {"completion": "Test1", "mode" : "partial"}

750

+

751

and then lldb will add the "1" at the curson and advance it after the added string,

752

waiting for more completions. But if "Test1" is the only completion, return:

753

+

754

.. code-block:: python

755

+

756

{"completion": "Test1", "mode": "complete"}

757

+

758

and lldb will add "1 " at the cursor, indicating the command string is complete.

759

+

760

The default is "complete", you don't need to specify a "mode" in that case.

761

+

762

A dictionary with the key: "values" whose value is a list of candidate completion

763

strings. The command interpreter will present those strings as the available choices.

764

You can optionally include a "descriptions" key, whose value is a parallel array

765

of description strings, and the completion will show the description next to

766

each completion.

767

+

768

+

596

769

`One other handy convenience when defining lldb command-line commands is the

597

command command script import which will import a module specified by file

770

command "command script import" which will import a module specified by file

598

771

`path, so you don't have to change your PYTHONPATH for temporary scripts. It

599

772

`also has another convenience that if your new script module has a function of

600

773

`the form:

601

774

602

775

.. code-block python

603

776

604

777

` def __lldb_init_module(debugger, internal_dict):

605

778

` # Command Initialization code goes here

`@@ -615,7 +788,7 @@ creating scripts that can be run from the command line. However, for command

615

788

`line scripts, the debugger instance must be created manually. Sample code would

616

789

`look like:

617

790

618

791

.. code-block:: python

619

792

620

793

`if name == 'main':

621

794

`# Initialize the debugger before making any API calls.

`@@ -638,7 +811,7 @@ look like:

638

811

`Now we can create a module called ls.py in the file ~/ls.py that will implement

639

812

`a function that can be used by LLDB's python command code:

640

813

641

814

.. code-block:: python

642

815

643

816

`#!/usr/bin/env python

644

817