ruby-dap 0.1.2 → 0.1.3

data/lib/dap/capabilities_event_body.rb

@@ -1,5 +1,11 @@
 require_relative 'capabilities'
 
+# The event indicates that one or more capabilities have changed. Since the
+# capabilities are dependent on the frontend and its UI, it might not be possible
+# to change that at random times (or too late). Consequently this event has a hint
+# characteristic: a frontend can only be expected to make a ‘best effort’ in
+# honouring individual capabilities but there are no guarantees. Only changed
+# capabilities need to be included, all other capabilities keep their values.
 class DAP::CapabilitiesEventBody < DAP::Base
   # The set of updated capabilities.
   property :capabilities, as: DAP::Capabilities

data/lib/dap/checksum.rb

@@ -1,9 +1,10 @@
 require_relative 'checksum_algorithm'
 
+# The checksum of an item calculated by the specified algorithm.
 class DAP::Checksum < DAP::Base
   # The algorithm used to calculate this checksum.
   property :algorithm, as: DAP::ChecksumAlgorithm
 
   # Value of the checksum.
-  property :checksum
+  property :checksum, as: 'string'
 end

data/lib/dap/checksum_algorithm.rb

@@ -1,3 +1,4 @@
+# Names of checksum algorithms that may be supported by a debug adapter.
 class DAP::ChecksumAlgorithm < DAP::Enum
   MD5 = new('MD5')
   SHA1 = new('SHA1')

data/lib/dap/column_descriptor.rb

@@ -1,17 +1,20 @@
+# A ColumnDescriptor specifies what module attribute to show in a column of the
+# ModulesView, how to format it, and what the column’s label should be. It is only
+# used if the underlying UI actually supports this level of customization.
 class DAP::ColumnDescriptor < DAP::Base
   # Name of the attribute rendered in this column.
-  property :attributeName
+  property :attributeName, as: 'string'
 
   # Header UI label of column.
-  property :label
+  property :label, as: 'string'
 
   # Format to use for the rendered values in this column. TBD how the format strings looks like.
-  property :format, required: false
+  property :format, required: false, as: 'string'
 
   # Datatype of values in this column.  Defaults to 'string' if not specified.
   # Values: 'string', 'number', 'boolean', 'unixTimestampUTC', etc.
-  property :type, required: false # 'string' | 'number' | 'boolean' | 'unixTimestampUTC'
+  property :type, required: false, as: 'string'
 
   # Width of this column in characters (hint only).
-  property :width, required: false
+  property :width, required: false, as: 'number'
 end

data/lib/dap/completion_item.rb

@@ -1,33 +1,34 @@
 require_relative 'completion_item_type'
 
+# CompletionItems are the suggestions returned from the CompletionsRequest.
 class DAP::CompletionItem < DAP::Base
   # The label of this completion item. By default this is also the text that is inserted when selecting this completion.
-  property :label
+  property :label, as: 'string'
 
   # If text is not falsy then it is inserted instead of the label.
-  property :text, required: false
+  property :text, required: false, as: 'string'
 
   # A string that should be used when comparing this item with other items. When `falsy` the label is used.
-  property :sortText, required: false
+  property :sortText, required: false, as: 'string'
 
   # The item's type. Typically the client uses this information to render the item in the UI with an icon.
   property :type, required: false, as: DAP::CompletionItemType
 
   # This value determines the location (in the CompletionsRequest's 'text' attribute) where the completion text is added.
   # If missing the text is added at the location specified by the CompletionsRequest's 'column' attribute.
-  property :start, required: false
+  property :start, required: false, as: 'number'
 
   # This value determines how many characters are overwritten by the completion text.
   # If missing the value 0 is assumed which results in the completion text being inserted.
-  property :length, required: false
+  property :length, required: false, as: 'number'
 
   # Determines the start of the new selection after the text has been inserted (or replaced).
   # The start position must in the range 0 and length of the completion text.
   # If omitted the selection starts at the end of the completion text.
-  property :selectionStart, required: false
+  property :selectionStart, required: false, as: 'number'
 
   # Determines the length of the new selection after the text has been inserted (or replaced).
   # The selection can not extend beyond the bounds of the completion text.
   # If omitted the length is assumed to be 0.
-  property :selectionLength, required: false
+  property :selectionLength, required: false, as: 'number'
 end

data/lib/dap/completion_item_type.rb

@@ -1,3 +1,5 @@
+# Some predefined types for the CompletionItem. Please note that not all clients
+# have specific icons for all of them.
 class DAP::CompletionItemType < DAP::Enum
   METHOD = new('method')
   FUNCTION = new('function')

data/lib/dap/completions_arguments.rb

@@ -1,13 +1,14 @@
+# Arguments for ‘completions’ request.
 class DAP::CompletionsArguments < DAP::Base
   # Returns completions in the scope of this stack frame. If not specified, the completions are returned for the global scope.
-  property :frameId, required: false
+  property :frameId, required: false, as: 'number'
 
   # One or more source lines. Typically this is the text a user has typed into the debug console before he asked for completion.
-  property :text
+  property :text, as: 'string'
 
   # The character position for which to determine the completion proposals.
-  property :column
+  property :column, as: 'number'
 
   # An optional line for which to determine the completion proposals. If missing the first line of the text is assumed.
-  property :line, required: false
+  property :line, required: false, as: 'number'
 end

data/lib/dap/completions_response_body.rb

@@ -1,5 +1,6 @@
 require_relative 'completion_item'
 
+# Response to ‘completions’ request.
 class DAP::CompletionsResponseBody < DAP::Base
   # The possible completions for .
   property :targets, as: many(DAP::CompletionItem)

data/lib/dap/continue_arguments.rb

@@ -1,5 +1,6 @@
+# Arguments for ‘continue’ request.
 class DAP::ContinueArguments < DAP::Base
   # Continue execution for the specified thread (if possible).
   # If the backend cannot continue on a single thread but will continue on all threads, it should set the 'allThreadsContinued' attribute in the response to true.
-  property :threadId
+  property :threadId, as: 'number'
 end

data/lib/dap/continue_response_body.rb

@@ -1,5 +1,6 @@
+# Response to ‘continue’ request.
 class DAP::ContinueResponseBody < DAP::Base
   # If true, the 'continue' request has ignored the specified thread and continued all threads instead.
   # If this attribute is missing a value of 'true' is assumed for backward compatibility.
-  property :allThreadsContinued, required: false
+  property :allThreadsContinued, required: false, as: 'boolean'
 end

data/lib/dap/continued_event_body.rb

@@ -1,7 +1,12 @@
+# The event indicates that the execution of the debuggee has continued. Please
+# note: a debug adapter is not expected to send this event in response to a
+# request that implies that execution continues, e.g. ‘launch’ or ‘continue’. It
+# is only necessary to send a ‘continued’ event if there was no previous request
+# that implied this.
 class DAP::ContinuedEventBody < DAP::Base
   # The thread which was continued.
-  property :threadId
+  property :threadId, as: 'number'
 
   # If 'allThreadsContinued' is true, a debug adapter can announce that all threads have continued.
-  property :allThreadsContinued, required: false
+  property :allThreadsContinued, required: false, as: 'boolean'
 end

data/lib/dap/data_breakpoint.rb

@@ -1,16 +1,17 @@
 require_relative 'data_breakpoint_access_type'
 
+# Properties of a data breakpoint passed to the setDataBreakpoints request.
 class DAP::DataBreakpoint < DAP::Base
   # An id representing the data. This id is returned from the dataBreakpointInfo request.
-  property :dataId
+  property :dataId, as: 'string'
 
   # The access type of the data.
   property :accessType, required: false, as: DAP::DataBreakpointAccessType
 
   # An optional expression for conditional breakpoints.
-  property :condition, required: false
+  property :condition, required: false, as: 'string'
 
   # An optional expression that controls how many hits of the breakpoint are ignored.
   # The backend is expected to interpret the expression as needed.
-  property :hitCondition, required: false
+  property :hitCondition, required: false, as: 'string'
 end

data/lib/dap/data_breakpoint_access_type.rb

@@ -1,3 +1,4 @@
+# This enumeration defines all possible access types for data breakpoints.
 class DAP::DataBreakpointAccessType < DAP::Enum
   READ = new('read')
   WRITE = new('write')

data/lib/dap/data_breakpoint_info_arguments.rb

@@ -1,8 +1,9 @@
+# Arguments for ‘dataBreakpointInfo’ request.
 class DAP::DataBreakpointInfoArguments < DAP::Base
   # Reference to the Variable container if the data breakpoint is requested for a child of the container.
-  property :variablesReference, required: false
+  property :variablesReference, required: false, as: 'number'
 
   # The name of the Variable's child to obtain data breakpoint information for.
   # If variableReference isn’t provided, this can be an expression.
-  property :name
+  property :name, as: 'string'
 end

data/lib/dap/data_breakpoint_info_response_body.rb

@@ -1,15 +1,16 @@
 require_relative 'data_breakpoint_access_type'
 
+# Response to ‘dataBreakpointInfo’ request.
 class DAP::DataBreakpointInfoResponseBody < DAP::Base
   # An identifier for the data on which a data breakpoint can be registered with the setDataBreakpoints request or null if no data breakpoint is available.
   property :dataId
 
   # UI string that describes on what data the breakpoint is set on or why a data breakpoint is not available.
-  property :description
+  property :description, as: 'string'
 
   # Optional attribute listing the available access types for a potential data breakpoint. A UI frontend could surface this information.
   property :accessTypes, required: false, as: many(DAP::DataBreakpointAccessType)
 
   # Optional attribute indicating that a potential data breakpoint could be persisted across sessions.
-  property :canPersist, required: false
+  property :canPersist, required: false, as: 'boolean'
 end

data/lib/dap/disassemble_arguments.rb

@@ -1,17 +1,18 @@
+# Arguments for ‘disassemble’ request.
 class DAP::DisassembleArguments < DAP::Base
   # Memory reference to the base location containing the instructions to disassemble.
-  property :memoryReference
+  property :memoryReference, as: 'string'
 
   # Optional offset (in bytes) to be applied to the reference location before disassembling. Can be negative.
-  property :offset, required: false
+  property :offset, required: false, as: 'number'
 
   # Optional offset (in instructions) to be applied after the byte offset (if any) before disassembling. Can be negative.
-  property :instructionOffset, required: false
+  property :instructionOffset, required: false, as: 'number'
 
   # Number of instructions to disassemble starting at the specified location and offset.
   # An adapter must return exactly this number of instructions - any unavailable instructions should be replaced with an implementation-defined 'invalid instruction' value.
-  property :instructionCount
+  property :instructionCount, as: 'number'
 
   # If true, the adapter should attempt to resolve memory addresses and other values to symbolic names.
-  property :resolveSymbols, required: false
+  property :resolveSymbols, required: false, as: 'boolean'
 end

data/lib/dap/disassemble_response_body.rb

@@ -1,5 +1,6 @@
 require_relative 'disassembled_instruction'
 
+# Response to ‘disassemble’ request.
 class DAP::DisassembleResponseBody < DAP::Base
   # The list of disassembled instructions.
   property :instructions, as: many(DAP::DisassembledInstruction)

data/lib/dap/disassembled_instruction.rb

@@ -1,17 +1,18 @@
 require_relative 'source'
 
+# Represents a single disassembled instruction.
 class DAP::DisassembledInstruction < DAP::Base
   # The address of the instruction. Treated as a hex value if prefixed with '0x', or as a decimal value otherwise.
-  property :address
+  property :address, as: 'string'
 
   # Optional raw bytes representing the instruction and its operands, in an implementation-defined format.
-  property :instructionBytes, required: false
+  property :instructionBytes, required: false, as: 'string'
 
   # Text representing the instruction and its operands, in an implementation-defined format.
-  property :instruction
+  property :instruction, as: 'string'
 
   # Name of the symbol that corresponds with the location of this instruction, if any.
-  property :symbol, required: false
+  property :symbol, required: false, as: 'string'
 
   # Source location that corresponds to this instruction, if any.
   # Should always be set (if available) on the first instruction returned,
@@ -19,14 +20,14 @@ class DAP::DisassembledInstruction < DAP::Base
   property :location, required: false, as: DAP::Source
 
   # The line within the source location that corresponds to this instruction, if any.
-  property :line, required: false
+  property :line, required: false, as: 'number'
 
   # The column within the line that corresponds to this instruction, if any.
-  property :column, required: false
+  property :column, required: false, as: 'number'
 
   # The end line of the range that corresponds to this instruction, if any.
-  property :endLine, required: false
+  property :endLine, required: false, as: 'number'
 
   # The end column of the range that corresponds to this instruction, if any.
-  property :endColumn, required: false
+  property :endColumn, required: false, as: 'number'
 end

data/lib/dap/disconnect_arguments.rb

@@ -1,9 +1,10 @@
+# Arguments for ‘disconnect’ request.
 class DAP::DisconnectArguments < DAP::Base
   # A value of true indicates that this 'disconnect' request is part of a restart sequence.
-  property :restart, required: false
+  property :restart, required: false, as: 'boolean'
 
   # Indicates whether the debuggee should be terminated when the debugger is disconnected.
   # If unspecified, the debug adapter is free to do whatever it thinks is best.
   # The attribute is only honored by a debug adapter if the capability 'supportTerminateDebuggee' is true.
-  property :terminateDebuggee, required: false
+  property :terminateDebuggee, required: false, as: 'boolean'
 end

data/lib/dap/encoding.rb

@@ -1,6 +1,11 @@
+# Encoding and decoding for DAP messages
 module DAP::Encoding
+  # The name of the content length header.
   CONTENT_LENGTH_HEADER = 'Content-Length'
 
+  # Decode a DAP message from the stream.
+  # @param s [IO] the stream
+  # @return [ProtocolMessage] the message
   def self.decode(s)
     headers = {}
 
@@ -28,17 +33,23 @@ module DAP::Encoding
     DAP::ProtocolMessage.from(values)
   end
 
+  # Encode a DAP message to a string.
+  # @param message [ProtocolMessage] the message
+  # @return [String] the encoded message
   def self.encode(message)
     raise "Body must be a protocol message" unless message.is_a? DAP::ProtocolMessage
 
     headers = {}
 
     body = JSON.dump(message.to_wire)
-    headers[CONTENT_LENGTH_HEADER] = body.size
+    headers[CONTENT_LENGTH_HEADER] = body.bytesize
 
     headers.map { |name, value| "#{name}: #{value}\r\n" }.join + "\r\n" + body
   end
 
+  # Decode all DAP messages from the stream.
+  # @param s [IO] the stream
+  # @yield Invokes the block for each message
   def self.decode_all(s)
     loop do
       yield decode(s)

data/lib/dap/enum.rb

@@ -1,12 +1,18 @@
+# Base class for DAP enumerations
 class DAP::Enum
+  # Retreive an enumeration instance by value.
+  # @param value [String] the enumeration string value
+  # @return [Enum] the enumeration instance
   def self.from(value)
     values[value]
   end
 
+  # The enumeration string value
   def to_s
     @value
   end
 
+  # The enumeration string value, suitable for encoding
   def to_wire
     @value
   end

data/lib/dap/error_response_body.rb

@@ -1,5 +1,6 @@
 require_relative 'message'
 
+# On error (whenever ‘success’ is false), the body can provide more details.
 class DAP::ErrorResponseBody < DAP::Base
   # An optional, structured error message.
   property :error, required: false, as: DAP::Message

data/lib/dap/evaluate_arguments.rb

@@ -1,11 +1,12 @@
 require_relative 'value_format'
 
+# Arguments for ‘evaluate’ request.
 class DAP::EvaluateArguments < DAP::Base
   # The expression to evaluate.
-  property :expression
+  property :expression, as: 'string'
 
   # Evaluate the expression in the scope of this stack frame. If not specified, the expression is evaluated in the global scope.
-  property :frameId, required: false
+  property :frameId, required: false, as: 'number'
 
   # The context in which the evaluate request is run.
   # Values:
@@ -15,7 +16,7 @@ class DAP::EvaluateArguments < DAP::Base
   # 'clipboard': evaluate is run to generate the value that will be stored in the clipboard.
   # The attribute is only honored by a debug adapter if the capability 'supportsClipboardContext' is true.
   # etc.
-  property :context, required: false # 'watch' | 'repl' | 'hover' | 'clipboard' | string
+  property :context, required: false, as: 'string'
 
   # Specifies details on how to format the Evaluate result.
   # The attribute is only honored by a debug adapter if the capability 'supportsValueFormattingOptions' is true.

data/lib/dap/evaluate_response_body.rb

@@ -1,32 +1,33 @@
 require_relative 'variable_presentation_hint'
 
+# Response to ‘evaluate’ request.
 class DAP::EvaluateResponseBody < DAP::Base
   # The result of the evaluate request.
-  property :result
+  property :result, as: 'string'
 
   # The optional type of the evaluate result.
   # This attribute should only be returned by a debug adapter if the client has passed the value true for the 'supportsVariableType' capability of the 'initialize' request.
-  property :type, required: false
+  property :type, required: false, as: 'string'
 
   # Properties of a evaluate result that can be used to determine how to render the result in the UI.
   property :presentationHint, required: false, as: DAP::VariablePresentationHint
 
   # If variablesReference is > 0, the evaluate result is structured and its children can be retrieved by passing variablesReference to the VariablesRequest.
   # The value should be less than or equal to 2147483647 (2^31 - 1).
-  property :variablesReference
+  property :variablesReference, as: 'number'
 
   # The number of named child variables.
   # The client can use this optional information to present the variables in a paged UI and fetch them in chunks.
   # The value should be less than or equal to 2147483647 (2^31 - 1).
-  property :namedVariables, required: false
+  property :namedVariables, required: false, as: 'number'
 
   # The number of indexed child variables.
   # The client can use this optional information to present the variables in a paged UI and fetch them in chunks.
   # The value should be less than or equal to 2147483647 (2^31 - 1).
-  property :indexedVariables, required: false
+  property :indexedVariables, required: false, as: 'number'
 
   # Optional memory reference to a location appropriate for this result.
   # For pointer type eval results, this is generally a reference to the memory address contained in the pointer.
   # This attribute should be returned by a debug adapter if the client has passed the value true for the 'supportsMemoryReferences' capability of the 'initialize' request.
-  property :memoryReference, required: false
+  property :memoryReference, required: false, as: 'string'
 end