From fd8f860478a6c6e12368a9456bc1c719a0b0efaa Mon Sep 17 00:00:00 2001 From: Andre Weinand Date: Mon, 23 Nov 2020 18:41:32 +0100 Subject: [PATCH] add support for conditional exceptions; fixes #137 --- _data/specification-toc.yml | 2 ++ changelog.md | 4 +++ debugAdapterProtocol.json | 43 ++++++++++++++++++++++---- specification.md | 60 ++++++++++++++++++++++++++++++++----- 4 files changed, 95 insertions(+), 14 deletions(-) diff --git a/_data/specification-toc.yml b/_data/specification-toc.yml index 4314925..b9ec391 100644 --- a/_data/specification-toc.yml +++ b/_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 diff --git a/changelog.md b/changelog.md index e35b058..0a1aa21 100644 --- a/changelog.md +++ b/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`. diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json index 9abaf0c..38744a2 100644 --- a/debugAdapterProtocol.json +++ b/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.", diff --git a/specification.md b/specification.md index f8b1956..f6ad0f3 100644 --- a/specification.md +++ b/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; } ``` ### 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 { } ``` +### 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; +} +``` + ### ExceptionOptions An ExceptionOptions assigns configuration options to a set of exceptions.