Merge pull request #430 from microsoft/main

Release 1.63

_implementors/adapters.md

@@ -62,7 +62,7 @@ Many adapters publish releases tailored for specific editors, such as VS Code, a
 [OCaml Earlybird](https://github.com/hackwaly/ocamlearlybird)|[@sim642](https://github.com/sim642)|[VS Code](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform)
 [OneScript Debug](https://github.com/EvilBeaver/OneScript)|[@EvilBeaver](https://github.com/EvilBeaver)|[VS Code](https://marketplace.visualstudio.com/items?itemName=EvilBeaver.oscript-debug)
 [Papyrus](https://github.com/joelday/papyrus-debug-server)|[@joelday](https://github.com/joelday)|[VS Code](https://marketplace.visualstudio.com/items?itemName=joelday.papyrus-lang-vscode)
-[Perl Debug](https://github.com/raix/vscode-perl-debug)|[@raix](https://github.com/raix)|[VS Code](https://marketplace.visualstudio.com/items?itemName=mortenhenriksen.perl-debug)
+[Perl Debug](https://github.com/Nihilus118/vscode-perl-debug)|[@Nihilus118](https://github.com/Nihilus118)|[VS Code](https://marketplace.visualstudio.com/items?itemName=Nihilus118.perl-debugger)
 [Perl::LanguageServer](https://github.com/richterger/Perl-LanguageServer)|[@richterger](https://github.com/richterger)|[VS Code](https://marketplace.visualstudio.com/items?itemName=richterger.perl)
 [Php](https://github.com/xdebug/vscode-php-debug)|[@zobo](https://github.com/zobo)|[VS Code](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug)
 [PowerShell](https://github.com/PowerShell/vscode-powershell)|[@daviwil](https://github.com/daviwil) [@rkeithhill](https://github.com/rkeithhill)|[VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell)

changelog.md

@@ -6,6 +6,13 @@ sectionid: changelog
 
 #### All notable changes to the specification will be documented in this file.
 
+* 1.63.x
+  * Add `memoryReference` support to the `SetVariableResponse`/`SetExpressionResponse`
+  * Fix a typo in the description of `BreakpointLocationsArguments`
+  * Fix missing line break in `CancelRequest`
+  * Clarify `memoryReference` in `Variable` type
+  * Clarify state of "object ID"s in `VariablePresentationHint`
+
 * 1.62.x
   * Clarify lifetime of `DataBreakpoint.dataId`
 
@@ -19,6 +26,7 @@ sectionid: changelog
 
 * 1.59.x:
   * Add an optional `frameId` to the `DataBreakpointInfoRequest`
+  * Add `notStopped` as a well-known reason in `Response`
   * Clarify the lifetime of `variablesReference`.
   * Clarify the default behavior when `kind` is omitted from the `RunInTerminalRequest`.
   * Clarify end of file behavior for `readMemory`.

debugAdapterProtocol.json

@@ -130,7 +130,7 @@
 		"CancelRequest": {
 			"allOf": [ { "$ref": "#/definitions/Request" }, {
 				"type": "object",
-				"description": "The `cancel` request is used by the client in two situations:\n- to indicate that it is no longer interested in the result produced by a specific request issued earlier\n- to cancel a progress sequence. Clients should only call this request if the corresponding capability `supportsCancelRequest` is true.\nThis request has a hint characteristic: a debug adapter can only be expected to make a 'best effort' in honoring this request but there are no guarantees.\nThe `cancel` request may return an error if it could not cancel an operation but a client should refrain from presenting this error to end users.\nThe request that got cancelled still needs to send a response back. This can either be a normal result (`success` attribute true) or an error response (`success` attribute false and the `message` set to `cancelled`).\nReturning partial results from a cancelled request is possible but please note that a client has no generic way for detecting that a response is partial or not.\nThe progress that got cancelled still needs to send a `progressEnd` event back.\n A client should not assume that progress just got cancelled after sending the `cancel` request.",
+				"description": "The `cancel` request is used by the client in two situations:\n- to indicate that it is no longer interested in the result produced by a specific request issued earlier\n- to cancel a progress sequence.\nClients should only call this request if the corresponding capability `supportsCancelRequest` is true.\nThis request has a hint characteristic: a debug adapter can only be expected to make a 'best effort' in honoring this request but there are no guarantees.\nThe `cancel` request may return an error if it could not cancel an operation but a client should refrain from presenting this error to end users.\nThe request that got cancelled still needs to send a response back. This can either be a normal result (`success` attribute true) or an error response (`success` attribute false and the `message` set to `cancelled`).\nReturning partial results from a cancelled request is possible but please note that a client has no generic way for detecting that a response is partial or not.\nThe progress that got cancelled still needs to send a `progressEnd` event back.\n A client should not assume that progress just got cancelled after sending the `cancel` request.",
 				"properties": {
 					"command": {
 						"type": "string",
@@ -1202,7 +1202,7 @@
 			"properties": {
 				"source": {
 					"$ref": "#/definitions/Source",
-					"description": "The source location of the breakpoints; either `source.path` or `source.reference` must be specified."
+					"description": "The source location of the breakpoints; either `source.path` or `source.sourceReference` must be specified."
 				},
 				"line": {
 					"type": "integer",
@@ -2228,6 +2228,10 @@
 							"indexedVariables": {
 								"type": "integer",
 								"description": "The number of indexed child variables.\nThe client can use this information to present the variables in a paged UI and fetch them in chunks.\nThe value should be less than or equal to 2147483647 (2^31-1)."
+							},
+							"memoryReference": {
+								"type": "string",
+								"description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true."
 							}
 						},
 						"required": [ "value" ]
@@ -2545,7 +2549,7 @@
 							},
 							"memoryReference": {
 								"type": "string",
-								"description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute should be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true."
+								"description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true."
 							}
 						},
 						"required": [ "result", "variablesReference" ]
@@ -2625,6 +2629,10 @@
 							"indexedVariables": {
 								"type": "integer",
 								"description": "The number of indexed child variables.\nThe client can use this information to present the variables in a paged UI and fetch them in chunks.\nThe value should be less than or equal to 2147483647 (2^31-1)."
+							},
+							"memoryReference": {
+								"type": "string",
+								"description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true."
 							}
 						},
 						"required": [ "value" ]
@@ -3587,7 +3595,7 @@
 				},
 				"memoryReference": {
 					"type": "string",
-					"description": "The memory reference for the variable if the variable represents executable code, such as a function pointer.\nThis attribute is only required if the corresponding capability `supportsMemoryReferences` is true."
+					"description": "A memory reference associated with this variable.\nFor pointer type variables, this is generally a reference to the memory address contained in the pointer.\nFor executable data, this reference may later be used in a `disassemble` request.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true."
 				}
 			},
 			"required": [ "name", "value", "variablesReference" ]
@@ -3626,8 +3634,8 @@
 							"Indicates that the object is a constant.",
 							"Indicates that the object is read only.",
 							"Indicates that the object is a raw string.",
-							"Indicates that the object can have an Object ID created for it.",
-							"Indicates that the object has an Object ID associated with it.",
+							"Indicates that the object can have an Object ID created for it. This is a vestigial attribute that is used by some clients; 'Object ID's are not specified in the protocol.",
+							"Indicates that the object has an Object ID associated with it. This is a vestigial attribute that is used by some clients; 'Object ID's are not specified in the protocol.",
 							"Indicates that the evaluation had side effects.",
 							"Indicates that the object has its value tracked by a data breakpoint."
 						]

index.html

@@ -86,7 +86,7 @@ <h1 class="text-center"><i class="fa fa-cogs" aria-hidden="true"></i></h1>
             <h1 class="text-center"><i class="fas fa-book" aria-hidden="true"></i></h1>
             <a href='{{ "/specification" | prepend: site.baseurl }}'><h3 class="text-center">Specification</h3></a>
             <p>
-                The latest version of the protocol specification is version 1.62.0.
+                The latest version of the protocol specification is version 1.63.0.
             </p>
             <p>
                 <a href='{{ "/changelog" | prepend: site.baseurl }}'>Change History</a>

specification.md

@@ -149,7 +149,9 @@ interface ErrorResponse extends Response {
 
 The `cancel` request is used by the client in two situations:
 - to indicate that it is no longer interested in the result produced by a specific request issued earlier
-- to cancel a progress sequence. Clients should only call this request if the corresponding capability `supportsCancelRequest` is true.
+- to cancel a progress sequence.
+
+Clients should only call this request if the corresponding capability `supportsCancelRequest` is true.
 
 This request has a hint characteristic: a debug adapter can only be expected to make a 'best effort' in honoring this request but there are no guarantees.
 
@@ -1306,7 +1308,7 @@ Arguments for `breakpointLocations` request.
 interface BreakpointLocationsArguments {
   /**
    * The source location of the breakpoints; either `source.path` or
-   * `source.reference` must be specified.
+   * `source.sourceReference` must be specified.
    */
   source: Source;
 
@@ -2396,6 +2398,15 @@ interface SetVariableResponse extends Response {
      * The value should be less than or equal to 2147483647 (2^31-1).
      */
     indexedVariables?: number;
+
+    /**
+     * A 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 may be returned by a debug adapter if corresponding
+     * capability `supportsMemoryReferences` is true.
+     */
+    memoryReference?: string;
   };
 }
 ```
@@ -2703,7 +2714,7 @@ interface EvaluateResponse extends Response {
      * A 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 corresponding
+     * This attribute may be returned by a debug adapter if corresponding
      * capability `supportsMemoryReferences` is true.
      */
     memoryReference?: string;
@@ -2804,6 +2815,15 @@ interface SetExpressionResponse extends Response {
      * The value should be less than or equal to 2147483647 (2^31-1).
      */
     indexedVariables?: number;
+
+    /**
+     * A 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 may be returned by a debug adapter if corresponding
+     * capability `supportsMemoryReferences` is true.
+     */
+    memoryReference?: string;
   };
 }
 ```
@@ -3978,10 +3998,13 @@ interface Variable {
   indexedVariables?: number;
 
   /**
-   * The memory reference for the variable if the variable represents executable
-   * code, such as a function pointer.
-   * This attribute is only required if the corresponding capability
-   * `supportsMemoryReferences` is true.
+   * A memory reference associated with this variable.
+   * For pointer type variables, this is generally a reference to the memory
+   * address contained in the pointer.
+   * For executable data, this reference may later be used in a `disassemble`
+   * request.
+   * This attribute may be returned by a debug adapter if corresponding
+   * capability `supportsMemoryReferences` is true.
    */
   memoryReference?: string;
 }
@@ -4027,9 +4050,11 @@ interface VariablePresentationHint {
    * 'readOnly': Indicates that the object is read only.
    * 'rawString': Indicates that the object is a raw string.
    * 'hasObjectId': Indicates that the object can have an Object ID created for
-   * it.
+   * it. This is a vestigial attribute that is used by some clients; 'Object
+   * ID's are not specified in the protocol.
    * 'canHaveObjectId': Indicates that the object has an Object ID associated
-   * with it.
+   * with it. This is a vestigial attribute that is used by some clients;
+   * 'Object ID's are not specified in the protocol.
    * 'hasSideEffects': Indicates that the evaluation had side effects.
    * 'hasDataBreakpoint': Indicates that the object has its value tracked by a
    * data breakpoint.