ruby-dap 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 161f235e05d3ede1272cc3b6e4a7a01bb09fefe3c3679ee51a62dd770c0fedd8
-  data.tar.gz: bdc5e6e97b4266cae5d9e0f4e84f279a9d06e869f843c1f05bcbe601dfd6b161
+  metadata.gz: 8d5f279747fa6dcf2cd60bfba40b6d76d4910877bd00b69de4b9f054591955c6
+  data.tar.gz: 3055a809c817620f7fb8eba44736377e2193ba59bc2196823fd55fabf0902cf6
 SHA512:
-  metadata.gz: 10995fbe87a5038f28cd32d6432030e12b7b080dca7b95511691bcb06c7d61dd6efe83b45f61c3e9a8a41ca5ce4bdb06d558c121d0bc2d481ae5406ede86c540
-  data.tar.gz: 72f2ce41850f1980a7388342e9cd1e827a74faf8ccc7b638da676ea8bafec3152658838bc207a411352a2243abd72ae12941e7aec552d0e98878ceb878d26bed
+  metadata.gz: e42f548ee238fc36a1142f9e406e758fd67ded7c7f62f1b7520b2adc7a0d58522332cf49d3e658539d57c33b5230f82ec1dbbc037fccfdcd5ee385cf2821a1db
+  data.tar.gz: 2dcb74846b33be54a8161018233732c4b53fe677bec6cb7b5afd1d1de7bc1e23a52feb1cfbd5ec8edb3d7864ece410a1e2eec74409b3bb8d104f67197720b32d

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change Log
 
+## 0.1.3
+
+- Fixed a unicode encoding error related to `String#size` vs `String#bytesize`
+
 ## 0.1.2
 
 - Support for custom events, requests, and responses

data/README.md

@@ -1,3 +1,5 @@
+[![Gem Version](https://badge.fury.io/rb/ruby-dap.svg)](https://badge.fury.io/rb/ruby-dap) [![Documentation](https://img.shields.io/static/v1?label=docs&message=master&color=informational&style=flat)](https://firelizzard.gitlab.io/ruby-dap/)
+
 # Ruby Debug Adapter Protocol
 
 This gem provides models, parsers, and formatters for the [Debug Adapter
@@ -11,6 +13,18 @@ specification](https://microsoft.github.io/debug-adapter-protocol/specification)
 to Ruby classes. To regenerate the Ruby classes, set `PRETEND = false` in the
 file and run `echo <spec> | ruby convert.rb -` or `ruby convert.rb <spec-file>`.
 If the input contains multiple files, `convert.rb` expects them to be separated
-with `\n\n// ---\n\n`. All of the specs can be extracted at once by running
-`$('.language-typescript').toArray().map(x => x.innerText).join('\n\n//
----\n\n')` in the browser JavaScript console.
+with `\n\n// ---\n\n`. All of the specs can be extracted at once by running the
+following in the browser JavaScript console:
+
+
+```javascript
+$('.language-typescript').toArray().map(x => {
+    let t = x.innerText;
+    x = $(x);
+    let s = [];
+    for (x = x.prev('p, ul'); x.length; x = x.prev('p, ul'))
+        s.unshift(...x.text().split('\n').filter(x => x.indexOf('Values: ') != 0));
+    if (!s.length) return t;
+    return s.map(x => '// ' + x).join('\n') + '\n' + t;
+}).join('\n\n// ---\n\n')
+```

data/lib/dap.rb

@@ -1,14 +1,18 @@
 require 'json'
 
+# The Debug Adapter Protocol
 module DAP
+  # (see DAP::Encoding.decode)
   def self.decode(s)
     DAP::Encoding.decode(s)
   end
 
+  # (see DAP::Encoding.encode)
   def self.encode(message)
     DAP::Encoding.encode(message)
   end
 
+  # (see DAP::Encoding.decode_all)
   def self.decode_all(s, &block)
     DAP::Encoding.decode_all(s, &block)
   end

data/lib/dap/attach_request_arguments.rb

@@ -1,3 +1,5 @@
+# Arguments for ‘attach’ request. Additional attributes are implementation
+# specific.
 class DAP::AttachRequestArguments < DAP::Base
   # Optional data from the previous, restarted session.
   # The data is sent as the 'restart' attribute of the 'terminated' event.

data/lib/dap/base.rb

@@ -1,4 +1,9 @@
+# Base class for DAP types
 class DAP::Base
+  # Build an instance of a DAP type.
+  # @param values [Hash|String] attribute values or enum string
+  # @yieldparam values [Hash] normalized attribute values (optional)
+  # @yieldreturn [Class] the class to instantiate
   def self.build(values, &block)
     values.transform_keys! &:to_sym if values.is_a? Hash
 
@@ -15,18 +20,32 @@ class DAP::Base
     klazz.new(values)
   end
 
+  # Returns a relation that indicates a property should be an array of the
+  # specified type.
+  # @param klazz [Class] the expected type of members of the property
+  # @return [Relation::Many]
   def self.many(klazz)
     DAP::Relation::Many.new(klazz)
   end
 
+  # Returns a relation that indicates a property should be one of a set of
+  # types.
+  # @param choices [Hash[String, Class]] the allowed property types
+  # @return [Relation::OneOf]
   def self.one_of(choices)
     DAP::Relation::OneOf.new(choices)
   end
 
+  # Returns a relation that indicates a property is expected to be an empty
+  # object.
   def self.empty
     Class.new(DAP::Base)
   end
 
+  # Defines a property or properties.
+  # @param names [Array<Symbol>] the properties
+  # @param as [Class|Relation|String] the expected type of the property
+  # @param required [Boolean] whether the property is required
   def self.property(*names, as: nil, required: true)
     @properties ||= []
     @transformations ||= {}
@@ -34,15 +53,19 @@ class DAP::Base
     klazz = name
 
     names.each do |name|
-      if as.is_a?(Class)
+      case as
+      when nil, String
+        # ignore
+
+      when Class
         DAP::Relation.supported!(as)
 
         transform = ->(value, values, invert: false) { value.nil? ? nil : invert ? value.to_wire : build(value || {}) { as } }
 
-      elsif as.is_a? DAP::Relation::Many
+      when DAP::Relation::Many
         transform = ->(value, values, invert: false) { value.nil? ? nil : invert ? value.map(&:to_wire) : value.map { |v| build(v) { as.klazz } } }
 
-      elsif as.is_a? DAP::Relation::OneOf
+      when DAP::Relation::OneOf
         transform = ->(value, values, invert: false) do
           return value.to_wire if invert
 
@@ -55,7 +78,7 @@ class DAP::Base
           end
         end
 
-      elsif !as.nil?
+      else
         raise "Invalid property constraint: #{as.class} #{as.inspect}"
       end
 
@@ -70,6 +93,7 @@ class DAP::Base
     attr_reader(*names)
   end
 
+  # Properties of the receiver.
   def self.properties
     @properties ||= []
     return @properties if self == DAP::Base
@@ -77,16 +101,22 @@ class DAP::Base
     superclass.properties + @properties
   end
 
+  # Names of the receiver's properties.
   def self.property_names
     properties.map { |p| p[:name] }
   end
 
+  # Retreives the transform for the named property.
+  # @param name [String] the property name
+  # @return [Proc] the transform
   def self.transform(name)
     (@properties || []).each { |p| return p[:transform] if p[:name] == name && p[:transform] }
 
     return superclass.transform(name) unless self == DAP::Base
   end
 
+  # Create a new instance of the receiver.
+  # @param values [Hash] the object's attributes
   def initialize(values)
     values.transform_keys!(&:to_sym)
 
@@ -100,6 +130,7 @@ class DAP::Base
     end
   end
 
+  # Validate property values against their expectations.
   def validate!
     self.class.properties.each do |p|
       key, required = p[:name], p[:required]
@@ -119,13 +150,18 @@ class DAP::Base
     self
   end
 
+  # Convert the receiver to a form suitable for encoding.
+  # @return [Hash]
   def to_wire
     self.class.property_names.each_with_object({}) do |k, h|
       v = self[k]
       next if v.nil?
 
-      transform = self.class.transform(k)
-      v = transform.call(v, self, invert: true) if transform
+      if transform = self.class.transform(k)
+        v = transform.call(v, self, invert: true) if transform
+      else
+        v = convert_complex(v)
+      end
 
       h[k] = v
     end
@@ -142,4 +178,19 @@ class DAP::Base
     key = key.to_sym
     instance_variable_set("@#{key}".to_sym, value)
   end
+
+  def convert_complex(v)
+    case v
+    when Array
+      v.map { |v| convert_complex(v) }
+    when Hash
+      v.transform_values { |v| convert_complex(v) }
+    when DAP::Base, DAP::Enum
+      v.to_wire
+    when String
+      v.encode('UTF-8', invalid: :replace, undef: :replace, replace: '?')
+    else
+      v
+    end
+  end
 end

data/lib/dap/breakpoint.rb

@@ -1,36 +1,38 @@
 require_relative 'source'
 
+# Information about a Breakpoint created in setBreakpoints,
+# setFunctionBreakpoints, setInstructionBreakpoints, or setDataBreakpoints.
 class DAP::Breakpoint < DAP::Base
   # An optional identifier for the breakpoint. It is needed if breakpoint events are used to update or remove breakpoints.
-  property :id, required: false
+  property :id, required: false, as: 'number'
 
   # If true breakpoint could be set (but not necessarily at the desired location).
-  property :verified
+  property :verified, as: 'boolean'
 
   # An optional message about the state of the breakpoint.
   # This is shown to the user and can be used to explain why a breakpoint could not be verified.
-  property :message, required: false
+  property :message, required: false, as: 'string'
 
   # The source where the breakpoint is located.
   property :source, required: false, as: DAP::Source
 
   # The start line of the actual range covered by the breakpoint.
-  property :line, required: false
+  property :line, required: false, as: 'number'
 
   # An optional start column of the actual range covered by the breakpoint.
-  property :column, required: false
+  property :column, required: false, as: 'number'
 
   # An optional end line of the actual range covered by the breakpoint.
-  property :endLine, required: false
+  property :endLine, required: false, as: 'number'
 
   # An optional end column of the actual range covered by the breakpoint.
   # If no end line is given, then the end column is assumed to be in the start line.
-  property :endColumn, required: false
+  property :endColumn, required: false, as: 'number'
 
   # An optional memory reference to where the breakpoint is set.
-  property :instructionReference, required: false
+  property :instructionReference, required: false, as: 'string'
 
   # An optional offset from the instruction reference.
   # This can be negative.
-  property :offset, required: false
+  property :offset, required: false, as: 'number'
 end

data/lib/dap/breakpoint_event_body.rb

@@ -1,9 +1,10 @@
 require_relative 'breakpoint'
 
+# The event indicates that some information about a breakpoint has changed.
 class DAP::BreakpointEventBody < DAP::Base
   # The reason for the event.
   # Values: 'changed', 'new', 'removed', etc.
-  property :reason # 'changed' | 'new' | 'removed' | string
+  property :reason, as: 'string'
 
   # The 'id' attribute is used to find the target breakpoint and the other attributes are used as the new values.
   property :breakpoint, as: DAP::Breakpoint

data/lib/dap/breakpoint_location.rb

@@ -1,13 +1,15 @@
+# Properties of a breakpoint location returned from the ‘breakpointLocations’
+# request.
 class DAP::BreakpointLocation < DAP::Base
   # Start line of breakpoint location.
-  property :line
+  property :line, as: 'number'
 
   # Optional start column of breakpoint location.
-  property :column, required: false
+  property :column, required: false, as: 'number'
 
   # Optional end line of breakpoint location if the location covers a range.
-  property :endLine, required: false
+  property :endLine, required: false, as: 'number'
 
   # Optional end column of breakpoint location if the location covers a range.
-  property :endColumn, required: false
+  property :endColumn, required: false, as: 'number'
 end

data/lib/dap/breakpoint_locations_arguments.rb

@@ -1,18 +1,19 @@
 require_relative 'source'
 
+# Arguments for ‘breakpointLocations’ request.
 class DAP::BreakpointLocationsArguments < DAP::Base
   # The source location of the breakpoints; either 'source.path' or 'source.reference' must be specified.
   property :source, as: DAP::Source
 
   # Start line of range to search possible breakpoint locations in. If only the line is specified, the request returns all possible locations in that line.
-  property :line
+  property :line, as: 'number'
 
   # Optional start column of range to search possible breakpoint locations in. If no start column is given, the first column in the start line is assumed.
-  property :column, required: false
+  property :column, required: false, as: 'number'
 
   # Optional end line of range to search possible breakpoint locations in. If no end line is given, then the end line is assumed to be the start line.
-  property :endLine, required: false
+  property :endLine, required: false, as: 'number'
 
   # Optional end column of range to search possible breakpoint locations in. If no end column is given, then it is assumed to be in the last column of the end line.
-  property :endColumn, required: false
+  property :endColumn, required: false, as: 'number'
 end

data/lib/dap/breakpoint_locations_response_body.rb

@@ -1,5 +1,7 @@
 require_relative 'breakpoint_location'
 
+# Response to ‘breakpointLocations’ request. Contains possible locations for
+# source breakpoints.
 class DAP::BreakpointLocationsResponseBody < DAP::Base
   # Sorted set of possible breakpoint locations.
   property :breakpoints, as: many(DAP::BreakpointLocation)

data/lib/dap/cancel_arguments.rb

@@ -1,9 +1,10 @@
+# Arguments for ‘cancel’ request.
 class DAP::CancelArguments < DAP::Base
   # The ID (attribute 'seq') of the request to cancel. If missing no request is cancelled.
   # Both a 'requestId' and a 'progressId' can be specified in one request.
-  property :requestId, required: false
+  property :requestId, required: false, as: 'number'
 
   # The ID (attribute 'progressId') of the progress to cancel. If missing no progress is cancelled.
   # Both a 'requestId' and a 'progressId' can be specified in one request.
-  property :progressId, required: false
+  property :progressId, required: false, as: 'string'
 end

data/lib/dap/capabilities.rb

@@ -2,48 +2,49 @@ require_relative 'exception_breakpoints_filter'
 require_relative 'column_descriptor'
 require_relative 'checksum_algorithm'
 
+# Information about the capabilities of a debug adapter.
 class DAP::Capabilities < DAP::Base
   # The debug adapter supports the 'configurationDone' request.
-  property :supportsConfigurationDoneRequest, required: false
+  property :supportsConfigurationDoneRequest, required: false, as: 'boolean'
 
   # The debug adapter supports function breakpoints.
-  property :supportsFunctionBreakpoints, required: false
+  property :supportsFunctionBreakpoints, required: false, as: 'boolean'
 
   # The debug adapter supports conditional breakpoints.
-  property :supportsConditionalBreakpoints, required: false
+  property :supportsConditionalBreakpoints, required: false, as: 'boolean'
 
   # The debug adapter supports breakpoints that break execution after a specified number of hits.
-  property :supportsHitConditionalBreakpoints, required: false
+  property :supportsHitConditionalBreakpoints, required: false, as: 'boolean'
 
   # The debug adapter supports a (side effect free) evaluate request for data hovers.
-  property :supportsEvaluateForHovers, required: false
+  property :supportsEvaluateForHovers, required: false, as: 'boolean'
 
   # Available filters or options for the setExceptionBreakpoints request.
   property :exceptionBreakpointFilters, required: false, as: many(DAP::ExceptionBreakpointsFilter)
 
   # The debug adapter supports stepping back via the 'stepBack' and 'reverseContinue' requests.
-  property :supportsStepBack, required: false
+  property :supportsStepBack, required: false, as: 'boolean'
 
   # The debug adapter supports setting a variable to a value.
-  property :supportsSetVariable, required: false
+  property :supportsSetVariable, required: false, as: 'boolean'
 
   # The debug adapter supports restarting a frame.
-  property :supportsRestartFrame, required: false
+  property :supportsRestartFrame, required: false, as: 'boolean'
 
   # The debug adapter supports the 'gotoTargets' request.
-  property :supportsGotoTargetsRequest, required: false
+  property :supportsGotoTargetsRequest, required: false, as: 'boolean'
 
   # The debug adapter supports the 'stepInTargets' request.
-  property :supportsStepInTargetsRequest, required: false
+  property :supportsStepInTargetsRequest, required: false, as: 'boolean'
 
   # The debug adapter supports the 'completions' request.
-  property :supportsCompletionsRequest, required: false
+  property :supportsCompletionsRequest, required: false, as: 'boolean'
 
   # The set of characters that should trigger completion in a REPL. If not specified, the UI should assume the '.' character.
-  property :completionTriggerCharacters, required: false
+  property :completionTriggerCharacters, required: false, as: 'string[]'
 
   # The debug adapter supports the 'modules' request.
-  property :supportsModulesRequest, required: false
+  property :supportsModulesRequest, required: false, as: 'boolean'
 
   # The set of additional module information exposed by the debug adapter.
   property :additionalModuleColumns, required: false, as: many(DAP::ColumnDescriptor)
@@ -52,59 +53,59 @@ class DAP::Capabilities < DAP::Base
   property :supportedChecksumAlgorithms, required: false, as: many(DAP::ChecksumAlgorithm)
 
   # The debug adapter supports the 'restart' request. In this case a client should not implement 'restart' by terminating and relaunching the adapter but by calling the RestartRequest.
-  property :supportsRestartRequest, required: false
+  property :supportsRestartRequest, required: false, as: 'boolean'
 
   # The debug adapter supports 'exceptionOptions' on the setExceptionBreakpoints request.
-  property :supportsExceptionOptions, required: false
+  property :supportsExceptionOptions, required: false, as: 'boolean'
 
   # The debug adapter supports a 'format' attribute on the stackTraceRequest, variablesRequest, and evaluateRequest.
-  property :supportsValueFormattingOptions, required: false
+  property :supportsValueFormattingOptions, required: false, as: 'boolean'
 
   # The debug adapter supports the 'exceptionInfo' request.
-  property :supportsExceptionInfoRequest, required: false
+  property :supportsExceptionInfoRequest, required: false, as: 'boolean'
 
   # The debug adapter supports the 'terminateDebuggee' attribute on the 'disconnect' request.
-  property :supportTerminateDebuggee, required: false
+  property :supportTerminateDebuggee, required: false, as: 'boolean'
 
   # The debug adapter supports the delayed loading of parts of the stack, which requires that both the 'startFrame' and 'levels' arguments and the 'totalFrames' result of the 'StackTrace' request are supported.
-  property :supportsDelayedStackTraceLoading, required: false
+  property :supportsDelayedStackTraceLoading, required: false, as: 'boolean'
 
   # The debug adapter supports the 'loadedSources' request.
-  property :supportsLoadedSourcesRequest, required: false
+  property :supportsLoadedSourcesRequest, required: false, as: 'boolean'
 
   # The debug adapter supports logpoints by interpreting the 'logMessage' attribute of the SourceBreakpoint.
-  property :supportsLogPoints, required: false
+  property :supportsLogPoints, required: false, as: 'boolean'
 
   # The debug adapter supports the 'terminateThreads' request.
-  property :supportsTerminateThreadsRequest, required: false
+  property :supportsTerminateThreadsRequest, required: false, as: 'boolean'
 
   # The debug adapter supports the 'setExpression' request.
-  property :supportsSetExpression, required: false
+  property :supportsSetExpression, required: false, as: 'boolean'
 
   # The debug adapter supports the 'terminate' request.
-  property :supportsTerminateRequest, required: false
+  property :supportsTerminateRequest, required: false, as: 'boolean'
 
   # The debug adapter supports data breakpoints.
-  property :supportsDataBreakpoints, required: false
+  property :supportsDataBreakpoints, required: false, as: 'boolean'
 
   # The debug adapter supports the 'readMemory' request.
-  property :supportsReadMemoryRequest, required: false
+  property :supportsReadMemoryRequest, required: false, as: 'boolean'
 
   # The debug adapter supports the 'disassemble' request.
-  property :supportsDisassembleRequest, required: false
+  property :supportsDisassembleRequest, required: false, as: 'boolean'
 
   # The debug adapter supports the 'cancel' request.
-  property :supportsCancelRequest, required: false
+  property :supportsCancelRequest, required: false, as: 'boolean'
 
   # The debug adapter supports the 'breakpointLocations' request.
-  property :supportsBreakpointLocationsRequest, required: false
+  property :supportsBreakpointLocationsRequest, required: false, as: 'boolean'
 
   # The debug adapter supports the 'clipboard' context value in the 'evaluate' request.
-  property :supportsClipboardContext, required: false
+  property :supportsClipboardContext, required: false, as: 'boolean'
 
   # The debug adapter supports stepping granularities (argument 'granularity') for the stepping requests.
-  property :supportsSteppingGranularity, required: false
+  property :supportsSteppingGranularity, required: false, as: 'boolean'
 
   # The debug adapter supports adding breakpoints based on instruction references.
-  property :supportsInstructionBreakpoints, required: false
+  property :supportsInstructionBreakpoints, required: false, as: 'boolean'
 end