add a 'breakpointLocations' request

Author: weinand

_data/specification-toc.yml

@@ -47,6 +47,8 @@
     children:
     - title: Attach
       anchor: Requests_Attach
+    - title: BreakpointLocations
+      anchor: Requests_BreakpointLocations
     - title: Completions
       anchor: Requests_Completions
     - title: ConfigurationDone
@@ -131,6 +133,8 @@
     children:
     - title: Breakpoint
       anchor: Types_Breakpoint
+    - title: BreakpointLocation
+      anchor: Types_BreakpointLocation
     - title: Capabilities
       anchor: Types_Capabilities
     - title: Checksum

changelog.md

@@ -7,6 +7,7 @@ sectionid: changelog
 #### All notable changes to the specification will be documented in this file.
 
 * 1.37.x:
+  * Adds a `breakpointLocations` request (and a corresponding `supportsBreakpointLocationsRequest` capability) for finding the possible breakpoints for a source range.
   * Adds cancellation support for requests via a new `cancel` request and a corresponding `supportsCancelRequest` capability.
   * Improves some comments.
 

debugAdapterProtocol.json

@@ -884,6 +884,73 @@
 			}]
 		},
 
+		"BreakpointLocationsRequest": {
+			"allOf": [ { "$ref": "#/definitions/Request" }, {
+				"type": "object",
+				"description": "The 'breakpointLocations' request returns all possible locations for source breakpoints in a given range.",
+				"properties": {
+					"command": {
+						"type": "string",
+						"enum": [ "breakpointLocations" ]
+					},
+					"arguments": {
+						"$ref": "#/definitions/BreakpointLocationsArguments"
+					}
+				},
+				"required": [ "command" ]
+			}]
+
+		},
+		"BreakpointLocationsArguments": {
+			"type": "object",
+			"description": "Arguments for 'breakpointLocations' request.",
+			"properties": {
+				"source": {
+					"$ref": "#/definitions/Source",
+					"description": "The source location of the breakpoints; either 'source.path' or 'source.reference' must be specified."
+				},
+				"line": {
+					"type": "integer",
+					"description": "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."
+				},
+				"column": {
+					"type": "integer",
+					"description": "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."
+				},
+				"endLine": {
+					"type": "integer",
+					"description": "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."
+				},
+				"endColumn": {
+					"type": "integer",
+					"description": "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."
+				}
+			},
+			"required": [ "source", "line" ]
+		},
+		"BreakpointLocationsResponse": {
+			"allOf": [ { "$ref": "#/definitions/Response" }, {
+				"type": "object",
+				"description": "Response to 'breakpointLocations' request.\nContains possible locations for source breakpoints.",
+				"properties": {
+					"body": {
+						"type": "object",
+						"properties": {
+							"breakpoints": {
+								"type": "array",
+								"items": {
+									"$ref": "#/definitions/BreakpointLocation"
+								},
+								"description": "Sorted set of possible breakpoint locations."
+							}
+						},
+						"required": [ "breakpoints" ]
+					}
+				},
+				"required": [ "body" ]
+			}]
+		},
+
 		"SetBreakpointsRequest": {
 			"allOf": [ { "$ref": "#/definitions/Request" }, {
 				"type": "object",
@@ -2643,6 +2710,10 @@
 				"supportsCancelRequest": {
 					"type": "boolean",
 					"description": "The debug adapter supports the 'cancel' request."
+				},
+				"supportsBreakpointLocationsRequest": {
+					"type": "boolean",
+					"description": "The debug adapter supports the 'breakpointLocations' request."
 				}
 			}
 		},
@@ -3058,6 +3129,30 @@
 			}
 		},
 
+		"BreakpointLocation": {
+			"type": "object",
+			"description": "Properties of a breakpoint location returned from the 'breakpointLocations' request.",
+			"properties": {
+				"line": {
+					"type": "integer",
+					"description": "Start line of breakpoint location."
+				},
+				"column": {
+					"type": "integer",
+					"description": "Optional start column of breakpoint location."
+				},
+				"endLine": {
+					"type": "integer",
+					"description": "Optional end line of breakpoint location if the location covers a range."
+				},
+				"endColumn": {
+					"type": "integer",
+					"description": "Optional end column of breakpoint location if the location covers a range."
+				}
+			},
+			"required": [ "line" ]
+		},
+
 		"SourceBreakpoint": {
 			"type": "object",
 			"description": "Properties of a breakpoint or logpoint passed to the setBreakpoints request.",

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.36.
+                The latest version of the protocol specification is version 1.37.
             </p>
             <p>
                 <a href='{{ "/changelog" | prepend: site.baseurl }}'>Change History</a>

specification.md

@@ -870,6 +870,66 @@ interface TerminateResponse extends Response {
 }
 ```
 
+### <a name="Requests_BreakpointLocations" class="anchor"></a>:leftwards_arrow_with_hook: BreakpointLocations Request
+
+The 'breakpointLocations' request returns all possible locations for source breakpoints in a given range.
+
+```typescript
+interface BreakpointLocationsRequest extends Request {
+  command: 'breakpointLocations';
+
+  arguments?: BreakpointLocationsArguments;
+}
+```
+
+Arguments for 'breakpointLocations' request.
+
+<a name="Types_BreakpointLocationsArguments" class="anchor"></a>
+```typescript
+interface BreakpointLocationsArguments {
+  /**
+   * The source location of the breakpoints; either 'source.path' or 'source.reference' must be specified.
+   */
+  source: 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.
+   */
+  line: 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.
+   */
+  column?: 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.
+   */
+  endLine?: 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.
+   */
+  endColumn?: number;
+}
+```
+
+Response to 'breakpointLocations' request.
+
+Contains possible locations for source breakpoints.
+
+<a name="Types_BreakpointLocationsResponse" class="anchor"></a>
+```typescript
+interface BreakpointLocationsResponse extends Response {
+  body: {
+    /**
+     * Sorted set of possible breakpoint locations.
+     */
+    breakpoints: BreakpointLocation[];
+  };
+}
+```
+
 ### <a name="Requests_SetBreakpoints" class="anchor"></a>:leftwards_arrow_with_hook: SetBreakpoints Request
 
 Sets multiple breakpoints for a single source and clears all previous breakpoints in that source.
@@ -2520,6 +2580,11 @@ interface Capabilities {
    * The debug adapter supports the 'cancel' request.
    */
   supportsCancelRequest?: boolean;
+
+  /**
+   * The debug adapter supports the 'breakpointLocations' request.
+   */
+  supportsBreakpointLocationsRequest?: boolean;
 }
 ```
 
@@ -3017,6 +3082,34 @@ interface VariablePresentationHint {
 }
 ```
 
+### <a name="Types_BreakpointLocation" class="anchor"></a>BreakpointLocation
+
+Properties of a breakpoint location returned from the 'breakpointLocations' request.
+
+```typescript
+interface BreakpointLocation {
+  /**
+   * Start line of breakpoint location.
+   */
+  line: number;
+
+  /**
+   * Optional start column of breakpoint location.
+   */
+  column?: number;
+
+  /**
+   * Optional end line of breakpoint location if the location covers a range.
+   */
+  endLine?: number;
+
+  /**
+   * Optional end column of breakpoint location if the location covers a range.
+   */
+  endColumn?: number;
+}
+```
+
 ### <a name="Types_SourceBreakpoint" class="anchor"></a>SourceBreakpoint
 
 Properties of a breakpoint or logpoint passed to the setBreakpoints request.