Migrate all commands.

Author: samuel-williams-shopify

data/toolbox/context.py

@@ -230,47 +230,23 @@ def print_info(self, terminal):
             pass
 
 
-class RubyContextCommand(debugger.Command):
-    """Show current execution context and set convenience variables.
+class RubyContextHandler:
+    """Show current execution context and set convenience variables."""
 
-    This command automatically discovers the current thread's execution context
-    and displays detailed information about it, while also setting up convenience
-    variables for easy inspection.
+    USAGE = command.Usage(
+        summary="Show current execution context and set convenience variables",
+        parameters=[],
+        options={},
+        flags=[],
+        examples=[
+            ("rb-context", "Display execution context info"),
+            ("rb-context; rb-print $errinfo", "Show context then print exception")
+        ]
+    )
 
-    Usage:
-        rb-context
-    
-    Displays:
-        - Execution context pointer and details
-        - VM stack information
-        - Control frame pointer
-        - Exception information (if any)
-    
-    Sets these convenience variables:
-        $ec       - Current execution context (rb_execution_context_t *)
-        $cfp      - Current control frame pointer
-        $errinfo  - Current exception (if any)
-    
-    Example:
-        (gdb) rb-context
-        Execution Context:
-          $ec = <rb_execution_context_t *@0x...>
-          VM Stack: <VALUE *@0x...> size=1024
-          $cfp = <rb_control_frame_t *@0x...>
-          Exception: None
-        
-        (gdb) rb-object-print $errinfo
-        (gdb) rb-object-print $ec->cfp->sp[-1]
-    """
-    
-    def __init__(self):
-        super(RubyContextCommand, self).__init__("rb-context", debugger.COMMAND_USER)
-    
-    def invoke(self, arg, from_tty):
+    def invoke(self, arguments, terminal):
         """Execute the rb-context command."""
         try:
-            terminal = format.create_terminal(from_tty)
-            
             # Get current execution context
             ctx = RubyContext.current()
 
@@ -314,30 +290,21 @@ def invoke(self, arg, from_tty):
             traceback.print_exc()
 
 
-class RubyContextStorageCommand(debugger.Command):
-    """Print the fiber storage from the current execution context.
+class RubyContextStorageHandler:
+    """Print the fiber storage from the current execution context."""
 
-    This command is a convenience wrapper around rb-object-print that
-    specifically prints $ec->storage (the inheritable fiber storage).
+    USAGE = command.Usage(
+        summary="Print fiber storage from current execution context",
+        parameters=[],
+        options={'depth': (int, 1, 'Recursion depth for nested objects')},
+        flags=[('debug', 'Show debug information')],
+        examples=[
+            ("rb-context-storage", "Print storage with default depth"),
+            ("rb-context-storage --depth 3", "Print storage with depth 3")
+        ]
+    )
 
-    Usage:
-        rb-context-storage [--depth N] [--debug]
-    
-    All flags are passed through to rb-object-print.
-    
-    Example:
-        (gdb) rb-context
-        (gdb) rb-context-storage --depth 3
-    
-    This is equivalent to:
-        (gdb) rb-context
-        (gdb) rb-object-print $ec->storage --depth 3
-    """
-    
-    def __init__(self):
-        super(RubyContextStorageCommand, self).__init__("rb-context-storage", debugger.COMMAND_USER)
-    
-    def invoke(self, arg, from_tty):
+    def invoke(self, arguments, terminal):
         """Execute the rb-context-storage command."""
         try:
             # Get current execution context
@@ -396,6 +363,5 @@ def invoke(self, arg, from_tty):
 
 
 # Register commands
-RubyContextCommand()
-RubyContextStorageCommand()
-
+debugger.register("rb-context", RubyContextHandler, usage=RubyContextHandler.USAGE)
+debugger.register("rb-context-storage", RubyContextStorageHandler, usage=RubyContextStorageHandler.USAGE)

data/toolbox/fiber.py

@@ -220,22 +220,29 @@ def print_info(self, terminal):
         print(terminal.print_type_tag('rb_control_frame_t', int(self.cfp), None))
 
 
-class RubyFiberScanHeapCommand(debugger.Command):
+class RubyFiberScanHeapHandler:
     """Scan heap and list all Ruby fibers."""
 
+    USAGE = command.Usage(
+        summary="Scan heap and list all Ruby fibers",
+        parameters=[],
+        options={
+            'limit': (int, None, 'Maximum fibers to find'),
+            'cache': (str, None, 'Cache file to use (default: fibers.json)')
+        },
+        flags=[
+            ('terminated', 'Include terminated fibers in results')
+        ],
+        examples=[
+            ("rb-fiber-scan-heap", "Find all non-terminated fibers"),
+            ("rb-fiber-scan-heap --limit 10", "Find first 10 fibers"),
+            ("rb-fiber-scan-heap --terminated", "Include terminated fibers"),
+            ("rb-fiber-scan-heap --cache my.json", "Use custom cache file")
+        ]
+    )
+    
     def __init__(self):
-        super(RubyFiberScanHeapCommand, self).__init__("rb-fiber-scan-heap", debugger.COMMAND_USER)
         self.heap = heap.RubyHeap()
-    
-    def usage(self):
-        """Print usage information."""
-        print("Usage: rb-fiber-scan-heap [--limit N] [--cache [filename]] [--terminated]")
-        print("Examples:")
-        print("  rb-fiber-scan-heap                    # Find all non-terminated fibers")
-        print("  rb-fiber-scan-heap --limit 10         # Find first 10 non-terminated fibers")
-        print("  rb-fiber-scan-heap --terminated       # Include terminated fibers")
-        print("  rb-fiber-scan-heap --cache            # Use fibers.json cache")
-        print("  rb-fiber-scan-heap --cache my.json    # Use custom cache file")
 
     def save_cache(self, fiber_values, filename):
         """Save fiber VALUE addresses to cache file.
@@ -474,29 +481,21 @@ def _print_fiber_info(self, terminal, index, fiber_obj):
         print()
 
 
-class RubyFiberScanSwitchCommand(debugger.Command):
-    """Switch to a fiber from the scan heap cache.
+class RubyFiberScanSwitchHandler:
+    """Switch to a fiber from the scan heap cache."""
 
-    Usage: rb-fiber-scan-switch <index>
-    Example: rb-fiber-scan-switch 0
-             rb-fiber-scan-switch 2
-    
-    Note: This command requires a fiber cache populated by 'rb-fiber-scan-heap'.
-    """
+    USAGE = command.Usage(
+        summary="Switch to a fiber from scan cache by index",
+        parameters=[('index', 'Fiber index from rb-fiber-scan-heap')],
+        options={},
+        flags=[],
+        examples=[
+            ("rb-fiber-scan-switch 0", "Switch to first fiber"),
+            ("rb-fiber-scan-switch 2", "Switch to third fiber")
+        ]
+    )
 
-    def __init__(self):
-        super(RubyFiberScanSwitchCommand, self).__init__("rb-fiber-scan-switch", debugger.COMMAND_USER)
-    
-    def usage(self):
-        """Print usage information."""
-        print("Usage: rb-fiber-scan-switch <index>")
-        print("Examples:")
-        print("  rb-fiber-scan-switch 0    # Switch to fiber #0")
-        print("  rb-fiber-scan-switch 2    # Switch to fiber #2")
-        print()
-        print("Note: Run 'rb-fiber-scan-heap' first to populate the fiber cache.")
-
-    def invoke(self, arg, from_tty):
+    def invoke(self, arguments, terminal):
         global _fiber_cache
 
         if not arg or not arg.strip():
@@ -650,42 +649,25 @@ def deactivate(self):
             gdb.invalidate_cached_frames()
 
 
-class RubyFiberSwitchCommand(debugger.Command):
-    """Switch debugger's stack view to a specific fiber.
-
-    Usage: rb-fiber-switch <fiber_value_or_address>
-           rb-fiber-switch off
-
-    Examples: 
-        rb-fiber-switch 0x7fffdc409ca8    # VALUE address
-        rb-fiber-switch $fiber_val         # Debugger variable
-        rb-fiber-switch off                # Deactivate unwinder (GDB only)
+class RubyFiberSwitchHandler:
+    """Switch debugger's stack view to a specific fiber."""
 
-    This uses a custom unwinder (GDB only) to make the debugger follow the fiber's saved
-    stack, allowing you to use 'bt', 'up', 'down', 'frame', etc.
-    Works even with core dumps!
-
-    Based on technique from Facebook Folly fibers.
-    """
+    USAGE = command.Usage(
+        summary="Switch debugger stack view to a specific fiber",
+        parameters=[('fiber', 'Fiber VALUE/address or "off" to deactivate')],
+        options={},
+        flags=[],
+        examples=[
+            ("rb-fiber-switch 0x7fffdc409ca8", "Switch to fiber at address"),
+            ("rb-fiber-switch $fiber", "Switch using debugger variable"),
+            ("rb-fiber-switch off", "Deactivate unwinder (GDB only)")
+        ]
+    )
 
     def __init__(self):
-        super(RubyFiberSwitchCommand, self).__init__("rb-fiber-switch", debugger.COMMAND_USER)
         if debugger.DEBUGGER_NAME == 'gdb':
             self._ensure_unwinder()
 
-    def usage(self):
-        """Print usage information."""
-        print("Usage: rb-fiber-switch <fiber_value_or_address>")
-        print("       rb-fiber-switch off")
-        print("Examples:")
-        print("  rb-fiber-switch 0x7fffdc409ca8    # VALUE address")
-        print("  rb-fiber-switch $fiber             # Debugger variable")
-        print("  rb-fiber-switch off                # Deactivate unwinder (GDB only)")
-        print()
-        print("After switching, you can use: bt, up, down, frame, info locals, etc.")
-        if debugger.DEBUGGER_NAME != 'gdb':
-            print("Note: Stack unwinding is only supported in GDB")
-
     def _ensure_unwinder(self):
         """Ensure the fiber unwinder is registered (GDB only)."""
         global _fiber_unwinder
@@ -840,26 +822,20 @@ def invoke(self, arg, from_tty):
         print("  rb-fiber-switch off")
 
 
-class RubyFiberScanStackTraceAllCommand(debugger.Command):
-    """Print stack traces for all fibers in the scan cache.
-
-    Usage: rb-fiber-scan-stack-trace-all
+class RubyFiberScanStackTraceAllHandler:
+    """Print stack traces for all fibers in the scan cache."""
 
-    This command prints the Ruby stack trace for each fiber that was
-    found by 'rb-fiber-scan-heap'. Run that command first to populate
-    the fiber cache.
-    """
+    USAGE = command.Usage(
+        summary="Print stack traces for all cached fibers",
+        parameters=[],
+        options={},
+        flags=[],
+        examples=[
+            ("rb-fiber-scan-heap; rb-fiber-scan-stack-trace-all", "Scan fibers then show all backtraces")
+        ]
+    )
 
-    def __init__(self):
-        super(RubyFiberScanStackTraceAllCommand, self).__init__("rb-fiber-scan-stack-trace-all", debugger.COMMAND_USER)
-    
-    def usage(self):
-        """Print usage information."""
-        print("Usage: rb-fiber-scan-stack-trace-all")
-        print()
-        print("Note: Run 'rb-fiber-scan-heap' first to populate the fiber cache.")
-
-    def invoke(self, arg, from_tty):
+    def invoke(self, arguments, terminal):
         global _fiber_cache
 
         # Check if cache is populated
@@ -895,7 +871,7 @@ def invoke(self, arg, from_tty):
 
 
 # Register commands
-RubyFiberScanHeapCommand()
-RubyFiberScanSwitchCommand()
-RubyFiberSwitchCommand()
-RubyFiberScanStackTraceAllCommand()
+debugger.register("rb-fiber-scan-heap", RubyFiberScanHeapHandler, usage=RubyFiberScanHeapHandler.USAGE)
+debugger.register("rb-fiber-scan-switch", RubyFiberScanSwitchHandler, usage=RubyFiberScanSwitchHandler.USAGE)
+debugger.register("rb-fiber-switch", RubyFiberSwitchHandler, usage=RubyFiberSwitchHandler.USAGE)
+debugger.register("rb-fiber-scan-stack-trace-all", RubyFiberScanStackTraceAllHandler, usage=RubyFiberScanStackTraceAllHandler.USAGE)

data/toolbox/heap.py

@@ -1,5 +1,6 @@
 import debugger
 import sys
+import command
 import constants
 
 # Constants
@@ -471,7 +472,7 @@ def find_typed_data(self, data_type, limit=None, progress=False):
 		return objects
 
 
-class RubyHeapScanCommand(debugger.Command):
+class RubyHeapScanHandler:
 	"""Scan the Ruby heap for objects, optionally filtered by type.
 	
 	Usage: rb-heap-scan [--type TYPE] [--limit N] [--from $heap]
@@ -501,23 +502,21 @@ class RubyHeapScanCommand(debugger.Command):
 	  rb-heap-scan --from $heap         # Continue from last scan
 	"""
 
-	def __init__(self):
-		super(RubyHeapScanCommand, self).__init__("rb-heap-scan", debugger.COMMAND_USER)
-	
-	def usage(self):
-		"""Print usage information."""
-		print("Usage: rb-heap-scan [--type TYPE] [--limit N] [--from $heap]")
-		print("Examples:")
-		print("  rb-heap-scan --type RUBY_T_STRING              # Find up to 10 strings")
-		print("  rb-heap-scan --type RUBY_T_ARRAY --limit 5     # Find up to 5 arrays")
-		print("  rb-heap-scan --type 0x05 --limit 100           # Find up to 100 T_STRING objects")
-		print("  rb-heap-scan --limit 20                        # Scan 20 objects (any type)")
-		print("  rb-heap-scan --type RUBY_T_STRING --from $heap # Continue from last scan")
-		print()
-		print("Pagination:")
-		print("  The address of the last object is saved to $heap for pagination:")
-		print("    rb-heap-scan --type RUBY_T_STRING --limit 10        # First page")
-		print("    rb-heap-scan --type RUBY_T_STRING --from $heap      # Next page")
+	USAGE = command.Usage(
+		summary="Scan the Ruby heap for objects, optionally filtered by type",
+		parameters=[],
+		options={
+			'type': (str, None, 'Filter by Ruby type (e.g., RUBY_T_STRING, RUBY_T_ARRAY, or 0x05)'),
+			'limit': (int, 10, 'Maximum objects to find'),
+			'from': (str, None, 'Start address for pagination (use $heap)')
+		},
+		flags=[],
+		examples=[
+			("rb-heap-scan --type RUBY_T_STRING", "Find up to 10 strings"),
+			("rb-heap-scan --type RUBY_T_ARRAY --limit 20", "Find first 20 arrays"),
+			("rb-heap-scan --from $heap", "Continue from last scan (pagination)")
+		]
+	)
 
 	def _parse_type(self, type_arg):
 		"""Parse a type argument and return the type value.
@@ -687,4 +686,4 @@ def invoke(self, arg, from_tty):
 
 
 # Register commands
-RubyHeapScanCommand()
+debugger.register("rb-heap-scan", RubyHeapScanHandler, usage=RubyHeapScanHandler.USAGE)