RubyGems - byebug-dap - Versions diffs - 0.1.3 → 0.1.4 - Mend

byebug-dap 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +6 -0
data/README.md +2 -0
data/bin/byebug-dap +8 -2
data/lib/byebug/dap.rb +26 -13
data/lib/byebug/dap/command.rb +40 -2
data/lib/byebug/dap/command_processor.rb +95 -49
data/lib/byebug/dap/commands/disconnect.rb +1 -0
data/lib/byebug/dap/commands/exception_info.rb +1 -1
data/lib/byebug/dap/commands/scopes.rb +3 -3
data/lib/byebug/dap/commands/set_function_breakpoints.rb +2 -2
data/lib/byebug/dap/commands/threads.rb +2 -2
data/lib/byebug/dap/commands/variables.rb +1 -1
data/lib/byebug/dap/contextual_command.rb +15 -0
data/lib/byebug/dap/helpers/captured_io.rb +15 -0
data/lib/byebug/dap/helpers/captured_output.rb +13 -1
data/lib/byebug/dap/helpers/channel.rb +9 -0
data/lib/byebug/dap/helpers/child_spawned_event_body.rb +16 -2
data/lib/byebug/dap/helpers/handles.rb +8 -0
data/lib/byebug/dap/helpers/invalid_request_argument_error.rb +11 -1
data/lib/byebug/dap/helpers/safe_helpers.rb +8 -0
data/lib/byebug/dap/helpers/scalar.rb +7 -0
data/lib/byebug/dap/helpers/stdio.rb +2 -0
data/lib/byebug/dap/helpers/value_helpers.rb +19 -4
data/lib/byebug/dap/server.rb +20 -0
data/lib/byebug/dap/session.rb +70 -11
data/lib/byebug/gem.rb +15 -1
metadata +2 -2

checksums.yaml CHANGED

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18d52dd5f136afc3350836a23abe3c9b957646358a566e15bfac0aedd070189c
-  data.tar.gz: 615c83e3512cc884f1d9dd2661b578cdf4314ebe2f3bab55f4c76f70a7fb17fc
+  metadata.gz: 581f5d93c98be98b115c7a20ed8d4ab1579cc1bf51cd56a6bff24ff22fb76695
+  data.tar.gz: 4fd205fedf08c249cc2b7484a3ecffd4a7885751d030fbd99f50e167fcf9f7f4
 SHA512:
-  metadata.gz: f5932e26ae7fe7f9518e35df4a22aad7cb363f57d56680e8416e2f6dfa3aed447b7a38270e752313b08a7244108a13f64daee74b58d715ce333b95e4230abbf8
-  data.tar.gz: 4e150cd4ba325258f41d91496ab6d6914294d15330a124c1501ec50b28991a8619d49be3420d4f22305c5067c5d42de167a62dbf2a919b501af9dcb75c18f6f1
+  metadata.gz: a27c677b2a123d5a390b99a42bfe6d572b595239cf53b7ff47480c13412f8aa233ab06d40acb2b022ee53775d3d8332a2eada659f96cea2f95191216e7d333d5
+  data.tar.gz: 46c3a3ca0868a4a2f13c53985620504107a3897e53d5d15a7335bc61d17510766caae4f527bbac9ae24f798d9430868027ef4a43a5d526de696026632dfe9273

data/CHANGELOG.md CHANGED

@@ -1,5 +1,11 @@
 # Change Log
+## 0.1.4
+- Workaround a bug caused by
+  [byebug#734](https://github.com/deivid-rodriguez/byebug/issues/734) by setting
+  the breakpoint hit condition to `>= 0` when the condition should be `nil`.
 ## 0.1.3
 - Support for output capture

data/README.md CHANGED

@@ -1,3 +1,5 @@
+[![Gem Version](https://badge.fury.io/rb/byebug-dap.svg)](https://badge.fury.io/rb/byebug-dap) [![Documentation](https://img.shields.io/static/v1?label=docs&message=master&color=informational&style=flat)](https://firelizzard.gitlab.io/byebug-dap/)
 # Byebug Debug Adapter Protocol
 This gem adds [Debug Adapter

data/bin/byebug-dap CHANGED

@@ -8,7 +8,7 @@ Usage: byebug-dap [options] <--stdio|--unix dap.socket|--listen 12345> <program>
 EOS
 def next_arg
-  arg = ARGV.pop
+  arg = ARGV.shift
   return arg if arg
   LOG.puts USAGE
@@ -88,7 +88,13 @@ begin
   LOG.puts "ok" unless options[:start_code]
-  require File.realpath(program)
+  if File.exist?(program)
+    require program
+  elsif defined?(Bundler)
+    Bundler::CLI.start(['exec', program, *ARGV])
+  else
+    require program
+  end
 rescue => e
   LOG.puts "#{e.message} (#{e.class.name})", *e.backtrace

data/lib/byebug/dap.rb CHANGED

@@ -5,6 +5,11 @@ require 'byebug/remote'
 require_relative 'gem'
+module Byebug::DAP
+  # An alias for `ruby-dap`'s {DAP} module.
+  Protocol = ::DAP
+end
 # load helpers
 Dir[File.join(__dir__, 'dap', 'helpers', '*.rb')].each { |file| require file }
@@ -22,8 +27,13 @@ require_relative 'dap/server'
 module Byebug
   class << self
-    def start_dap(host, port = 0, &block)
-      DAP::Server.new(&block).start(host, port)
+    # Creates and starts the server. See {DAP::Server#initialize} and
+    # {DAP::Server#start}.
+    # @param host the host passed to {DAP::Server#start}
+    # @param port the port passed to {DAP::Server#start}
+    # @return [DAP::Server]
+    def start_dap(host, port = 0)
+      DAP::Server.new.start(host, port)
     end
   end
@@ -37,28 +47,31 @@ module Byebug
 end
 module Byebug::DAP
-  Protocol = ::DAP
   class << self
-    def child_spawned(*args)
-      Session.child_spawned(*args)
-    end
+    # (see Session.stop!)
     def stop!
-      interface = Byebug::Context.interface
-      return false unless interface.is_a?(Session)
+      Session.stop!
+    end
-      interface.stop!
-      true
+    # (see Session.child_spawned)
+    def child_spawned(*args)
+      Session.child_spawned(*args)
     end
   end
 end
+# Debug logging
 module Byebug::DAP::Debug
   class << self
     @protocol = false
     @evaluate = false
-    attr_accessor :protocol, :evaluate
+    # Log all sent and received protocol messages.
+    # @return [Boolean]
+    attr_accessor :protocol
+    # Log evaluation failures.
+    # @return [Boolean]
+    attr_accessor :evaluate
   end
 end

data/lib/byebug/dap/command.rb CHANGED

@@ -1,9 +1,14 @@
 module Byebug::DAP
+  # Implementation of a DAP command.
+  # @abstract Subclasses must implement {#execute}
   class Command
+    # The error message returned when a variable or expression cannot be evaluated.
     EVAL_ERROR = "*Error in evaluation*"
     include SafeHelpers
+    # The DAP command assocated with the receiver.
+    # @return [std:String]
     def self.command
       return @command_name if defined?(@command_name)
@@ -15,10 +20,16 @@ module Byebug::DAP
       @command_name = "#{last[0].downcase}#{last[1..]}"
     end
+    # Register the receiver as a DAP command.
     def self.register!
       (@@commands ||= {})[command] = self
     end
+    # Resolve the requested command. Calls {Session#respond!} indicating a
+    # failed request if the command cannot be found.
+    # @param session [Session] the debug session
+    # @param request [Protocol::Request] the DAP request
+    # @return [std:Class] the {Command} class
     def self.resolve!(session, request)
       cls = @@commands[request.command]
       return cls if cls
@@ -26,21 +37,33 @@ module Byebug::DAP
       session.respond! request, success: false, message: 'Invalid command'
     end
+    # Resolve and execute the requested command. The command is {.resolve!
+    # resolved}, {#initialize initialized}, and {#safe_execute safely executed}.
+    # @param session [Session] the debug session
+    # @param request [Protocol::Request] the DAP request
+    # @param args [std:Array] additional arguments for {#initialize}
+    # @return the return value of {#safe_execute}
     def self.execute(session, request, *args)
       return unless command = resolve!(session, request)
       command.new(session, request, *args).safe_execute
     end
+    # Create a new instance of the receiver.
+    # @param session [Session] the debug session
+    # @param request [Protocol::Request] the DAP request
     def initialize(session, request)
       @session = session
       @request = request
     end
+    # (see Session#log)
     def log(*args)
       @session.log(*args)
     end
+    # Call {#execute} safely, handling any errors that arise.
+    # @return the return value of {#execute}
     def safe_execute
       execute
@@ -91,12 +114,18 @@ module Byebug::DAP
       return
     end
+    # Raises an error if the debugger is running
+    # @api private
+    # @!visibility public
     def stopped!
       return if !Byebug.started?
       respond! success: false, message: "Cannot #{@request.command} - debugger is already running"
     end
+    # Raises an error unless the debugger is running
+    # @api private
+    # @!visibility public
     def started!
       return if Byebug.started?
@@ -111,6 +140,13 @@ module Byebug::DAP
       safe(-> { "#{ex.message} (#{ex.class.name})" }, :call) { EVAL_ERROR }
     end
+    # Execute a code block on the specified thread, {SafeHelpers#safe safely}.
+    # @param thnum [std:Integer] the thread number
+    # @param block [std:Proc] the code block
+    # @yield called on error
+    # @yieldparam ex [std:Exception] the execution error
+    # @api private
+    # @!visibility public
     def execute_on_thread(thnum, block, &on_error)
       return safe(block, :call, &on_error) if thnum == 0 || @context&.thnum == thnum
@@ -207,8 +243,10 @@ module Byebug::DAP
     end
     def convert_breakpoint_hit_condition(condition)
-      return nil if condition.nil? || condition.empty?
-      return nil unless condition.is_a?(String)
+      # Because of https://github.com/deivid-rodriguez/byebug/issues/739,
+      # Breakpoint#hit_condition can't be set to nil.
+      return :ge, 0 if condition.nil? || condition.empty?
+      return :ge, 0 unless condition.is_a?(String)
       m = /^(?<op><|<=|=|==|===|=>|>|%)?\s*(?<value>[0-9]+)$/.match(condition)
       raise InvalidRequestArgumentError.new("'#{condition}' is not a valid hit condition") unless m

data/lib/byebug/dap/command_processor.rb CHANGED

@@ -1,10 +1,14 @@
 module Byebug
   module DAP
+    # Processes thread-specific commands and handles Byebug/TracePoint events.
     class CommandProcessor
       extend Forwardable
       include SafeHelpers
+      # Indicates a timeout while sending a message to the context.
       class TimeoutError < StandardError
+        # The receiving context.
+        # @return [gem:byebug:Byebug::Context]
         attr_reader :context
         def initialize(context)
@@ -12,9 +16,25 @@ module Byebug
         end
       end
-      attr_reader :context, :last_exception
+      # The thread context.
+      # @return [gem:byebug:Byebug::Context]
+      attr_reader :context
+      # The last exception that occured.
+      # @return [std:Exception]
+      attr_reader :last_exception
+      # Indicates that the client requested a pause.
+      # @return [Boolean]
+      # @note This should only be set by {Command::Pause}
+      # @api private
       attr_writer :pause_requested
+      # Create a new command processor.
+      # @param context [gem:byebug:Byebug::Context] the thread context
+      # @param session [Session] the debugging session
+      # @note This should only be used by Byebug internals
+      # @api private
       def initialize(context, session)
         @context = context
         @session = session
@@ -23,14 +43,21 @@ module Byebug
         @exec_ch = Channel.new
       end
+      # (see Session#log)
       def log(*args)
         @session.log(*args)
       end
+      # Send a message to the thread context.
+      # @param message the message to send
+      # @note Raises a {TimeoutError timeout error} after 1 second if the thread is not paused or not responding.
       def <<(message)
         @requests.push(message, timeout: 1) { raise TimeoutError.new(context) }
       end
+      # Execute a code block in the thread.
+      # @yield the code block to execute
+      # @note This calls {#\<\<} and thus may raise a {TimeoutError timeout error}.
       def execute(&block)
         raise "Block required" unless block_given?
@@ -47,6 +74,51 @@ module Byebug
         end
       end
+      # Line handler.
+      # @note This should only be called by Byebug internals
+      # @api private
+      def at_line
+        stopped!
+      end
+      # End of class/module handler.
+      # @note This should only be called by Byebug internals
+      # @api private
+      def at_end
+        stopped!
+      end
+      # Return handler.
+      # @note This should only be called by Byebug internals
+      # @api private
+      def at_return(return_value)
+        @at_return = return_value
+        stopped!
+      end
+      # Tracing handler.
+      # @note This should only be called by Byebug internals
+      # @api private
+      def at_tracing
+        # @session.puts "Tracing: #{context.full_location}"
+      end
+      # Breakpoint handler.
+      # @note This should only be called by Byebug internals
+      # @api private
+      def at_breakpoint(breakpoint)
+        @last_breakpoint = breakpoint
+      end
+      # Catchpoint handler.
+      # @note This should only be called by Byebug internals
+      # @api private
+      def at_catchpoint(exception)
+        @last_exception = exception
+      end
+      private
       def process_requests
         loop do
           request = @requests.pop
@@ -69,35 +141,6 @@ module Byebug
         log "\n! #{e.message} (#{e.class})", *e.backtrace
       end
-      def logpoint!
-        return false unless @last_breakpoint
-        breakpoint, @last_breakpoint = @last_breakpoint, nil
-        expr = @session.get_log_point(breakpoint)
-        return false unless expr
-        binding = @context.frame._binding
-        msg = expr.gsub(/\{([^\}]+)\}/) do |x|
-          safe(binding, :eval, x[1...-1]) { return true } # ignore bad log points
-        end
-        body = {
-          category: 'console',
-          output: msg + "\n",
-        }
-        if breakpoint.pos.is_a?(Integer)
-          body[:line] = breakpoint.pos
-          body[:source] = {
-            name: File.basename(breakpoint.source),
-            path: breakpoint.source,
-          }
-        end
-        @session.event! 'output', **body
-        return true
-      end
       def stopped!
         return if logpoint!
@@ -141,30 +184,33 @@ module Byebug
         process_requests
       end
-      alias at_line stopped!
-      alias at_end stopped!
-      def at_end
-        stopped!
-      end
+      def logpoint!
+        return false unless @last_breakpoint
-      def at_return(return_value)
-        @at_return = return_value
-        stopped!
-      end
+        breakpoint, @last_breakpoint = @last_breakpoint, nil
+        expr = @session.get_log_point(breakpoint)
+        return false unless expr
-      # def at_tracing
-      #   @session.puts "Tracing: #{context.full_location}"
+        binding = @context.frame._binding
+        msg = expr.gsub(/\{([^\}]+)\}/) do |x|
+          safe(binding, :eval, x[1...-1]) { return true } # ignore bad log points
+        end
-      #   # run_auto_cmds(2)
-      # end
+        body = {
+          category: 'console',
+          output: msg + "\n",
+        }
-      def at_breakpoint(breakpoint)
-        @last_breakpoint = breakpoint
-      end
+        if breakpoint.pos.is_a?(Integer)
+          body[:line] = breakpoint.pos
+          body[:source] = {
+            name: File.basename(breakpoint.source),
+            path: breakpoint.source,
+          }
+        end
-      def at_catchpoint(exception)
-        @last_exception = exception
+        @session.event! 'output', **body
+        return true
       end
     end
   end

data/lib/byebug/dap/commands/disconnect.rb CHANGED

@@ -11,6 +11,7 @@ module Byebug::DAP
     def execute
       @session.stop!
       respond!
+      event! 'terminated'
     end
   end
 end

data/lib/byebug/dap/commands/exception_info.rb CHANGED

@@ -15,7 +15,7 @@ module Byebug::DAP
       respond! body: {
         exceptionId: class_name,
         description: exception_description(ex),
-        breakMode: ::DAP::ExceptionBreakMode::ALWAYS,
+        breakMode: Protocol::ExceptionBreakMode::ALWAYS,
         details: details(ex, '$!'),
       }
     end

data/lib/byebug/dap/commands/scopes.rb CHANGED

@@ -14,7 +14,7 @@ module Byebug::DAP
       locals = frame_local_names(frame).sort
       unless locals.empty?
-        scopes << ::DAP::Scope.new(
+        scopes << Protocol::Scope.new(
           name: 'Locals',
           presentationHint: 'locals',
           variablesReference: @session.save_variables(thnum, frnum, :locals, locals),
@@ -26,7 +26,7 @@ module Byebug::DAP
       globals = global_names.sort
       unless globals.empty?
-        scopes << ::DAP::Scope.new(
+        scopes << Protocol::Scope.new(
           name: 'Globals',
           presentationHint: 'globals',
           variablesReference: @session.save_variables(thnum, frnum, :globals, globals),
@@ -36,7 +36,7 @@ module Byebug::DAP
           .validate!
       end
-      respond! body: ::DAP::ScopesResponseBody.new(scopes: scopes)
+      respond! body: Protocol::ScopesResponseBody.new(scopes: scopes)
     end
     private

data/lib/byebug/dap/commands/set_function_breakpoints.rb CHANGED

@@ -42,7 +42,7 @@ module Byebug::DAP
           results << {
             id: bp.id,
             verified: true,
-            source: ::DAP::Source.new(name: File.basename(cm[0]), path: cm[0]),
+            source: Protocol::Source.new(name: File.basename(cm[0]), path: cm[0]),
             line: cm[1]
           }
         end
@@ -51,7 +51,7 @@ module Byebug::DAP
           results << {
             id: bp.id,
             verified: true,
-            source: ::DAP::Source.new(name: File.basename(im[0]), path: im[0]),
+            source: Protocol::Source.new(name: File.basename(im[0]), path: im[0]),
             line: im[1]
           }
         end

data/lib/byebug/dap/commands/threads.rb CHANGED

@@ -7,11 +7,11 @@ module Byebug::DAP
     def execute
       started!
-      respond! body: ::DAP::ThreadsResponseBody.new(
+      respond! body: Protocol::ThreadsResponseBody.new(
         threads: Byebug
           .contexts
           .filter { |ctx| !ctx.thread.is_a?(::Byebug::DebugThread) }
-          .map { |ctx| ::DAP::Thread.new(
+          .map { |ctx| Protocol::Thread.new(
             id: ctx.thnum,
             name: ctx.thread.name || "Thread ##{ctx.thnum}"
           ).validate! })

data/lib/byebug/dap/commands/variables.rb CHANGED

@@ -27,7 +27,7 @@ module Byebug::DAP
       variables = vars[first...last].map { |var, get| prepare_value_response(thnum, frnum, :variable, name: var) { get.call(var) } }
-      respond! body: ::DAP::VariablesResponseBody.new(variables: variables)
+      respond! body: Protocol::VariablesResponseBody.new(variables: variables)
     end
   end
 end

data/lib/byebug/dap/contextual_command.rb CHANGED

@@ -1,5 +1,9 @@
 module Byebug::DAP
+  # Implementation of a DAP command that must be executed in-context.
+  # @abstract Subclasses must implement {#execute_in_context}
   class ContextualCommand < Command
+    # (see Command.resolve!)
+    # @note Raises an error if the resolved class is not a subclass of {ContextualCommand}
     def self.resolve!(session, request)
       return unless cls = super
       return cls if cls < ContextualCommand
@@ -7,12 +11,19 @@ module Byebug::DAP
       raise "Not a contextual command: #{command}"
     end
+    # Create a new instance of the receiver.
+    # @param session [Session] the debug session
+    # @param request [Protocol::Request] the DAP request
+    # @param processor [CommandProcessor] the command processor associated with the context
     def initialize(session, request, processor = nil)
       super(session, request)
       @processor = processor
       @context = processor&.context
     end
+    # {#execute_in_context Execute in-context} if `processor` is defined.
+    # Otherwise, ensure debugging is {#started! started}, find the requested
+    # thread context, and {#forward_to_context forward the request}.
     def execute
       return execute_in_context if @processor
@@ -23,6 +34,10 @@ module Byebug::DAP
     private
+    # Forward the request to the context's thread.
+    # @param ctx [gem:byebug:Byebug::Context] the context
+    # @api private
+    # @!visibility public
     def forward_to_context(ctx)
       ctx.processor << @request
     end

data/lib/byebug/dap/helpers/captured_io.rb CHANGED

@@ -1,5 +1,12 @@
 module Byebug::DAP
+  # Captures STDOUT and STDERR. See {CapturedOutput}.
+  # @api private
   class CapturedIO
+    # Capture STDOUT and STDERR and create a new
+    # {gem:byebug:Byebug::DebugThread} running {#capture}. See
+    # {CapturedOutput#initialize}.
+    # @param forward_stdout [Boolean] if true, captured STDOUT is forwarded to the original STDOUT.
+    # @param forward_stderr [Boolean] if true, captured STDERR is forwarded to the original STDERR.
     def initialize(forward_stdout, forward_stderr)
       @forward_stdout = forward_stdout
       @forward_stderr = forward_stderr
@@ -10,6 +17,8 @@ module Byebug::DAP
       Byebug::DebugThread.new { capture }
     end
+    # Return an IO that can be used for logging.
+    # @return [std:IO]
     def log
       if defined?(LOG)
         LOG
@@ -20,6 +29,7 @@ module Byebug::DAP
       end
     end
+    # {CapturedOutput#restore Restore} the original STDOUT and STDERR.
     def restore
       @stop = true
       @stdout.restore
@@ -28,6 +38,11 @@ module Byebug::DAP
     private
+    # In a loop, read from the captured STDOUT and STDERR and send an output
+    # event to the active session's client (if there is an active session), and
+    # optionally forward the output to the original STDOUT/STDERR.
+    # @api private
+    # @!visibility public
     def capture
       until @stop do
         r, = IO.select([@stdout.captured, @stderr.captured])

data/lib/byebug/dap/helpers/captured_output.rb CHANGED

@@ -1,7 +1,18 @@
 module Byebug::DAP
+  # Captures an IO output stream.
+  # @api private
   class CapturedOutput
-    attr_reader :original, :captured
+    # The original stream, {std:IO#dup duplicated} from `io`. Writing to this IO
+    # will write to the original file.
+    # @return [std:IO]
+    attr_reader :original
+    # The captured stream. Captured output can be read from this IO.
+    # @return [std:IO]
+    attr_reader :captured
+    # Capture `io`, {std:IO#dup duplicate} the original, open an {std:IO.pipe
+    # pipe} pair, and {std:IO#reopen reopen} `io` to redirect it to the pipe.
     def initialize(io)
       @io = io
       @original = io.dup
@@ -11,6 +22,7 @@ module Byebug::DAP
       pw.close
     end
+    # Restore `io` to the original file.
     def restore
       @io.reopen(@original)
       @original.close

data/lib/byebug/dap/helpers/channel.rb CHANGED

@@ -1,5 +1,7 @@
 module Byebug
   module DAP
+    # A channel for synchronously passing values between threads.
+    # @api private
     class Channel
       def initialize
         @mu = Mutex.new
@@ -8,6 +10,7 @@ module Byebug
         @have = false
       end
+      # Close the channel.
       def close
         @mu.synchronize {
           @closed = true
@@ -15,6 +18,8 @@ module Byebug
         }
       end
+      # Pop an item off the channel. Blocks until {#push} or {#close} is called.
+      # @return a value that was pushed or `nil` if the channel is closed.
       def pop
         synchronize_loop {
           return if @closed
@@ -29,6 +34,10 @@ module Byebug
         }
       end
+      # Push an item onto the channel. Raises an error if the channel is closed.
+      # If `timeout` is nil, blocks until {#push} or {#close} is called.
+      # @param message the value to push
+      # @yield called on timeout
       def push(message, timeout: nil)
         deadline = timeout + Time.now.to_f unless timeout.nil?

data/lib/byebug/dap/helpers/child_spawned_event_body.rb CHANGED

@@ -1,10 +1,24 @@
 module Byebug
   module DAP
-    class ChildSpawnedEventBody < ::DAP::Base
-      ::DAP::Event.bodies[:childSpawned] = self
+    # `childSpawned` is a custom DAP event used to notify the client that a
+    # child process has spawned.
+    # @api private
+    class ChildSpawnedEventBody < Protocol::Base
+      Protocol::Event.bodies[:childSpawned] = self
+      # The child process's name
+      # @return [std:String]
+      # @!attribute [r]
       property :name
+      # The child's process ID
+      # @return [std:Integer]
+      # @!attribute [r]
       property :pid
+      # The debug socket to connect to
+      # @return [std:String]
+      # @!attribute [r]
       property :socket
     end
   end

data/lib/byebug/dap/helpers/handles.rb CHANGED

@@ -1,19 +1,27 @@
 module Byebug
   module DAP
+    # Tracks opaque handles used by DAP.
+    # @api private
     class Handles
       def initialize
         @mu = Mutex.new
         @entries = []
       end
+      # Delete all handles.
       def clear!
         sync { @entries = []; nil }
       end
+      # Retrieve the entry with the specified handle.
+      # @param id [std:Integer] the handle
+      # @return the entry
       def [](id)
         sync { @entries[id-1] }
       end
+      # Add a new entry.
+      # @return [std:Integer] the handle
       def <<(entry)
         sync do
           @entries << entry

data/lib/byebug/dap/helpers/invalid_request_argument_error.rb CHANGED

@@ -1,7 +1,17 @@
 module Byebug
   module DAP
+    # Raised when the client sends a request with invalid arguments
+    # @api private
     class InvalidRequestArgumentError < StandardError
-      attr_accessor :error, :value, :scope
+      # The error kind or message.
+      # @return [std:Symbol|std:String]
+      attr_reader :error
+      # The error value.
+      attr_reader :value
+      # The error scope.
+      attr_reader :scope
       def initialize(error, value: nil, scope: nil)
         @error = error

data/lib/byebug/dap/helpers/safe_helpers.rb CHANGED

@@ -1,6 +1,14 @@
 module Byebug
   module DAP
+    # Methods to safely execute methods.
+    # @api private
     module SafeHelpers
+      # Safely execute `method` on `target` with `args`.
+      # @param target the receiver
+      # @param method [std:Symbol] the method name
+      # @param args [std:Array] the method arguments
+      # @yield called on error
+      # @yieldparam ex [std:StandardError] the execution error
       def safe(target, method, *args, &block)
         if method.is_a?(Array) && args.empty?
           method.each { |m| target = target.__send__(m) }

data/lib/byebug/dap/helpers/scalar.rb CHANGED

@@ -1,5 +1,12 @@
 module Byebug::DAP
+  # Used in case statements to identify scalar types.
+  # @api private
   module Scalar
+    # Match scalar values. {std:NilClass nil}, {std:TrueClass true},
+    # {std:FalseClass false}, {std:String strings}, {std:Numeric numbers},
+    # {std:Time times}, {std:Range ranges}, {std:date:Date dates}, and
+    # {std:date:DateTime date-times} are considered scalars.
+    # @return [Boolean]
     def ===(value)
       case value
       when nil, true, false

data/lib/byebug/dap/helpers/stdio.rb CHANGED

@@ -1,4 +1,6 @@
 module Byebug::DAP
+  # A debug session 'connection' using STDIN and STDOUT.
+  # @api private
   class STDIO
     extend Forwardable

data/lib/byebug/dap/helpers/value_helpers.rb CHANGED

@@ -1,5 +1,11 @@
 module Byebug::DAP
+  # Methods to prepare values for DAP responses.
+  # @api private
   module ValueHelpers
+    # Safely inspect a value and retrieve its class name, class and instance
+    # variables, and indexed members. {Scalar} values do not have variables or
+    # members. Only {std:Array arrays} and {std:Hash hashes} have members.
+    # @return `val.inspect`, `val.class.name`, variables, and members.
     def prepare_value(val)
       str = safe(val, :inspect) { safe(val, :to_s) { return yield } }
       cls = safe(val, :class) { nil }
@@ -8,8 +14,8 @@ module Byebug::DAP
       scalar = safe(-> { Scalar === val }, :call) { true }
       return str, typ, [], [] if scalar
-      named = safe(val, :instance_variables) { [] }
-      named += safe(val, :class_variables) { [] }
+      named = safe(val, :instance_variables) { [] } || []
+      named += safe(val, :class_variables) { [] } || []
       # named += safe(val, :constants) { [] }
       indexed = safe(-> {
@@ -21,6 +27,15 @@ module Byebug::DAP
       return str, typ, named, indexed
     end
+    # Prepare a {Protocol::Variable} or {Protocol::EvaluateResponseBody} for a
+    # calculated value. For global variables and evaluations, `thnum` and
+    # `frnum` should be 0. Local variables and evaluations are
+    # {Command#execute_on_thread executed on the specified thread}.
+    # @param thnum [std:Integer] the thread number
+    # @param frnum [std:Integer] the frame number
+    # @param kind [std:Symbol] `:variable` or `:evaluate`
+    # @param name [std:String] the variable name (ignored for evaluations)
+    # @yield retrieves an variable or evaluates an expression
     def prepare_value_response(thnum, frnum, kind, name: nil, &block)
       err = nil
       raw = execute_on_thread(thnum, block) { |e| err = e; nil }
@@ -39,10 +54,10 @@ module Byebug::DAP
       case kind
       when :variable
-        klazz = ::DAP::Variable
+        klazz = Protocol::Variable
         args = { name: safe(name, :to_s) { safe(name, :inspect) { '???' } }, value: value, type: type }
       when :evaluate
-        klazz = ::DAP::EvaluateResponseBody
+        klazz = Protocol::EvaluateResponseBody
         args = { result: value, type: type }
       end

data/lib/byebug/dap/server.rb CHANGED

@@ -1,6 +1,10 @@
 module Byebug
   module DAP
+    # Byebug DAP Server
     class Server
+      # Create a new server.
+      # @param capture [Boolean] if `true`, the debugee's STDOUT and STDERR will be captured
+      # @param forward [Boolean] if `false`, the debugee's STDOUT and STDERR will be supressed
       def initialize(capture: true, forward: true)
         @started = false
         @mu = Mutex.new
@@ -10,6 +14,12 @@ module Byebug
         @forward = forward
       end
+      # Starts the server. Calls {#start_stdio} if `host == :stdio`. Calls
+      # {#start_unix} with `port` if `host == :unix`. Calls {#start_tcp} with
+      # `host` and `port` otherwise.
+      # @param host `:stdio`, `:unix`, or the TCP host name
+      # @param port the Unix socket path or TCP port
+      # @return [Server]
       def start(host, port = 0)
         case host
         when :stdio
@@ -21,6 +31,10 @@ module Byebug
         end
       end
+      # Starts the server, listening on a TCP socket.
+      # @param host [std:String] the IP to listen on
+      # @param port [std:Number] the port to listen on
+      # @return [Server]
       def start_tcp(host, port)
         return if @started
         @started = true
@@ -29,6 +43,9 @@ module Byebug
         launch_accept TCPServer.new(host, port)
       end
+      # Starts the server, listening on a Unix socket.
+      # @param socket [std:String] the Unix socket path
+      # @return [Server]
       def start_unix(socket)
         return if @started
         @started = true
@@ -37,6 +54,8 @@ module Byebug
         launch_accept UNIXServer.new(socket)
       end
+      # Starts the server using STDIN and STDOUT to communicate.
+      # @return [Server]
       def start_stdio
         return if @started
         @started = true
@@ -47,6 +66,7 @@ module Byebug
         launch stream
       end
+      # Blocks until a client connects and begins debugging.
       def wait_for_client
         @mu.synchronize do
           loop do

data/lib/byebug/dap/session.rb CHANGED

@@ -1,24 +1,42 @@
 module Byebug
   module DAP
+    # A Byebug DAP session
     class Session
       include SafeHelpers
-      @@children = []
+      # Call {Session#stop!} on {gem:byebug:Byebug::Context.interface} if it is
+      # a {Session}.
+      # @return [Boolean] whether {gem:byebug:Byebug::Context.interface} was a {Session}
+      def self.stop!
+        session = Byebug::Context.interface
+        return false unless session.is_a?(Session)
+        session.stop!
+        true
+      end
+      # Record a {ChildSpawnedEventBody childSpawned event} and send the event
+      # to the current session's client, if
+      # {gem:byebug:Byebug::Context.interface} is a {Session}.
       def self.child_spawned(name, pid, socket)
         child = ChildSpawnedEventBody.new(name: name, pid: pid, socket: socket)
-        @@children << child
+        (@@children ||= []) << child
         session = Context.interface
-        session.event! child if session.is_a?(Byebug::DAP::Session)
+        return false unless session.is_a?(Session)
+        session.event! child
         return true
       rescue IOError, Errno::EPIPE, Errno::ECONNRESET, Errno::ECONNABORTED
         return false
       end
-      def initialize(connection, ios, &block)
+      # Create a new session instance.
+      # @param connection [std:IO] the connection to the client
+      # @param ios [CapturedIO] the captured IO
+      # @yield called once the client is done configuring the session (optional)
+      def initialize(connection, ios = nil, &block)
         @connection = connection
         @ios = ios
         @on_configured = block
@@ -31,6 +49,7 @@ module Byebug
         notify_of_children
       end
+      # Write a message to the log.
       def log(*args)
         logger =
           if @ios
@@ -43,20 +62,28 @@ module Byebug
         logger.puts(*args)
       end
+      # Execute requests from the client until the connection is closed.
       def execute
         Context.interface = self
-        Context.processor = Byebug::DAP::CommandProcessor
+        Context.processor = DAP::CommandProcessor
         Command.execute(self, receive) until @connection.closed?
         Context.interface = LocalInterface.new
       end
+      # Invalidate frame IDs and variables references.
+      # @note This should only be used by a {ContextualCommand contextual command} that un-pauses its context
+      # @api private
       def invalidate_handles!
         @frame_ids.clear!
         @variable_refs.clear!
       end
+      # Start Byebug.
+      # @param mode [std:Symbol] `:attached` or `:launched`
+      # @note This should only be used by the {Command::Attach attach} or {Command::Launch launch} commands
+      # @api private
       def start!(mode)
         @trace.enable
         Byebug.mode = mode
@@ -64,6 +91,9 @@ module Byebug
         @exit_on_stop = true if mode == :launched
       end
+      # Call the block passed to {#initialize}.
+      # @note This should only be used by the {Command::ConfigurationDone configurationDone} commands
+      # @api private
       def configured!
         return unless @on_configured
@@ -71,6 +101,8 @@ module Byebug
         callback.call
       end
+      # Stop Byebug and close the client's connection.
+      # @note If the session was started with the `launch` command, this will {std:Kernel#exit exit}
       def stop!
         exit if @exit_on_stop && @pid == Process.pid
@@ -80,19 +112,29 @@ module Byebug
         @connection.close
       end
+      # Send an event to the client. Either call with an event name and body
+      # attributes, or call with an already constructed body.
+      # @param event [std:String|Protocol::Base] the event name or event body
+      # @param values [std:Hash] event body attributes
       def event!(event, **values)
         if (cls = event.class.name.split('::').last) && cls.end_with?('EventBody')
           body, event = event, cls[0].downcase + cls[1...-9]
         elsif event.is_a?(String) && !values.empty?
-          body = ::DAP.const_get("#{event[0].upcase}#{event[1..]}EventBody").new(values)
+          body = Protocol.const_get("#{event[0].upcase}#{event[1..]}EventBody").new(values)
         end
-        send ::DAP::Event.new(event: event, body: body)
+        send Protocol::Event.new(event: event, body: body)
       end
+      # Send a response to the client.
+      # @param request [Protocol::Request] the request to respond to
+      # @param body [std:Hash|Protocol::Base] the response body
+      # @param success [std:Boolean] whether the request was successful
+      # @param message [std:String] the response message
+      # @param values [std:Hash] additional response attributes
       def respond!(request, body = nil, success: true, message: 'Success', **values)
-        send ::DAP::Response.new(
+        send Protocol::Response.new(
           request_seq: request.seq,
           command: request.command,
           success: success,
@@ -101,26 +143,40 @@ module Byebug
           **values)
       end
+      # Create a variables reference.
       def save_variables(*args)
         @variable_refs << args
       end
+      # Retrieve variables from a reference.
       def restore_variables(ref)
         @variable_refs[ref]
       end
+      # Create a frame ID.
       def save_frame(*args)
         @frame_ids << args
       end
+      # Restore a frame from an ID.
       def restore_frame(id)
         @frame_ids[id]
       end
+      # Get the log point expression associated with `breakpoint`.
+      # @param breakpoint [gem:byebug:Byebug::Breakpoint] the breakpoint
+      # @return [std:String] the log point expression
+      # @note This should only be used by a {CommandProcessor command processor}
+      # @api private
       def get_log_point(breakpoint)
         @log_points[breakpoint.id]
       end
+      # Associate a log point expression with `breakpoint`.
+      # @param breakpoint [gem:byebug:Byebug::Breakpoint] the breakpoint
+      # @param expr [std:String] the log point expression
+      # @note This should only be used by a {CommandProcessor command processor}
+      # @api private
       def set_log_point(breakpoint, expr)
         if expr.nil? || expr.empty?
           @log_points.delete(breakpoint.id)
@@ -129,6 +185,9 @@ module Byebug
         end
       end
+      # Delete the specified breakpoints and any log points associated with
+      # them.
+      # @param breakpoints [std:Array<gem:byebug:Byebug::Breakpoint>] the breakpoints
       def clear_breakpoints(*breakpoints)
         breakpoints.each do |breakpoint|
           Byebug.breakpoints.delete(breakpoint)
@@ -139,7 +198,7 @@ module Byebug
       private
       def notify_of_children
-        @@children.each { |c| event! c }
+        @@children.each { |c| event! c } if defined?(@@children)
       rescue IOError, Errno::EPIPE, Errno::ECONNRESET, Errno::ECONNABORTED
         # client is closed
       end
@@ -147,11 +206,11 @@ module Byebug
       def send(message)
         log "#{Process.pid} > #{message.to_wire}" if Debug.protocol
         message.validate!
-        @connection.write ::DAP::Encoding.encode(message)
+        @connection.write Protocol.encode(message)
       end
       def receive
-        m = ::DAP::Encoding.decode(@connection)
+        m = Protocol.decode(@connection)
         log "#{Process.pid} < #{m.to_wire}" if Debug.protocol
         m
       end

data/lib/byebug/gem.rb CHANGED

@@ -1,11 +1,25 @@
 module Byebug
+  # Debug Adapter Protocol support for Byebug
   module DAP
+    # Gem name
     NAME = 'byebug-dap'
-    VERSION = '0.1.3'
+    # Gem version
+    VERSION = '0.1.4'
+    # Gem summary
     SUMMARY = 'Debug Adapter Protocol for Byebug'
+    # Gem description
     DESCRIPTION = 'Implements a Debug Adapter Protocol interface for Byebug'
+    # Gem authors
     AUTHORS = ['Ethan Reesor']
+    # Gem website
     WEBSITE = 'https://gitlab.com/firelizzard/byebug-dap'
+    # Gem license
     LICENSE = 'Apache-2.0'
   end
 end

metadata CHANGED

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: byebug-dap
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Ethan Reesor
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-10-12 00:00:00.000000000 Z
+date: 2020-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug