add support for conditional exceptions; fixes #137

_data/specification-toc.yml

@@ -169,6 +169,8 @@
       anchor: Types_ExceptionBreakpointsFilter
     - title: ExceptionDetails
       anchor: Types_ExceptionDetails
+    - title: ExceptionFilterOptions
+      anchor: Types_ExceptionFilterOptions
     - title: ExceptionOptions
       anchor: Types_ExceptionOptions
     - title: ExceptionPathSegment

changelog.md

@@ -6,6 +6,10 @@ sectionid: changelog
 
 #### All notable changes to the specification will be documented in this file.
 
+* 1.43.x:
+  * Add support for conditional exceptions. With this the `setExceptionBreakpoints` request got a new property `filterOptions` for setting the exception filters and their conditions. The corresponding capability is `supportsExceptionFilterOptions`.
+  * Clarify the description of the `cwd` property of the `runInTerminal` request: a client is only expected to execute a change directory command if `cwd` contains a non-empty, valid path.
+
 * 1.42.x:
   * Add `invalidated` event and a corresponding **client** capability `supportsInvalidatedEvent`.
 

debugAdapterProtocol.json

@@ -1256,7 +1256,14 @@
 					"items": {
 						"type": "string"
 					},
-					"description": "IDs of checked exception options. The set of IDs is returned via the 'exceptionBreakpointFilters' capability."
+					"description": "Set of exception filters specified by their ID. The set of all possible exception filters is defined by the 'exceptionBreakpointFilters' capability."
+				},
+				"filterOptions": {
+					"type": "array",
+					"items": {
+						"$ref": "#/definitions/ExceptionFilterOptions"
+					},
+					"description": "Set of exception filters and their options. The set of all possible exception filters is defined by the 'exceptionBreakpointFilters' capability. This attribute is only honored by a debug adapter if the capability 'supportsExceptionFilterOptions' is true."
 				},
 				"exceptionOptions": {
 					"type": "array",
@@ -2833,7 +2840,7 @@
 					"items": {
 						"$ref": "#/definitions/ExceptionBreakpointsFilter"
 					},
-					"description": "Available filters or options for the setExceptionBreakpoints request."
+					"description": "Available exception filter options for the 'setExceptionBreakpoints' request."
 				},
 				"supportsStepBack": {
 					"type": "boolean",
@@ -2959,25 +2966,33 @@
 				"supportsInstructionBreakpoints": {
 					"type": "boolean",
 					"description": "The debug adapter supports adding breakpoints based on instruction references."
+				},
+				"supportsExceptionFilterOptions": {
+					"type": "boolean",
+					"description": "The debug adapter supports 'filterOptions' as an argument on the 'setExceptionBreakpoints' request."
 				}
 			}
 		},
 
 		"ExceptionBreakpointsFilter": {
 			"type": "object",
-			"description": "An ExceptionBreakpointsFilter is shown in the UI as an option for configuring how exceptions are dealt with.",
+			"description": "An ExceptionBreakpointsFilter is shown in the UI as an filter option for configuring how exceptions are dealt with.",
 			"properties": {
 				"filter": {
 					"type": "string",
-					"description": "The internal ID of the filter. This value is passed to the setExceptionBreakpoints request."
+					"description": "The internal ID of the filter option. This value is passed to the 'setExceptionBreakpoints' request."
 				},
 				"label": {
 					"type": "string",
-					"description": "The name of the filter. This will be shown in the UI."
+					"description": "The name of the filter option. This will be shown in the UI."
 				},
 				"default": {
 					"type": "boolean",
-					"description": "Initial value of the filter. If not specified a value 'false' is assumed."
+					"description": "Initial value of the filter option. If not specified a value 'false' is assumed."
+				},
+				"supportsCondition": {
+					"type": "boolean",
+					"description": "Controls whether a condition can be specified for this filter option. If false or missing, a condition can not be set."
 				}
 			},
 			"required": [ "filter", "label" ]
@@ -3727,6 +3742,22 @@
 			}]
 		},
 
+		"ExceptionFilterOptions": {
+			"type": "object",
+			"description": "An ExceptionFilterOptions is used to specify an exception filter together with a condition for the setExceptionsFilter request.",
+			"properties": {
+				"filterId": {
+					"type": "string",
+					"description": "ID of an exception filter returned by the 'exceptionBreakpointFilters' capability."
+				},
+				"condition": {
+					"type": "string",
+					"description": "An optional expression for conditional exceptions.\nThe exception will break into the debugger if the result of the condition is true."
+				}
+			},
+			"required": [ "filterId" ]
+		},
+
 		"ExceptionOptions": {
 			"type": "object",
 			"description": "An ExceptionOptions assigns configuration options to a set of exceptions.",

specification.md

@@ -1345,11 +1345,20 @@ Arguments for 'setExceptionBreakpoints' request.
 ```typescript
 interface SetExceptionBreakpointsArguments {
   /**
-   * IDs of checked exception options. The set of IDs is returned via the
-   * 'exceptionBreakpointFilters' capability.
+   * Set of exception filters specified by their ID. The set of all possible
+   * exception filters is defined by the 'exceptionBreakpointFilters'
+   * capability.
    */
   filters: string[];
 
+  /**
+   * Set of exception filters and their options. The set of all possible
+   * exception filters is defined by the 'exceptionBreakpointFilters'
+   * capability. This attribute is only honored by a debug adapter if the
+   * capability 'supportsExceptionFilterOptions' is true.
+   */
+  filterOptions?: ExceptionFilterOptions[];
+
   /**
    * Configuration options for selected exceptions.
    * The attribute is only honored by a debug adapter if the capability
@@ -2930,7 +2939,8 @@ interface Capabilities {
   supportsEvaluateForHovers?: boolean;
 
   /**
-   * Available filters or options for the setExceptionBreakpoints request.
+   * Available exception filter options for the 'setExceptionBreakpoints'
+   * request.
    */
   exceptionBreakpointFilters?: ExceptionBreakpointsFilter[];
 
@@ -3091,30 +3101,43 @@ interface Capabilities {
    * references.
    */
   supportsInstructionBreakpoints?: boolean;
+
+  /**
+   * The debug adapter supports 'filterOptions' as an argument on the
+   * 'setExceptionBreakpoints' request.
+   */
+  supportsExceptionFilterOptions?: boolean;
 }
 ```
 
 ### <a name="Types_ExceptionBreakpointsFilter" class="anchor"></a>ExceptionBreakpointsFilter
 
-An ExceptionBreakpointsFilter is shown in the UI as an option for configuring how exceptions are dealt with.
+An ExceptionBreakpointsFilter is shown in the UI as an filter option for configuring how exceptions are dealt with.
 
 ```typescript
 interface ExceptionBreakpointsFilter {
   /**
-   * The internal ID of the filter. This value is passed to the
-   * setExceptionBreakpoints request.
+   * The internal ID of the filter option. This value is passed to the
+   * 'setExceptionBreakpoints' request.
    */
   filter: string;
 
   /**
-   * The name of the filter. This will be shown in the UI.
+   * The name of the filter option. This will be shown in the UI.
    */
   label: string;
 
   /**
-   * Initial value of the filter. If not specified a value 'false' is assumed.
+   * Initial value of the filter option. If not specified a value 'false' is
+   * assumed.
    */
   default?: boolean;
+
+  /**
+   * Controls whether a condition can be specified for this filter option. If
+   * false or missing, a condition can not be set.
+   */
+  supportsCondition?: boolean;
 }
 ```
 
@@ -4139,6 +4162,27 @@ interface StackFrameFormat extends ValueFormat {
 }
 ```
 
+### <a name="Types_ExceptionFilterOptions" class="anchor"></a>ExceptionFilterOptions
+
+An ExceptionFilterOptions is used to specify an exception filter together with a condition for the setExceptionsFilter request.
+
+```typescript
+interface ExceptionFilterOptions {
+  /**
+   * ID of an exception filter returned by the 'exceptionBreakpointFilters'
+   * capability.
+   */
+  filterId: string;
+
+  /**
+   * An optional expression for conditional exceptions.
+   * The exception will break into the debugger if the result of the condition
+   * is true.
+   */
+  condition?: string;
+}
+```
+
 ### <a name="Types_ExceptionOptions" class="anchor"></a>ExceptionOptions
 
 An ExceptionOptions assigns configuration options to a set of exceptions.