diff --git a/_data/specification-toc.yml b/_data/specification-toc.yml index 20c5050..40de2e8 100644 --- a/_data/specification-toc.yml +++ b/_data/specification-toc.yml @@ -51,6 +51,8 @@ anchor: Requests_ConfigurationDone - title: Continue anchor: Requests_Continue + - title: DataBreakpointInfo + anchor: Requests_DataBreakpointInfo - title: Disconnect anchor: Requests_Disconnect - title: Evaluate @@ -83,6 +85,8 @@ anchor: Requests_Scopes - title: SetBreakpoints anchor: Requests_SetBreakpoints + - title: SetDataBreakpoints + anchor: Requests_SetDataBreakpoints - title: SetExceptionBreakpoints anchor: Requests_SetExceptionBreakpoints - title: SetExpression @@ -133,6 +137,10 @@ anchor: Types_CompletionItem - title: CompletionItemType anchor: Types_CompletionItemType + - title: DataBreakpoint + anchor: Types_DataBreakpoint + - title: DataBreakpointAccessType + anchor: Types_DataBreakpointAccessType - title: ExceptionBreakMode anchor: Types_ExceptionBreakMode - title: ExceptionBreakpointsFilter diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json index 86117e2..53e3a32 100644 --- a/debugAdapterProtocol.json +++ b/debugAdapterProtocol.json @@ -152,7 +152,7 @@ "reason": { "type": "string", "description": "The reason for the event.\nFor backward compatibility this string is shown in the UI if the 'description' attribute is missing (but it must not be translated).", - "_enum": [ "step", "breakpoint", "exception", "pause", "entry", "goto", "function breakpoint" ] + "_enum": [ "step", "breakpoint", "exception", "pause", "entry", "goto", "function breakpoint", "data breakpoint" ] }, "description": { "type": "string", @@ -1003,6 +1003,125 @@ }] }, + "DataBreakpointInfoRequest": { + "allOf": [ { "$ref": "#/definitions/Request" }, { + "type": "object", + "description": "Obtains information on a possible data breakpoint that could be set on an expression or variable.", + "properties": { + "command": { + "type": "string", + "enum": [ "dataBreakpointInfo" ] + }, + "arguments": { + "$ref": "#/definitions/DataBreakpointInfoArguments" + } + }, + "required": [ "command", "arguments" ] + }] + }, + "DataBreakpointInfoArguments": { + "type": "object", + "description": "Arguments for 'dataBreakpointInfo' request.", + "properties": { + "variablesReference": { + "type": "integer", + "description": "Reference to the Variable container if the data breakpoint is requested for a child of the container." + }, + "name": { + "type": "string", + "description": "The name of the Variable's child to obtain data breakpoint information for. If variableReference isn’t provided, this can be an expression." + } + }, + "required": [ "name" ] + }, + "DataBreakpointInfoResponse": { + "allOf": [ { "$ref": "#/definitions/Response" }, { + "type": "object", + "description": "Response to 'dataBreakpointInfo' request.", + "properties": { + "body": { + "type": "object", + "properties": { + "dataId": { + "type": [ "string", "null" ], + "description": "An identifier for the data on which a data breakpoint can be registered with the setDataBreakpoints request or null if no data breakpoint is available." + }, + "description": { + "type": "string", + "description": "UI string that describes on what data the breakpoint is set on or why a data breakpoint is not available." + }, + "accessTypes": { + "type": "array", + "items": { + "$ref": "#/definitions/DataBreakpointAccessType" + }, + "description": "Optional attribute listing the available access types for a potential data breakpoint. A UI frontend could surface this information." + }, + "canPersist": { + "type": "boolean", + "description": "Optional attribute indicating that a potential data breakpoint could be persisted across sessions." + } + }, + "required": [ "dataId", "description" ] + } + }, + "required": [ "body" ] + }] + }, + + "SetDataBreakpointsRequest": { + "allOf": [ { "$ref": "#/definitions/Request" }, { + "type": "object", + "description": "Replaces all existing data breakpoints with new data breakpoints.\nTo clear all data breakpoints, specify an empty array.\nWhen a data breakpoint is hit, a 'stopped' event (with reason 'data breakpoint') is generated.", + "properties": { + "command": { + "type": "string", + "enum": [ "setDataBreakpoints" ] + }, + "arguments": { + "$ref": "#/definitions/SetDataBreakpointsArguments" + } + }, + "required": [ "command", "arguments" ] + }] + }, + "SetDataBreakpointsArguments": { + "type": "object", + "description": "Arguments for 'setDataBreakpoints' request.", + "properties": { + "breakpoints": { + "type": "array", + "items": { + "$ref": "#/definitions/DataBreakpoint" + }, + "description": "The contents of this array replaces all existing data breakpoints. An empty array clears all data breakpoints." + } + }, + "required": [ "breakpoints" ] + }, + "SetDataBreakpointsResponse": { + "allOf": [ { "$ref": "#/definitions/Response" }, { + "type": "object", + "description": "Response to 'setDataBreakpoints' request.\nReturned is information about each breakpoint created by this request.", + "properties": { + "body": { + "type": "object", + "properties": { + "breakpoints": { + "type": "array", + "items": { + "$ref": "#/definitions/Breakpoint" + }, + "description": "Information about the data breakpoints. The array elements correspond to the elements of the input argument 'breakpoints' array." + } + }, + "required": [ "breakpoints" ] + } + }, + "required": [ "body" ] + }] + }, + "ContinueRequest": { "allOf": [ { "$ref": "#/definitions/Request" }, { "type": "object", @@ -2324,6 +2443,10 @@ "supportsTerminateRequest": { "type": "boolean", "description": "The debug adapter supports the 'terminate' request." + }, + "supportsDataBreakpoints": { + "type": "boolean", + "description": "The debug adapter supports data breakpoints." } } }, @@ -2681,7 +2804,7 @@ "kind": { "description": "The kind of variable. Before introducing additional values, try to use the listed values.", "type": "string", - "_enum": [ "property", "method", "class", "data", "event", "baseClass", "innerClass", "interface", "mostDerivedClass", "virtual" ], + "_enum": [ "property", "method", "class", "data", "event", "baseClass", "innerClass", "interface", "mostDerivedClass", "virtual", "dataBreakpoint" ], "enumDescriptions": [ "Indicates that the object is a property.", "Indicates that the object is a method.", @@ -2692,7 +2815,8 @@ "Indicates that the object is an inner class.", "Indicates that the object is an interface.", "Indicates that the object is the most derived class.", - "Indicates that the object is virtual, that means it is a synthetic object introduced by the adapter for rendering purposes, e.g. an index range for large arrays." + "Indicates that the object is virtual, that means it is a synthetic object introduced by the adapter for rendering purposes, e.g. an index range for large arrays.", + "Indicates that a data breakpoint is registered for the object." ] }, "attributes": { @@ -2768,6 +2892,36 @@ "required": [ "name" ] }, + "DataBreakpointAccessType": { + "type": "string", + "description": "This enumeration defines all possible access types for data breakpoints.", + "enum": [ "read", "write", "readWrite" ] + }, + + "DataBreakpoint": { + "type": "object", + "description": "Properties of a data breakpoint passed to the setDataBreakpoints request.", + "properties": { + "dataId": { + "type": "string", + "description": "An id representing the data. This id is returned from the dataBreakpointInfo request." + }, + "accessType": { + "$ref": "#/definitions/DataBreakpointAccessType", + "description": "The access type of the data." + }, + "condition": { + "type": "string", + "description": "An optional expression for conditional breakpoints." + }, + "hitCondition": { + "type": "string", + "description": "An optional expression that controls how many hits of the breakpoint are ignored. The backend is expected to interpret the expression as needed." + } + }, + "required": [ "dataId" ] + }, + "Breakpoint": { "type": "object", "description": "Information about a Breakpoint created in setBreakpoints or setFunctionBreakpoints.", diff --git a/specification.md b/specification.md index 3a0002d..62ff168 100644 --- a/specification.md +++ b/specification.md @@ -159,7 +159,7 @@ interface StoppedEvent extends Event { /** * The reason for the event. * For backward compatibility this string is shown in the UI if the 'description' attribute is missing (but it must not be translated). - * Values: 'step', 'breakpoint', 'exception', 'pause', 'entry', 'goto', etc. + * Values: 'step', 'breakpoint', 'exception', 'pause', 'entry', 'goto', 'function breakpoint', 'data breakpoint', etc. */ reason: string; @@ -876,11 +876,11 @@ interface SetBreakpointsResponse extends Response { ### :leftwards_arrow_with_hook: SetFunctionBreakpoints Request -Sets multiple function breakpoints and clears all previous function breakpoints. +Replaces all existing function breakpoints with new function breakpoints. -To clear all function breakpoint, specify an empty array. +To clear all function breakpoints, specify an empty array. -When a function breakpoint is hit, a 'stopped' event (event type 'function breakpoint') is generated. +When a function breakpoint is hit, a 'stopped' event (with reason 'function breakpoint') is generated. ```typescript interface SetFunctionBreakpointsRequest extends Request { @@ -955,6 +955,108 @@ interface SetExceptionBreakpointsResponse extends Response { } ``` +### :leftwards_arrow_with_hook: DataBreakpointInfo Request + +Obtains information on a possible data breakpoint that could be set on an expression or variable. + +```typescript +interface DataBreakpointInfoRequest extends Request { + command: 'dataBreakpointInfo'; + + arguments: DataBreakpointInfoArguments; +} +``` + +Arguments for 'dataBreakpointInfo' request. + + +```typescript +interface DataBreakpointInfoArguments { + /** + * Reference to the Variable container if the data breakpoint is requested for a child of the container. + */ + variablesReference?: number; + + /** + * The name of the Variable's child to obtain data breakpoint information for. If variableReference isn’t provided, this can be an expression. + */ + name: string; +} +``` + +Response to 'dataBreakpointInfo' request. + + +```typescript +interface DataBreakpointInfoResponse extends Response { + body: { + /** + * An identifier for the data on which a data breakpoint can be registered with the setDataBreakpoints request or null if no data breakpoint is available. + */ + dataId: string | null; + + /** + * UI string that describes on what data the breakpoint is set on or why a data breakpoint is not available. + */ + description: string; + + /** + * Optional attribute listing the available access types for a potential data breakpoint. A UI frontend could surface this information. + */ + accessTypes?: DataBreakpointAccessType[]; + + /** + * Optional attribute indicating that a potential data breakpoint could be persisted across sessions. + */ + canPersist?: boolean; + }; +} +``` + +### :leftwards_arrow_with_hook: SetDataBreakpoints Request + +Replaces all existing data breakpoints with new data breakpoints. + +To clear all data breakpoints, specify an empty array. + +When a data breakpoint is hit, a 'stopped' event (with reason 'data breakpoint') is generated. + +```typescript +interface SetDataBreakpointsRequest extends Request { + command: 'setDataBreakpoints'; + + arguments: SetDataBreakpointsArguments; +} +``` + +Arguments for 'setDataBreakpoints' request. + + +```typescript +interface SetDataBreakpointsArguments { + /** + * The contents of this array replaces all existing data breakpoints. An empty array clears all data breakpoints. + */ + breakpoints: DataBreakpoint[]; +} +``` + +Response to 'setDataBreakpoints' request. + +Returned is information about each breakpoint created by this request. + + +```typescript +interface SetDataBreakpointsResponse extends Response { + body: { + /** + * Information about the data breakpoints. The array elements correspond to the elements of the input argument 'breakpoints' array. + */ + breakpoints: Breakpoint[]; + }; +} +``` + ### :leftwards_arrow_with_hook: Continue Request The request starts the debuggee to run again. @@ -1465,7 +1567,7 @@ interface SetVariableArguments { variablesReference: number; /** - * The name of the variable. + * The name of the variable in the container. */ name: string; @@ -2211,6 +2313,11 @@ interface Capabilities { * The debug adapter supports the 'terminate' request. */ supportsTerminateRequest?: boolean; + + /** + * The debug adapter supports data breakpoints. + */ + supportsDataBreakpoints?: boolean; } ``` @@ -2661,6 +2768,7 @@ interface VariablePresentationHint { * 'interface': Indicates that the object is an interface. * 'mostDerivedClass': Indicates that the object is the most derived class. * 'virtual': Indicates that the object is virtual, that means it is a synthetic object introduced by the adapter for rendering purposes, e.g. an index range for large arrays. + * 'dataBreakpoint': Indicates that a data breakpoint is registered for the object. * etc. */ kind?: string; @@ -2743,6 +2851,42 @@ interface FunctionBreakpoint { } ``` +### DataBreakpointAccessType + +This enumeration defines all possible access types for data breakpoints. + +```typescript +type DataBreakpointAccessType = 'read' | 'write' | 'readWrite'; +``` + +### DataBreakpoint + +Properties of a data breakpoint passed to the setDataBreakpoints request. + +```typescript +interface DataBreakpoint { + /** + * An id representing the data. This id is returned from the dataBreakpointInfo request. + */ + dataId: string; + + /** + * The access type of the data. + */ + accessType?: DataBreakpointAccessType; + + /** + * An optional expression for conditional breakpoints. + */ + condition?: string; + + /** + * An optional expression that controls how many hits of the breakpoint are ignored. The backend is expected to interpret the expression as needed. + */ + hitCondition?: string; +} +``` + ### Breakpoint Information about a Breakpoint created in setBreakpoints or setFunctionBreakpoints.