<feed xmlns='http://www.w3.org/2005/Atom'>
<title>ruby.git/misc/rb_base_command.py, branch master</title>
<subtitle>The Ruby Programming Language</subtitle>
<link rel='alternate' type='text/html' href='https://git.ruby-lang.org/ruby.git/'/>
<entry>
<title>[ci-skip][Feature #18910][lldb] New directory structure</title>
<updated>2022-08-18T17:25:32+00:00</updated>
<author>
<name>Matt Valentine-House</name>
<email>matt@eightbitraptor.com</email>
</author>
<published>2022-07-13T17:14:44+00:00</published>
<link rel='alternate' type='text/html' href='https://git.ruby-lang.org/ruby.git/commit/?id=b26aec9daa03a4f3da225e9e4f7a43e916928712'/>
<id>b26aec9daa03a4f3da225e9e4f7a43e916928712</id>
<content type='text'>
Push the newly refactored lldb files into a sub-directory so that we're
not cluttering up the misc directory
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
Push the newly refactored lldb files into a sub-directory so that we're
not cluttering up the misc directory
</pre>
</div>
</content>
</entry>
<entry>
<title>[ci-skip][Feature #18910][lldb] Provide class framework for lldb commands</title>
<updated>2022-08-18T17:25:32+00:00</updated>
<author>
<name>Matt Valentine-House</name>
<email>matt@eightbitraptor.com</email>
</author>
<published>2022-07-13T12:18:03+00:00</published>
<link rel='alternate' type='text/html' href='https://git.ruby-lang.org/ruby.git/commit/?id=f1ccfa0c2c200c9443fbfc3f1ac3acbdd3e35559'/>
<id>f1ccfa0c2c200c9443fbfc3f1ac3acbdd3e35559</id>
<content type='text'>
`lldb_cruby.py` manages lldb custom commands using functions. The file
is a large list of Python functions, and an init handler to map some of
the Python functions into the debugger, to enable execution of custom
logic during a debugging session.

Since LLDB 3.7 (September 2015) there has also been support for using
python classes rather than bare functions, as long as those classes
implement a specific interface.

This PR Introduces some more defined structure to the LLDB helper
functions by switching from the function based implementation to the
class based one, and providing an auto-loading mechanism by which new
functions can be loaded.

The intention behind this change is to make working with the LLDB
helpers easier, by reducing code duplication, providing a consistent
structure and a clearer API for developers.

The current function based approach has some advantages and
disadvantages

Advantages:

- Adding new code is easy.
- All the code is self contained and searchable.

Disadvantages:
- No visible organisation of the file contents. This means
  - Hard to tell which functions are utility functions and which are
    available to you in a debugging session
  - Lots of code duplication within lldb functions
- Large files quickly become intimidating to work with - for example,
  `lldb_disasm.py` was implemented as a seperate Python module because
  it was easier to start with a clean slate than add significant amounts
  of code to `lldb_cruby.py`

This PR attempts, to fix the disadvantages of the current approach and
maintain, or enhance, the benefits. The new structure of a command looks
like this;

 ```
 class TestCommand(RbBaseCommand):
    # program is the keyword the user will type in lldb to execute this command
    program = "test"

    # help_string will be displayed in lldb when the user uses the help functions
    help_string = "This is a test command to show how to implement lldb commands"

    # call is where our command logic will be implemented
    def call(self, debugger, command, exe_ctx, result):
        pass
  ```

If the command fulfils the following criteria it will then be
auto-loaded when an lldb session is started:

- The package file must exist inside the `commands` directory and the
  filename must end in `_command.py`
- The package must implement a class whose name ends in `Command`
- The class inherits from `RbBaseCommand` or at minimum a class that
  shares the same interface as `RbBaseCommand`  (at minimum this means
  defining `__init__` and `__call__`, and using `__call__` to call
  `call` which is defined in the subclasses).
- The class must have a class variable `package` that is a String. This
  is the name of the command you'll call in the `lldb` debugger.
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
`lldb_cruby.py` manages lldb custom commands using functions. The file
is a large list of Python functions, and an init handler to map some of
the Python functions into the debugger, to enable execution of custom
logic during a debugging session.

Since LLDB 3.7 (September 2015) there has also been support for using
python classes rather than bare functions, as long as those classes
implement a specific interface.

This PR Introduces some more defined structure to the LLDB helper
functions by switching from the function based implementation to the
class based one, and providing an auto-loading mechanism by which new
functions can be loaded.

The intention behind this change is to make working with the LLDB
helpers easier, by reducing code duplication, providing a consistent
structure and a clearer API for developers.

The current function based approach has some advantages and
disadvantages

Advantages:

- Adding new code is easy.
- All the code is self contained and searchable.

Disadvantages:
- No visible organisation of the file contents. This means
  - Hard to tell which functions are utility functions and which are
    available to you in a debugging session
  - Lots of code duplication within lldb functions
- Large files quickly become intimidating to work with - for example,
  `lldb_disasm.py` was implemented as a seperate Python module because
  it was easier to start with a clean slate than add significant amounts
  of code to `lldb_cruby.py`

This PR attempts, to fix the disadvantages of the current approach and
maintain, or enhance, the benefits. The new structure of a command looks
like this;

 ```
 class TestCommand(RbBaseCommand):
    # program is the keyword the user will type in lldb to execute this command
    program = "test"

    # help_string will be displayed in lldb when the user uses the help functions
    help_string = "This is a test command to show how to implement lldb commands"

    # call is where our command logic will be implemented
    def call(self, debugger, command, exe_ctx, result):
        pass
  ```

If the command fulfils the following criteria it will then be
auto-loaded when an lldb session is started:

- The package file must exist inside the `commands` directory and the
  filename must end in `_command.py`
- The package must implement a class whose name ends in `Command`
- The class inherits from `RbBaseCommand` or at minimum a class that
  shares the same interface as `RbBaseCommand`  (at minimum this means
  defining `__init__` and `__call__`, and using `__call__` to call
  `call` which is defined in the subclasses).
- The class must have a class variable `package` that is a String. This
  is the name of the command you'll call in the `lldb` debugger.
</pre>
</div>
</content>
</entry>
</feed>
