diff --git a/include/dap/protocol.h b/include/dap/protocol.h index 1781ec0..0962d37 100644 --- a/include/dap/protocol.h +++ b/include/dap/protocol.h @@ -15,7 +15,7 @@ // Generated with protocol_gen.go -- do not edit this file. // go run scripts/protocol_gen/protocol_gen.go // -// DAP version 1.46.0 +// DAP version 1.58.0 #ifndef dap_protocol_h #define dap_protocol_h @@ -35,19 +35,19 @@ struct Request {}; struct Response {}; struct Event {}; -// Response to 'attach' request. This is just an acknowledgement, so no body +// Response to `attach` request. This is just an acknowledgement, so no body // field is required. struct AttachResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(AttachResponse); -// The attach request is sent from the client to the debug adapter to attach to -// a debuggee that is already running. Since attaching is debugger/runtime +// The `attach` request is sent from the client to the debug adapter to attach +// to a debuggee that is already running. Since attaching is debugger/runtime // specific, the arguments for this request are not part of this specification. struct AttachRequest : public Request { using Response = AttachResponse; - // Optional data from the previous, restarted session. - // The data is sent as the 'restart' attribute of the 'terminated' event. + // Arbitrary data from the previous, restarted session. + // The data is sent as the `restart` attribute of the `terminated` event. // The client should leave the data intact. optional, boolean, integer, null, number, object, string>> restart; @@ -65,17 +65,17 @@ using ChecksumAlgorithm = string; struct Checksum { // The algorithm used to calculate this checksum. ChecksumAlgorithm algorithm = "MD5"; - // Value of the checksum. + // Value of the checksum, encoded as a hexadecimal value. string checksum; }; DAP_DECLARE_STRUCT_TYPEINFO(Checksum); -// A Source is a descriptor for source code. -// It is returned from the debug adapter as part of a StackFrame and it is used -// by clients when specifying breakpoints. +// A `Source` is a descriptor for source code. +// It is returned from the debug adapter as part of a `StackFrame` and it is +// used by clients when specifying breakpoints. struct Source { - // Optional data that a debug adapter might want to loop through the client. + // Additional data that a debug adapter might want to loop through the client. // The client should leave the data intact and persist it across sessions. The // client should not interpret the data. optional, boolean, integer, null, number, object, string>> @@ -86,60 +86,64 @@ struct Source { // has a name. When sending a source to the debug adapter this name is // optional. optional name; - // The (optional) origin of this source: possible values 'internal module', - // 'inlined content from source map', etc. + // The origin of this source. For example, 'internal module', 'inlined content + // from source map', etc. optional origin; // The path of the source to be shown in the UI. // It is only used to locate and load the content of the source if no - // sourceReference is specified (or its value is 0). + // `sourceReference` is specified (or its value is 0). optional path; - // An optional hint for how to present the source in the UI. - // A value of 'deemphasize' can be used to indicate that the source is not + // A hint for how to present the source in the UI. + // A value of `deemphasize` can be used to indicate that the source is not // available or that it is skipped on stepping. // // Must be one of the following enumeration values: // 'normal', 'emphasize', 'deemphasize' optional presentationHint; - // If sourceReference > 0 the contents of the source must be retrieved through - // the SourceRequest (even if a path is specified). A sourceReference is only - // valid for a session, so it must not be used to persist a source. The value - // should be less than or equal to 2147483647 (2^31-1). + // If the value > 0 the contents of the source must be retrieved through the + // `source` request (even if a path is specified). Since a `sourceReference` + // is only valid for a session, it can not be used to persist a source. The + // value should be less than or equal to 2147483647 (2^31-1). optional sourceReference; - // An optional list of sources that are related to this source. These may be - // the source that generated this source. + // A list of sources that are related to this source. These may be the source + // that generated this source. optional> sources; }; DAP_DECLARE_STRUCT_TYPEINFO(Source); -// Information about a Breakpoint created in setBreakpoints, -// setFunctionBreakpoints, setInstructionBreakpoints, or setDataBreakpoints. +// Information about a breakpoint created in `setBreakpoints`, +// `setFunctionBreakpoints`, `setInstructionBreakpoints`, or +// `setDataBreakpoints` requests. struct Breakpoint { - // An optional start column of the actual range covered by the breakpoint. + // Start position of the source range covered by the breakpoint. It is + // measured in UTF-16 code units and the client capability `columnsStartAt1` + // determines whether it is 0- or 1-based. optional column; - // An optional end column of the actual range covered by the breakpoint. - // If no end line is given, then the end column is assumed to be in the start - // line. + // End position of the source range covered by the breakpoint. It is measured + // in UTF-16 code units and the client capability `columnsStartAt1` determines + // whether it is 0- or 1-based. If no end line is given, then the end column + // is assumed to be in the start line. optional endColumn; - // An optional end line of the actual range covered by the breakpoint. + // The end line of the actual range covered by the breakpoint. optional endLine; - // An optional identifier for the breakpoint. It is needed if breakpoint - // events are used to update or remove breakpoints. + // The identifier for the breakpoint. It is needed if breakpoint events are + // used to update or remove breakpoints. optional id; - // An optional memory reference to where the breakpoint is set. + // A memory reference to where the breakpoint is set. optional instructionReference; // The start line of the actual range covered by the breakpoint. optional line; - // An optional message about the state of the breakpoint. + // A message about the state of the breakpoint. // This is shown to the user and can be used to explain why a breakpoint could // not be verified. optional message; - // An optional offset from the instruction reference. + // The offset from the instruction reference. // This can be negative. optional offset; // The source where the breakpoint is located. optional source; - // If true breakpoint could be set (but not necessarily at the desired + // If true, the breakpoint could be set (but not necessarily at the desired // location). boolean verified; }; @@ -148,7 +152,7 @@ DAP_DECLARE_STRUCT_TYPEINFO(Breakpoint); // The event indicates that some information about a breakpoint has changed. struct BreakpointEvent : public Event { - // The 'id' attribute is used to find the target breakpoint and the other + // The `id` attribute is used to find the target breakpoint, the other // attributes are used as the new values. Breakpoint breakpoint; // The reason for the event. @@ -160,14 +164,18 @@ struct BreakpointEvent : public Event { DAP_DECLARE_STRUCT_TYPEINFO(BreakpointEvent); -// Properties of a breakpoint location returned from the 'breakpointLocations' +// Properties of a breakpoint location returned from the `breakpointLocations` // request. struct BreakpointLocation { - // Optional start column of breakpoint location. + // The start position of a breakpoint location. Position is measured in UTF-16 + // code units and the client capability `columnsStartAt1` determines whether + // it is 0- or 1-based. optional column; - // Optional end column of breakpoint location if the location covers a range. + // The end position of a breakpoint location (if the location covers a range). + // Position is measured in UTF-16 code units and the client capability + // `columnsStartAt1` determines whether it is 0- or 1-based. optional endColumn; - // Optional end line of breakpoint location if the location covers a range. + // The end line of breakpoint location if the location covers a range. optional endLine; // Start line of breakpoint location. integer line; @@ -175,7 +183,7 @@ struct BreakpointLocation { DAP_DECLARE_STRUCT_TYPEINFO(BreakpointLocation); -// Response to 'breakpointLocations' request. +// Response to `breakpointLocations` request. // Contains possible locations for source breakpoints. struct BreakpointLocationsResponse : public Response { // Sorted set of possible breakpoint locations. @@ -184,73 +192,75 @@ struct BreakpointLocationsResponse : public Response { DAP_DECLARE_STRUCT_TYPEINFO(BreakpointLocationsResponse); -// The 'breakpointLocations' request returns all possible locations for source +// The `breakpointLocations` request returns all possible locations for source // breakpoints in a given range. Clients should only call this request if the -// capability 'supportsBreakpointLocationsRequest' is true. +// corresponding capability `supportsBreakpointLocationsRequest` is true. struct BreakpointLocationsRequest : public Request { using Response = BreakpointLocationsResponse; - // 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. + // Start position within `line` to search possible breakpoint locations in. It + // is measured in UTF-16 code units and the client capability + // `columnsStartAt1` determines whether it is 0- or 1-based. If no column is + // given, the first position in the start line is assumed. optional column; - // 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. + // End position within `endLine` to search possible breakpoint locations in. + // It is measured in UTF-16 code units and the client capability + // `columnsStartAt1` determines whether it is 0- or 1-based. If no end column + // is given, the last position in the end line is assumed. optional endColumn; - // 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. + // 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. optional endLine; // 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. integer line; - // The source location of the breakpoints; either 'source.path' or - // 'source.reference' must be specified. + // The source location of the breakpoints; either `source.path` or + // `source.reference` must be specified. Source source; }; DAP_DECLARE_STRUCT_TYPEINFO(BreakpointLocationsRequest); -// Response to 'cancel' request. This is just an acknowledgement, so no body +// Response to `cancel` request. This is just an acknowledgement, so no body // field is required. struct CancelResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(CancelResponse); -// The 'cancel' request is used by the frontend in two situations: +// 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 -// capability 'supportsCancelRequest' is true. This request has a hint -// characteristic: a debug adapter can only be expected to make a 'best effort' -// in honouring this request but there are no guarantees. The 'cancel' request -// may return an error if it could not cancel an operation but a frontend should -// refrain from presenting this error to end users. A frontend client should -// only call this request if the capability 'supportsCancelRequest' is true. The -// request that got canceled 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'). Returning -// partial results from a cancelled request is possible but please note that a -// frontend client has no generic way for detecting that a response is partial -// or not. -// The progress that got cancelled still needs to send a 'progressEnd' event -// back. A client should not assume that progress just got cancelled after -// sending the 'cancel' request. +// 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. The `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. The 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`). Returning 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. The progress that got +// cancelled still needs to send a `progressEnd` event back. +// A client should not assume that progress just got cancelled after sending +// the `cancel` request. struct CancelRequest : public Request { using Response = CancelResponse; - // The ID (attribute 'progressId') of the progress to cancel. If missing no - // progress is cancelled. Both a 'requestId' and a 'progressId' can be + // The ID (attribute `progressId`) of the progress to cancel. If missing no + // progress is cancelled. Both a `requestId` and a `progressId` can be // specified in one request. optional progressId; - // The ID (attribute 'seq') of the request to cancel. If missing no request is - // cancelled. Both a 'requestId' and a 'progressId' can be specified in one + // The ID (attribute `seq`) of the request to cancel. If missing no request is + // cancelled. Both a `requestId` and a `progressId` can be specified in one // request. optional requestId; }; DAP_DECLARE_STRUCT_TYPEINFO(CancelRequest); -// A ColumnDescriptor specifies what module attribute to show in a column of the -// ModulesView, how to format it, and what the column's label should be. It is -// only used if the underlying UI actually supports this level of customization. +// A `ColumnDescriptor` specifies what module attribute to show in a column of +// the modules view, how to format it, and what the column's label should be. It +// is only used if the underlying UI actually supports this level of +// customization. struct ColumnDescriptor { // Name of the attribute rendered in this column. string attributeName; @@ -259,7 +269,7 @@ struct ColumnDescriptor { optional format; // Header UI label of column. string label; - // Datatype of values in this column. Defaults to 'string' if not specified. + // Datatype of values in this column. Defaults to `string` if not specified. // // Must be one of the following enumeration values: // 'string', 'number', 'boolean', 'unixTimestampUTC' @@ -270,23 +280,22 @@ struct ColumnDescriptor { DAP_DECLARE_STRUCT_TYPEINFO(ColumnDescriptor); -// An ExceptionBreakpointsFilter is shown in the UI as an filter option for +// An `ExceptionBreakpointsFilter` is shown in the UI as an filter option for // configuring how exceptions are dealt with. struct ExceptionBreakpointsFilter { - // An optional help text providing information about the condition. This - // string is shown as the placeholder text for a text box and must be - // translated. + // A help text providing information about the condition. This string is shown + // as the placeholder text for a text box and can be translated. optional conditionDescription; - // Initial value of the filter option. If not specified a value 'false' is + // Initial value of the filter option. If not specified a value false is // assumed. optional def; - // An optional help text providing additional information about the exception - // filter. This string is typically shown as a hover and must be translated. + // A help text providing additional information about the exception filter. + // This string is typically shown as a hover and can be translated. optional description; // The internal ID of the filter option. This value is passed to the - // 'setExceptionBreakpoints' request. + // `setExceptionBreakpoints` request. string filter; - // The name of the filter option. This will be shown in the UI. + // The name of the filter option. This is shown in the UI. string label; // Controls whether a condition can be specified for this filter option. If // false or missing, a condition can not be set. @@ -300,51 +309,54 @@ struct Capabilities { // The set of additional module information exposed by the debug adapter. optional> additionalModuleColumns; // The set of characters that should trigger completion in a REPL. If not - // specified, the UI should assume the '.' character. + // specified, the UI should assume the `.` character. optional> completionTriggerCharacters; - // Available exception filter options for the 'setExceptionBreakpoints' + // Available exception filter options for the `setExceptionBreakpoints` // request. optional> exceptionBreakpointFilters; - // The debug adapter supports the 'terminateDebuggee' attribute on the - // 'disconnect' request. + // The debug adapter supports the `suspendDebuggee` attribute on the + // `disconnect` request. + optional supportSuspendDebuggee; + // The debug adapter supports the `terminateDebuggee` attribute on the + // `disconnect` request. optional supportTerminateDebuggee; // Checksum algorithms supported by the debug adapter. optional> supportedChecksumAlgorithms; - // The debug adapter supports the 'breakpointLocations' request. + // The debug adapter supports the `breakpointLocations` request. optional supportsBreakpointLocationsRequest; - // The debug adapter supports the 'cancel' request. + // The debug adapter supports the `cancel` request. optional supportsCancelRequest; - // The debug adapter supports the 'clipboard' context value in the 'evaluate' + // The debug adapter supports the `clipboard` context value in the `evaluate` // request. optional supportsClipboardContext; - // The debug adapter supports the 'completions' request. + // The debug adapter supports the `completions` request. optional supportsCompletionsRequest; // The debug adapter supports conditional breakpoints. optional supportsConditionalBreakpoints; - // The debug adapter supports the 'configurationDone' request. + // The debug adapter supports the `configurationDone` request. optional supportsConfigurationDoneRequest; // The debug adapter supports data breakpoints. optional supportsDataBreakpoints; // The debug adapter supports the delayed loading of parts of the stack, which - // requires that both the 'startFrame' and 'levels' arguments and an optional - // 'totalFrames' result of the 'StackTrace' request are supported. + // requires that both the `startFrame` and `levels` arguments and the + // `totalFrames` result of the `stackTrace` request are supported. optional supportsDelayedStackTraceLoading; - // The debug adapter supports the 'disassemble' request. + // The debug adapter supports the `disassemble` request. optional supportsDisassembleRequest; - // The debug adapter supports a (side effect free) evaluate request for data + // The debug adapter supports a (side effect free) `evaluate` request for data // hovers. optional supportsEvaluateForHovers; - // The debug adapter supports 'filterOptions' as an argument on the - // 'setExceptionBreakpoints' request. + // The debug adapter supports `filterOptions` as an argument on the + // `setExceptionBreakpoints` request. optional supportsExceptionFilterOptions; - // The debug adapter supports the 'exceptionInfo' request. + // The debug adapter supports the `exceptionInfo` request. optional supportsExceptionInfoRequest; - // The debug adapter supports 'exceptionOptions' on the - // setExceptionBreakpoints request. + // The debug adapter supports `exceptionOptions` on the + // `setExceptionBreakpoints` request. optional supportsExceptionOptions; // The debug adapter supports function breakpoints. optional supportsFunctionBreakpoints; - // The debug adapter supports the 'gotoTargets' request. + // The debug adapter supports the `gotoTargets` request. optional supportsGotoTargetsRequest; // The debug adapter supports breakpoints that break execution after a // specified number of hits. @@ -352,49 +364,55 @@ struct Capabilities { // The debug adapter supports adding breakpoints based on instruction // references. optional supportsInstructionBreakpoints; - // The debug adapter supports the 'loadedSources' request. + // The debug adapter supports the `loadedSources` request. optional supportsLoadedSourcesRequest; - // The debug adapter supports logpoints by interpreting the 'logMessage' - // attribute of the SourceBreakpoint. + // The debug adapter supports log points by interpreting the `logMessage` + // attribute of the `SourceBreakpoint`. optional supportsLogPoints; - // The debug adapter supports the 'modules' request. + // The debug adapter supports the `modules` request. optional supportsModulesRequest; - // The debug adapter supports the 'readMemory' request. + // The debug adapter supports the `readMemory` request. optional supportsReadMemoryRequest; // The debug adapter supports restarting a frame. optional supportsRestartFrame; - // The debug adapter supports the 'restart' request. In this case a client - // should not implement 'restart' by terminating and relaunching the adapter - // but by calling the RestartRequest. + // The debug adapter supports the `restart` request. In this case a client + // should not implement `restart` by terminating and relaunching the adapter + // but by calling the `restart` request. optional supportsRestartRequest; - // The debug adapter supports the 'setExpression' request. + // The debug adapter supports the `setExpression` request. optional supportsSetExpression; // The debug adapter supports setting a variable to a value. optional supportsSetVariable; - // The debug adapter supports stepping back via the 'stepBack' and - // 'reverseContinue' requests. + // The debug adapter supports the `singleThread` property on the execution + // requests (`continue`, `next`, `stepIn`, `stepOut`, `reverseContinue`, + // `stepBack`). + optional supportsSingleThreadExecutionRequests; + // The debug adapter supports stepping back via the `stepBack` and + // `reverseContinue` requests. optional supportsStepBack; - // The debug adapter supports the 'stepInTargets' request. + // The debug adapter supports the `stepInTargets` request. optional supportsStepInTargetsRequest; - // The debug adapter supports stepping granularities (argument 'granularity') + // The debug adapter supports stepping granularities (argument `granularity`) // for the stepping requests. optional supportsSteppingGranularity; - // The debug adapter supports the 'terminate' request. + // The debug adapter supports the `terminate` request. optional supportsTerminateRequest; - // The debug adapter supports the 'terminateThreads' request. + // The debug adapter supports the `terminateThreads` request. optional supportsTerminateThreadsRequest; - // The debug adapter supports a 'format' attribute on the stackTraceRequest, - // variablesRequest, and evaluateRequest. + // The debug adapter supports a `format` attribute on the `stackTrace`, + // `variables`, and `evaluate` requests. optional supportsValueFormattingOptions; + // The debug adapter supports the `writeMemory` request. + optional supportsWriteMemoryRequest; }; DAP_DECLARE_STRUCT_TYPEINFO(Capabilities); // The event indicates that one or more capabilities have changed. -// Since the capabilities are dependent on the frontend and its UI, it might not +// Since the capabilities are dependent on the client and its UI, it might not // be possible to change that at random times (or too late). Consequently this -// event has a hint characteristic: a frontend can only be expected to make a -// 'best effort' in honouring individual capabilities but there are no +// event has a hint characteristic: a client can only be expected to make a +// 'best effort' in honoring individual capabilities but there are no // guarantees. Only changed capabilities need to be included, all other // capabilities keep their values. struct CapabilitiesEvent : public Event { @@ -413,32 +431,40 @@ DAP_DECLARE_STRUCT_TYPEINFO(CapabilitiesEvent); // 'snippet', 'text', 'color', 'file', 'reference', 'customcolor' using CompletionItemType = string; -// CompletionItems are the suggestions returned from the CompletionsRequest. +// `CompletionItems` are the suggestions returned from the `completions` +// request. struct CompletionItem { + // A human-readable string with additional information about this item, like + // type or symbol information. + optional detail; // The label of this completion item. By default this is also the text that is // inserted when selecting this completion. string label; - // This value determines how many characters are overwritten by the completion - // text. If missing the value 0 is assumed which results in the completion - // text being inserted. + // Length determines how many characters are overwritten by the completion + // text and it is measured in UTF-16 code units. If missing the value 0 is + // assumed which results in the completion text being inserted. optional length; // Determines the length of the new selection after the text has been inserted - // (or replaced). The selection can not extend beyond the bounds of the - // completion text. If omitted the length is assumed to be 0. + // (or replaced) and it is measured in UTF-16 code units. The selection can + // not extend beyond the bounds of the completion text. If omitted the length + // is assumed to be 0. optional selectionLength; // Determines the start of the new selection after the text has been inserted - // (or replaced). The start position must in the range 0 and length of the - // completion text. If omitted the selection starts at the end of the - // completion text. + // (or replaced). `selectionStart` is measured in UTF-16 code units and must + // be in the range 0 and length of the completion text. If omitted the + // selection starts at the end of the completion text. optional selectionStart; - // A string that should be used when comparing this item with other items. - // When `falsy` the label is used. + // A string that should be used when comparing this item with other items. If + // not returned or an empty string, the `label` is used instead. optional sortText; - // This value determines the location (in the CompletionsRequest's 'text' - // attribute) where the completion text is added. If missing the text is added - // at the location specified by the CompletionsRequest's 'column' attribute. + // Start position (within the `text` attribute of the `completions` request) + // where the completion text is added. The position is measured in UTF-16 code + // units and the client capability `columnsStartAt1` determines whether it is + // 0- or 1-based. If the start position is omitted the text is added at the + // location specified by the `column` attribute of the `completions` request. optional start; - // If text is not falsy then it is inserted instead of the label. + // If text is returned and not an empty string, then it is inserted instead of + // the label. optional text; // The item's type. Typically the client uses this information to render the // item in the UI with an icon. @@ -447,7 +473,7 @@ struct CompletionItem { DAP_DECLARE_STRUCT_TYPEINFO(CompletionItem); -// Response to 'completions' request. +// Response to `completions` request. struct CompletionsResponse : public Response { // The possible completions for . array targets; @@ -456,59 +482,67 @@ struct CompletionsResponse : public Response { DAP_DECLARE_STRUCT_TYPEINFO(CompletionsResponse); // Returns a list of possible completions for a given caret position and text. -// Clients should only call this request if the capability -// 'supportsCompletionsRequest' is true. +// Clients should only call this request if the corresponding capability +// `supportsCompletionsRequest` is true. struct CompletionsRequest : public Request { using Response = CompletionsResponse; - // The character position for which to determine the completion proposals. + // The position within `text` for which to determine the completion proposals. + // It is measured in UTF-16 code units and the client capability + // `columnsStartAt1` determines whether it is 0- or 1-based. integer column; // Returns completions in the scope of this stack frame. If not specified, the // completions are returned for the global scope. optional frameId; - // An optional line for which to determine the completion proposals. If - // missing the first line of the text is assumed. + // A line for which to determine the completion proposals. If missing the + // first line of the text is assumed. optional line; - // One or more source lines. Typically this is the text a user has typed into - // the debug console before he asked for completion. + // One or more source lines. Typically this is the text users have typed into + // the debug console before they asked for completion. string text; }; DAP_DECLARE_STRUCT_TYPEINFO(CompletionsRequest); -// Response to 'configurationDone' request. This is just an acknowledgement, so +// Response to `configurationDone` request. This is just an acknowledgement, so // no body field is required. struct ConfigurationDoneResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(ConfigurationDoneResponse); -// This optional request indicates that the client has finished initialization -// of the debug adapter. So it is the last request in the sequence of -// configuration requests (which was started by the 'initialized' event). -// Clients should only call this request if the capability -// 'supportsConfigurationDoneRequest' is true. +// This request indicates that the client has finished initialization of the +// debug adapter. So it is the last request in the sequence of configuration +// requests (which was started by the `initialized` event). Clients should only +// call this request if the corresponding capability +// `supportsConfigurationDoneRequest` is true. struct ConfigurationDoneRequest : public Request { using Response = ConfigurationDoneResponse; }; DAP_DECLARE_STRUCT_TYPEINFO(ConfigurationDoneRequest); -// Response to 'continue' request. +// Response to `continue` request. struct ContinueResponse : public Response { - // If true, the 'continue' request has ignored the specified thread and - // continued all threads instead. If this attribute is missing a value of - // 'true' is assumed for backward compatibility. + // The value true (or a missing property) signals to the client that all + // threads have been resumed. The value false indicates that not all threads + // were resumed. optional allThreadsContinued; }; DAP_DECLARE_STRUCT_TYPEINFO(ContinueResponse); -// The request starts the debuggee to run again. +// The request resumes execution of all threads. If the debug adapter supports +// single thread execution (see capability +// `supportsSingleThreadExecutionRequests`), setting the `singleThread` argument +// to true resumes only the specified thread. If not all threads were resumed, +// the `allThreadsContinued` attribute of the response should be set to false. struct ContinueRequest : public Request { using Response = ContinueResponse; - // Continue execution for the specified thread (if possible). - // If the backend cannot continue on a single thread but will continue on all - // threads, it should set the 'allThreadsContinued' attribute in the response - // to true. + // If this flag is true, execution is resumed only for the thread with given + // `threadId`. + optional singleThread; + // Specifies the active thread. If the debug adapter supports single thread + // execution (see `supportsSingleThreadExecutionRequests`) and the argument + // `singleThread` is true, only the thread with this ID is resumed. integer threadId; }; @@ -516,11 +550,11 @@ DAP_DECLARE_STRUCT_TYPEINFO(ContinueRequest); // The event indicates that the execution of the debuggee has continued. // Please note: a debug adapter is not expected to send this event in response -// to a request that implies that execution continues, e.g. 'launch' or -// 'continue'. It is only necessary to send a 'continued' event if there was no +// to a request that implies that execution continues, e.g. `launch` or +// `continue`. It is only necessary to send a `continued` event if there was no // previous request that implied this. struct ContinuedEvent : public Event { - // If 'allThreadsContinued' is true, a debug adapter can announce that all + // If `allThreadsContinued` is true, a debug adapter can announce that all // threads have continued. optional allThreadsContinued; // The thread which was continued. @@ -535,16 +569,16 @@ DAP_DECLARE_STRUCT_TYPEINFO(ContinuedEvent); // 'read', 'write', 'readWrite' using DataBreakpointAccessType = string; -// Response to 'dataBreakpointInfo' request. +// Response to `dataBreakpointInfo` request. struct DataBreakpointInfoResponse : public Response { - // Optional attribute listing the available access types for a potential data - // breakpoint. A UI frontend could surface this information. + // Attribute lists the available access types for a potential data breakpoint. + // A UI client could surface this information. optional> accessTypes; - // Optional attribute indicating that a potential data breakpoint could be - // persisted across sessions. + // Attribute indicates that a potential data breakpoint could be persisted + // across sessions. optional canPersist; // An identifier for the data on which a data breakpoint can be registered - // with the setDataBreakpoints request or null if no data breakpoint is + // with the `setDataBreakpoints` request or null if no data breakpoint is // available. variant dataId; // UI string that describes on what data the breakpoint is set on or why a @@ -556,13 +590,13 @@ DAP_DECLARE_STRUCT_TYPEINFO(DataBreakpointInfoResponse); // Obtains information on a possible data breakpoint that could be set on an // expression or variable. Clients should only call this request if the -// capability 'supportsDataBreakpoints' is true. +// corresponding capability `supportsDataBreakpoints` is true. struct DataBreakpointInfoRequest : public Request { using Response = DataBreakpointInfoResponse; - // The name of the Variable's child to obtain data breakpoint information for. - // If variablesReference isn’t provided, this can be an expression. + // The name of the variable's child to obtain data breakpoint information for. + // If `variablesReference` isn't specified, this can be an expression. string name; - // Reference to the Variable container if the data breakpoint is requested for + // Reference to the variable container if the data breakpoint is requested for // a child of the container. optional variablesReference; }; @@ -572,7 +606,7 @@ DAP_DECLARE_STRUCT_TYPEINFO(DataBreakpointInfoRequest); // Represents a single disassembled instruction. struct DisassembledInstruction { // The address of the instruction. Treated as a hex value if prefixed with - // '0x', or as a decimal value otherwise. + // `0x`, or as a decimal value otherwise. string address; // The column within the line that corresponds to this instruction, if any. optional column; @@ -583,7 +617,7 @@ struct DisassembledInstruction { // Text representing the instruction and its operands, in an // implementation-defined format. string instruction; - // Optional raw bytes representing the instruction and its operands, in an + // Raw bytes representing the instruction and its operands, in an // implementation-defined format. optional instructionBytes; // The line within the source location that corresponds to this instruction, @@ -601,7 +635,7 @@ struct DisassembledInstruction { DAP_DECLARE_STRUCT_TYPEINFO(DisassembledInstruction); -// Response to 'disassemble' request. +// Response to `disassemble` request. struct DisassembleResponse : public Response { // The list of disassembled instructions. array instructions; @@ -610,8 +644,8 @@ struct DisassembleResponse : public Response { DAP_DECLARE_STRUCT_TYPEINFO(DisassembleResponse); // Disassembles code stored at the provided location. -// Clients should only call this request if the capability -// 'supportsDisassembleRequest' is true. +// Clients should only call this request if the corresponding capability +// `supportsDisassembleRequest` is true. struct DisassembleRequest : public Request { using Response = DisassembleResponse; // Number of instructions to disassemble starting at the specified location @@ -619,13 +653,13 @@ struct DisassembleRequest : public Request { // any unavailable instructions should be replaced with an // implementation-defined 'invalid instruction' value. integer instructionCount; - // Optional offset (in instructions) to be applied after the byte offset (if - // any) before disassembling. Can be negative. + // Offset (in instructions) to be applied after the byte offset (if any) + // before disassembling. Can be negative. optional instructionOffset; // Memory reference to the base location containing the instructions to // disassemble. string memoryReference; - // Optional offset (in bytes) to be applied to the reference location before + // Offset (in bytes) to be applied to the reference location before // disassembling. Can be negative. optional offset; // If true, the adapter should attempt to resolve memory addresses and other @@ -635,28 +669,35 @@ struct DisassembleRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(DisassembleRequest); -// Response to 'disconnect' request. This is just an acknowledgement, so no body +// Response to `disconnect` request. This is just an acknowledgement, so no body // field is required. struct DisconnectResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(DisconnectResponse); -// The 'disconnect' request is sent from the client to the debug adapter in -// order to stop debugging. It asks the debug adapter to disconnect from the -// debuggee and to terminate the debug adapter. If the debuggee has been started -// with the 'launch' request, the 'disconnect' request terminates the debuggee. -// If the 'attach' request was used to connect to the debuggee, 'disconnect' -// does not terminate the debuggee. This behavior can be controlled with the -// 'terminateDebuggee' argument (if supported by the debug adapter). +// The `disconnect` request asks the debug adapter to disconnect from the +// debuggee (thus ending the debug session) and then to shut down itself (the +// debug adapter). In addition, the debug adapter must terminate the debuggee if +// it was started with the `launch` request. If an `attach` request was used to +// connect to the debuggee, then the debug adapter must not terminate the +// debuggee. This implicit behavior of when to terminate the debuggee can be +// overridden with the `terminateDebuggee` argument (which is only supported by +// a debug adapter if the corresponding capability `supportTerminateDebuggee` is +// true). struct DisconnectRequest : public Request { using Response = DisconnectResponse; - // A value of true indicates that this 'disconnect' request is part of a + // A value of true indicates that this `disconnect` request is part of a // restart sequence. optional restart; + // Indicates whether the debuggee should stay suspended when the debugger is + // disconnected. If unspecified, the debuggee should resume execution. The + // attribute is only honored by a debug adapter if the corresponding + // capability `supportSuspendDebuggee` is true. + optional suspendDebuggee; // Indicates whether the debuggee should be terminated when the debugger is // disconnected. If unspecified, the debug adapter is free to do whatever it // thinks is best. The attribute is only honored by a debug adapter if the - // capability 'supportTerminateDebuggee' is true. + // corresponding capability `supportTerminateDebuggee` is true. optional terminateDebuggee; }; @@ -664,7 +705,7 @@ DAP_DECLARE_STRUCT_TYPEINFO(DisconnectRequest); // A structured message object. Used to return errors from requests. struct Message { - // A format string for the message. Embedded variables have the form '{name}'. + // A format string for the message. Embedded variables have the form `{name}`. // If variable name starts with an underscore character, the variable does not // contain user data (PII) and can be safely used for telemetry purposes. string format; @@ -674,11 +715,9 @@ struct Message { optional sendTelemetry; // If true show user. optional showUser; - // An optional url where additional information about this message can be - // found. + // A url where additional information about this message can be found. optional url; - // An optional label that is presented to the user as the UI for opening the - // url. + // A label that is presented to the user as the UI for opening the url. optional urlLabel; // An object used as a dictionary for looking up the variables in the format // string. @@ -687,16 +726,16 @@ struct Message { DAP_DECLARE_STRUCT_TYPEINFO(Message); -// On error (whenever 'success' is false), the body can provide more details. +// On error (whenever `success` is false), the body can provide more details. struct ErrorResponse : public Response { - // An optional, structured error message. + // A structured error message. optional error; }; DAP_DECLARE_STRUCT_TYPEINFO(ErrorResponse); -// Optional properties of a variable that can be used to determine how to render -// the variable in the UI. +// Properties of a variable that can be used to determine how to render the +// variable in the UI. struct VariablePresentationHint { // Set of attributes represented as an array of strings. Before introducing // additional values, try to use the listed values. @@ -708,6 +747,15 @@ struct VariablePresentationHint { // 'property', 'method', 'class', 'data', 'event', 'baseClass', 'innerClass', // 'interface', 'mostDerivedClass', 'virtual', 'dataBreakpoint' optional kind; + // If true, clients can present the variable with a UI that supports a + // specific gesture to trigger its evaluation. This mechanism can be used for + // properties that require executing code when retrieving their value and + // where the code execution can be expensive and/or produce side-effects. A + // typical example are properties based on a getter function. Please note that + // in addition to the `lazy` flag, the variable's `variablesReference` is + // expected to refer to a variable that will provide the value through another + // `variable` request. + optional lazy; // Visibility of variable. Before introducing additional values, try to use // the listed values. // @@ -718,37 +766,36 @@ struct VariablePresentationHint { DAP_DECLARE_STRUCT_TYPEINFO(VariablePresentationHint); -// Response to 'evaluate' request. +// Response to `evaluate` request. struct EvaluateResponse : public Response { // The number of indexed child variables. - // The client can use this optional information to present the variables in a - // paged UI and fetch them in chunks. The value should be less than or equal - // to 2147483647 (2^31-1). + // The client can use this information to present the variables in a paged UI + // and fetch them in chunks. The value should be less than or equal to + // 2147483647 (2^31-1). optional indexedVariables; - // Optional memory reference to a location appropriate for this result. + // 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 the client has passed the value true for the - // 'supportsMemoryReferences' capability of the 'initialize' request. + // debug adapter if corresponding capability `supportsMemoryReferences` is + // true. optional memoryReference; // The number of named child variables. - // The client can use this optional information to present the variables in a - // paged UI and fetch them in chunks. The value should be less than or equal - // to 2147483647 (2^31-1). + // The client can use this information to present the variables in a paged UI + // and fetch them in chunks. The value should be less than or equal to + // 2147483647 (2^31-1). optional namedVariables; - // Properties of a evaluate result that can be used to determine how to render - // the result in the UI. + // Properties of an evaluate result that can be used to determine how to + // render the result in the UI. optional presentationHint; // The result of the evaluate request. string result; - // The optional type of the evaluate result. - // This attribute should only be returned by a debug adapter if the client has - // passed the value true for the 'supportsVariableType' capability of the - // 'initialize' request. + // The type of the evaluate result. + // This attribute should only be returned by a debug adapter if the + // corresponding capability `supportsVariableType` is true. optional type; - // If variablesReference is > 0, the evaluate result is structured and its - // children can be retrieved by passing variablesReference to the - // VariablesRequest. The value should be less than or equal to 2147483647 + // If `variablesReference` is > 0, the evaluate result is structured and its + // children can be retrieved by passing `variablesReference` to the + // `variables` request. The value should be less than or equal to 2147483647 // (2^31-1). integer variablesReference; }; @@ -763,20 +810,20 @@ struct ValueFormat { DAP_DECLARE_STRUCT_TYPEINFO(ValueFormat); -// Evaluates the given expression in the context of the top most stack frame. +// Evaluates the given expression in the context of the topmost stack frame. // The expression has access to any variables and arguments that are in scope. struct EvaluateRequest : public Request { using Response = EvaluateResponse; - // The context in which the evaluate request is run. + // The context in which the evaluate request is used. // // May be one of the following enumeration values: - // 'watch', 'repl', 'hover', 'clipboard' + // 'variables', 'watch', 'repl', 'hover', 'clipboard' optional context; // The expression to evaluate. string expression; - // Specifies details on how to format the Evaluate result. - // The attribute is only honored by a debug adapter if the capability - // 'supportsValueFormattingOptions' is true. + // Specifies details on how to format the result. + // The attribute is only honored by a debug adapter if the corresponding + // capability `supportsValueFormattingOptions` is true. optional format; // Evaluate the expression in the scope of this stack frame. If not specified, // the expression is evaluated in the global scope. @@ -796,8 +843,8 @@ using ExceptionBreakMode = string; // Detailed information about an exception that has occurred. struct ExceptionDetails { - // Optional expression that can be evaluated in the current scope to obtain - // the exception object. + // An expression that can be evaluated in the current scope to obtain the + // exception object. optional evaluateName; // Fully-qualified type name of the exception object. optional fullTypeName; @@ -813,11 +860,11 @@ struct ExceptionDetails { DAP_DECLARE_STRUCT_TYPEINFO(ExceptionDetails); -// Response to 'exceptionInfo' request. +// Response to `exceptionInfo` request. struct ExceptionInfoResponse : public Response { // Mode that caused the exception notification to be raised. ExceptionBreakMode breakMode = "never"; - // Descriptive text for the exception provided by the debug adapter. + // Descriptive text for the exception. optional description; // Detailed information about the exception. optional details; @@ -828,8 +875,8 @@ struct ExceptionInfoResponse : public Response { DAP_DECLARE_STRUCT_TYPEINFO(ExceptionInfoResponse); // Retrieves the details of the exception that caused this event to be raised. -// Clients should only call this request if the capability -// 'supportsExceptionInfoRequest' is true. +// Clients should only call this request if the corresponding capability +// `supportsExceptionInfoRequest` is true. struct ExceptionInfoRequest : public Request { using Response = ExceptionInfoResponse; // Thread for which exception information should be retrieved. @@ -846,19 +893,19 @@ struct ExitedEvent : public Event { DAP_DECLARE_STRUCT_TYPEINFO(ExitedEvent); -// Response to 'goto' request. This is just an acknowledgement, so no body field +// Response to `goto` request. This is just an acknowledgement, so no body field // is required. struct GotoResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(GotoResponse); // The request sets the location where the debuggee will continue to run. -// This makes it possible to skip the execution of code or to executed code +// This makes it possible to skip the execution of code or to execute code // again. The code between the current location and the goto target is not // executed but skipped. The debug adapter first sends the response and then a -// 'stopped' event with reason 'goto'. Clients should only call this request if -// the capability 'supportsGotoTargetsRequest' is true (because only then goto -// targets exist that can be passed as arguments). +// `stopped` event with reason `goto`. Clients should only call this request if +// the corresponding capability `supportsGotoTargetsRequest` is true (because +// only then goto targets exist that can be passed as arguments). struct GotoRequest : public Request { using Response = GotoResponse; // The location where the debuggee will continue to run. @@ -869,20 +916,20 @@ struct GotoRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(GotoRequest); -// A GotoTarget describes a code location that can be used as a target in the -// 'goto' request. The possible goto targets can be determined via the -// 'gotoTargets' request. +// A `GotoTarget` describes a code location that can be used as a target in the +// `goto` request. The possible goto targets can be determined via the +// `gotoTargets` request. struct GotoTarget { - // An optional column of the goto target. + // The column of the goto target. optional column; - // An optional end column of the range covered by the goto target. + // The end column of the range covered by the goto target. optional endColumn; - // An optional end line of the range covered by the goto target. + // The end line of the range covered by the goto target. optional endLine; - // Unique identifier for a goto target. This is used in the goto request. + // Unique identifier for a goto target. This is used in the `goto` request. integer id; - // Optional memory reference for the instruction pointer value represented by - // this target. + // A memory reference for the instruction pointer value represented by this + // target. optional instructionPointerReference; // The name of the goto target (shown in the UI). string label; @@ -892,7 +939,7 @@ struct GotoTarget { DAP_DECLARE_STRUCT_TYPEINFO(GotoTarget); -// Response to 'gotoTargets' request. +// Response to `gotoTargets` request. struct GotoTargetsResponse : public Response { // The possible goto targets of the specified location. array targets; @@ -901,12 +948,14 @@ struct GotoTargetsResponse : public Response { DAP_DECLARE_STRUCT_TYPEINFO(GotoTargetsResponse); // This request retrieves the possible goto targets for the specified source -// location. These targets can be used in the 'goto' request. Clients should -// only call this request if the capability 'supportsGotoTargetsRequest' is -// true. +// location. These targets can be used in the `goto` request. Clients should +// only call this request if the corresponding capability +// `supportsGotoTargetsRequest` is true. struct GotoTargetsRequest : public Request { using Response = GotoTargetsResponse; - // An optional column location for which the goto targets are determined. + // The position within `line` for which the goto targets are determined. It is + // measured in UTF-16 code units and the client capability `columnsStartAt1` + // determines whether it is 0- or 1-based. optional column; // The line location for which the goto targets are determined. integer line; @@ -916,56 +965,59 @@ struct GotoTargetsRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(GotoTargetsRequest); -// Response to 'initialize' request. +// Response to `initialize` request. struct InitializeResponse : public Response { // The set of additional module information exposed by the debug adapter. optional> additionalModuleColumns; // The set of characters that should trigger completion in a REPL. If not - // specified, the UI should assume the '.' character. + // specified, the UI should assume the `.` character. optional> completionTriggerCharacters; - // Available exception filter options for the 'setExceptionBreakpoints' + // Available exception filter options for the `setExceptionBreakpoints` // request. optional> exceptionBreakpointFilters; - // The debug adapter supports the 'terminateDebuggee' attribute on the - // 'disconnect' request. + // The debug adapter supports the `suspendDebuggee` attribute on the + // `disconnect` request. + optional supportSuspendDebuggee; + // The debug adapter supports the `terminateDebuggee` attribute on the + // `disconnect` request. optional supportTerminateDebuggee; // Checksum algorithms supported by the debug adapter. optional> supportedChecksumAlgorithms; - // The debug adapter supports the 'breakpointLocations' request. + // The debug adapter supports the `breakpointLocations` request. optional supportsBreakpointLocationsRequest; - // The debug adapter supports the 'cancel' request. + // The debug adapter supports the `cancel` request. optional supportsCancelRequest; - // The debug adapter supports the 'clipboard' context value in the 'evaluate' + // The debug adapter supports the `clipboard` context value in the `evaluate` // request. optional supportsClipboardContext; - // The debug adapter supports the 'completions' request. + // The debug adapter supports the `completions` request. optional supportsCompletionsRequest; // The debug adapter supports conditional breakpoints. optional supportsConditionalBreakpoints; - // The debug adapter supports the 'configurationDone' request. + // The debug adapter supports the `configurationDone` request. optional supportsConfigurationDoneRequest; // The debug adapter supports data breakpoints. optional supportsDataBreakpoints; // The debug adapter supports the delayed loading of parts of the stack, which - // requires that both the 'startFrame' and 'levels' arguments and an optional - // 'totalFrames' result of the 'StackTrace' request are supported. + // requires that both the `startFrame` and `levels` arguments and the + // `totalFrames` result of the `stackTrace` request are supported. optional supportsDelayedStackTraceLoading; - // The debug adapter supports the 'disassemble' request. + // The debug adapter supports the `disassemble` request. optional supportsDisassembleRequest; - // The debug adapter supports a (side effect free) evaluate request for data + // The debug adapter supports a (side effect free) `evaluate` request for data // hovers. optional supportsEvaluateForHovers; - // The debug adapter supports 'filterOptions' as an argument on the - // 'setExceptionBreakpoints' request. + // The debug adapter supports `filterOptions` as an argument on the + // `setExceptionBreakpoints` request. optional supportsExceptionFilterOptions; - // The debug adapter supports the 'exceptionInfo' request. + // The debug adapter supports the `exceptionInfo` request. optional supportsExceptionInfoRequest; - // The debug adapter supports 'exceptionOptions' on the - // setExceptionBreakpoints request. + // The debug adapter supports `exceptionOptions` on the + // `setExceptionBreakpoints` request. optional supportsExceptionOptions; // The debug adapter supports function breakpoints. optional supportsFunctionBreakpoints; - // The debug adapter supports the 'gotoTargets' request. + // The debug adapter supports the `gotoTargets` request. optional supportsGotoTargetsRequest; // The debug adapter supports breakpoints that break execution after a // specified number of hits. @@ -973,110 +1025,122 @@ struct InitializeResponse : public Response { // The debug adapter supports adding breakpoints based on instruction // references. optional supportsInstructionBreakpoints; - // The debug adapter supports the 'loadedSources' request. + // The debug adapter supports the `loadedSources` request. optional supportsLoadedSourcesRequest; - // The debug adapter supports logpoints by interpreting the 'logMessage' - // attribute of the SourceBreakpoint. + // The debug adapter supports log points by interpreting the `logMessage` + // attribute of the `SourceBreakpoint`. optional supportsLogPoints; - // The debug adapter supports the 'modules' request. + // The debug adapter supports the `modules` request. optional supportsModulesRequest; - // The debug adapter supports the 'readMemory' request. + // The debug adapter supports the `readMemory` request. optional supportsReadMemoryRequest; // The debug adapter supports restarting a frame. optional supportsRestartFrame; - // The debug adapter supports the 'restart' request. In this case a client - // should not implement 'restart' by terminating and relaunching the adapter - // but by calling the RestartRequest. + // The debug adapter supports the `restart` request. In this case a client + // should not implement `restart` by terminating and relaunching the adapter + // but by calling the `restart` request. optional supportsRestartRequest; - // The debug adapter supports the 'setExpression' request. + // The debug adapter supports the `setExpression` request. optional supportsSetExpression; // The debug adapter supports setting a variable to a value. optional supportsSetVariable; - // The debug adapter supports stepping back via the 'stepBack' and - // 'reverseContinue' requests. + // The debug adapter supports the `singleThread` property on the execution + // requests (`continue`, `next`, `stepIn`, `stepOut`, `reverseContinue`, + // `stepBack`). + optional supportsSingleThreadExecutionRequests; + // The debug adapter supports stepping back via the `stepBack` and + // `reverseContinue` requests. optional supportsStepBack; - // The debug adapter supports the 'stepInTargets' request. + // The debug adapter supports the `stepInTargets` request. optional supportsStepInTargetsRequest; - // The debug adapter supports stepping granularities (argument 'granularity') + // The debug adapter supports stepping granularities (argument `granularity`) // for the stepping requests. optional supportsSteppingGranularity; - // The debug adapter supports the 'terminate' request. + // The debug adapter supports the `terminate` request. optional supportsTerminateRequest; - // The debug adapter supports the 'terminateThreads' request. + // The debug adapter supports the `terminateThreads` request. optional supportsTerminateThreadsRequest; - // The debug adapter supports a 'format' attribute on the stackTraceRequest, - // variablesRequest, and evaluateRequest. + // The debug adapter supports a `format` attribute on the `stackTrace`, + // `variables`, and `evaluate` requests. optional supportsValueFormattingOptions; + // The debug adapter supports the `writeMemory` request. + optional supportsWriteMemoryRequest; }; DAP_DECLARE_STRUCT_TYPEINFO(InitializeResponse); -// The 'initialize' request is sent as the first request from the client to the +// The `initialize` request is sent as the first request from the client to the // debug adapter in order to configure it with client capabilities and to // retrieve capabilities from the debug adapter. Until the debug adapter has -// responded to with an 'initialize' response, the client must not send any +// responded with an `initialize` response, the client must not send any // additional requests or events to the debug adapter. In addition the debug // adapter is not allowed to send any requests or events to the client until it -// has responded with an 'initialize' response. The 'initialize' request may +// has responded with an `initialize` response. The `initialize` request may // only be sent once. struct InitializeRequest : public Request { using Response = InitializeResponse; // The ID of the debug adapter. string adapterID; - // The ID of the (frontend) client using this adapter. + // The ID of the client using this adapter. optional clientID; - // The human readable name of the (frontend) client using this adapter. + // The human-readable name of the client using this adapter. optional clientName; // If true all column numbers are 1-based (default). optional columnsStartAt1; // If true all line numbers are 1-based (default). optional linesStartAt1; - // The ISO-639 locale of the (frontend) client using this adapter, e.g. en-US - // or de-CH. + // The ISO-639 locale of the client using this adapter, e.g. en-US or de-CH. optional locale; - // Determines in what format paths are specified. The default is 'path', which + // Determines in what format paths are specified. The default is `path`, which // is the native format. // // May be one of the following enumeration values: // 'path', 'uri' optional pathFormat; - // Client supports the invalidated event. + // Client supports the `argsCanBeInterpretedByShell` attribute on the + // `runInTerminal` request. + optional supportsArgsCanBeInterpretedByShell; + // Client supports the `invalidated` event. optional supportsInvalidatedEvent; + // Client supports the `memory` event. + optional supportsMemoryEvent; // Client supports memory references. optional supportsMemoryReferences; // Client supports progress reporting. optional supportsProgressReporting; - // Client supports the runInTerminal request. + // Client supports the `runInTerminal` request. optional supportsRunInTerminalRequest; + // Client supports the `startDebugging` request. + optional supportsStartDebuggingRequest; // Client supports the paging of variables. optional supportsVariablePaging; - // Client supports the optional type attribute for variables. + // Client supports the `type` attribute for variables. optional supportsVariableType; }; DAP_DECLARE_STRUCT_TYPEINFO(InitializeRequest); // This event indicates that the debug adapter is ready to accept configuration -// requests (e.g. SetBreakpointsRequest, SetExceptionBreakpointsRequest). A -// debug adapter is expected to send this event when it is ready to accept -// configuration requests (but not before the 'initialize' request has -// finished). The sequence of events/requests is as follows: -// - adapters sends 'initialized' event (after the 'initialize' request has +// requests (e.g. `setBreakpoints`, `setExceptionBreakpoints`). A debug adapter +// is expected to send this event when it is ready to accept configuration +// requests (but not before the `initialize` request has finished). The sequence +// of events/requests is as follows: +// - adapters sends `initialized` event (after the `initialize` request has // returned) -// - frontend sends zero or more 'setBreakpoints' requests -// - frontend sends one 'setFunctionBreakpoints' request (if capability -// 'supportsFunctionBreakpoints' is true) -// - frontend sends a 'setExceptionBreakpoints' request if one or more -// 'exceptionBreakpointFilters' have been defined (or if -// 'supportsConfigurationDoneRequest' is not defined or false) -// - frontend sends other future configuration requests -// - frontend sends one 'configurationDone' request to indicate the end of the +// - client sends zero or more `setBreakpoints` requests +// - client sends one `setFunctionBreakpoints` request (if corresponding +// capability `supportsFunctionBreakpoints` is true) +// - client sends a `setExceptionBreakpoints` request if one or more +// `exceptionBreakpointFilters` have been defined (or if +// `supportsConfigurationDoneRequest` is not true) +// - client sends other future configuration requests +// - client sends one `configurationDone` request to indicate the end of the // configuration. struct InitializedEvent : public Event {}; DAP_DECLARE_STRUCT_TYPEINFO(InitializedEvent); -// Logical areas that can be invalidated by the 'invalidated' event. +// Logical areas that can be invalidated by the `invalidated` event. using InvalidatedAreas = string; // This event signals that some state in the debug adapter has changed and @@ -1085,17 +1149,17 @@ using InvalidatedAreas = string; // like stopped or thread events because in that case the client refetches the // new state anyway. But the event can be used for example to refresh the UI // after rendering formatting has changed in the debug adapter. This event -// should only be sent if the debug adapter has received a value true for the -// 'supportsInvalidatedEvent' capability of the 'initialize' request. +// should only be sent if the corresponding capability +// `supportsInvalidatedEvent` is true. struct InvalidatedEvent : public Event { - // Optional set of logical areas that got invalidated. This property has a - // hint characteristic: a client can only be expected to make a 'best effort' - // in honouring the areas but there are no guarantees. If this property is - // missing, empty, or if values are not understand the client should assume a - // single value 'all'. + // Set of logical areas that got invalidated. This property has a hint + // characteristic: a client can only be expected to make a 'best effort' in + // honoring the areas but there are no guarantees. If this property is + // missing, empty, or if values are not understood, the client should assume a + // single value `all`. optional> areas; // If specified, the client only needs to refetch data related to this stack - // frame (and the 'threadId' is ignored). + // frame (and the `threadId` is ignored). optional stackFrameId; // If specified, the client only needs to refetch data related to this thread. optional threadId; @@ -1103,25 +1167,25 @@ struct InvalidatedEvent : public Event { DAP_DECLARE_STRUCT_TYPEINFO(InvalidatedEvent); -// Response to 'launch' request. This is just an acknowledgement, so no body +// Response to `launch` request. This is just an acknowledgement, so no body // field is required. struct LaunchResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(LaunchResponse); // This launch request is sent from the client to the debug adapter to start the -// debuggee with or without debugging (if 'noDebug' is true). Since launching is +// debuggee with or without debugging (if `noDebug` is true). Since launching is // debugger/runtime specific, the arguments for this request are not part of // this specification. struct LaunchRequest : public Request { using Response = LaunchResponse; - // Optional data from the previous, restarted session. - // The data is sent as the 'restart' attribute of the 'terminated' event. + // Arbitrary data from the previous, restarted session. + // The data is sent as the `restart` attribute of the `terminated` event. // The client should leave the data intact. optional, boolean, integer, null, number, object, string>> restart; - // If noDebug is true the launch request should launch the program without - // enabling debugging. + // If true, the launch request should launch the program without enabling + // debugging. optional noDebug; }; @@ -1141,7 +1205,7 @@ struct LoadedSourceEvent : public Event { DAP_DECLARE_STRUCT_TYPEINFO(LoadedSourceEvent); -// Response to 'loadedSources' request. +// Response to `loadedSources` request. struct LoadedSourcesResponse : public Response { // Set of loaded sources. array sources; @@ -1150,30 +1214,54 @@ struct LoadedSourcesResponse : public Response { DAP_DECLARE_STRUCT_TYPEINFO(LoadedSourcesResponse); // Retrieves the set of all sources currently loaded by the debugged process. -// Clients should only call this request if the capability -// 'supportsLoadedSourcesRequest' is true. +// Clients should only call this request if the corresponding capability +// `supportsLoadedSourcesRequest` is true. struct LoadedSourcesRequest : public Request { using Response = LoadedSourcesResponse; }; DAP_DECLARE_STRUCT_TYPEINFO(LoadedSourcesRequest); +// This event indicates that some memory range has been updated. It should only +// be sent if the corresponding capability `supportsMemoryEvent` is true. +// Clients typically react to the event by re-issuing a `readMemory` request if +// they show the memory identified by the `memoryReference` and if the updated +// memory range overlaps the displayed range. Clients should not make +// assumptions how individual memory references relate to each other, so they +// should not assume that they are part of a single continuous address range and +// might overlap. Debug adapters can use this event to indicate that the +// contents of a memory range has changed due to some other request like +// `setVariable` or `setExpression`. Debug adapters are not expected to emit +// this event for each and every memory change of a running program, because +// that information is typically not available from debuggers and it would flood +// clients with too many events. +struct MemoryEvent : public Event { + // Number of bytes updated. + integer count; + // Memory reference of a memory range that has been updated. + string memoryReference; + // Starting offset in bytes where memory has been updated. Can be negative. + integer offset; +}; + +DAP_DECLARE_STRUCT_TYPEINFO(MemoryEvent); + // A Module object represents a row in the modules view. -// Two attributes are mandatory: an id identifies a module in the modules view -// and is used in a ModuleEvent for identifying a module for adding, updating or -// deleting. The name is used to minimally render the module in the UI. +// The `id` attribute identifies a module in the modules view and is used in a +// `module` event for identifying a module for adding, updating or deleting. The +// `name` attribute is used to minimally render the module in the UI. // -// Additional attributes can be added to the module. They will show up in the -// module View if they have a corresponding ColumnDescriptor. +// Additional attributes can be added to the module. They show up in the module +// view if they have a corresponding `ColumnDescriptor`. // // To avoid an unnecessary proliferation of additional attributes with similar -// semantics but different names we recommend to re-use attributes from the +// semantics but different names, we recommend to re-use attributes from the // 'recommended' list below first, and only introduce new attributes if nothing // appropriate could be found. struct Module { // Address range covered by this module. optional addressRange; - // Module created or modified. + // Module created or modified, encoded as a RFC 3339 timestamp. optional dateTimeStamp; // Unique identifier for the module. variant id; @@ -1184,9 +1272,6 @@ struct Module { optional isUserCode; // A name of the module. string name; - // optional but recommended attributes. - // always try to use these first before introducing additional attributes. - // // Logical full path to the module. The exact definition is implementation // defined, but usually this would be a full path to the on-disk file for the // module. @@ -1194,8 +1279,8 @@ struct Module { // Logical full path to the symbol file. The exact definition is // implementation defined. optional symbolFilePath; - // User understandable description of if symbols were found for the module - // (ex: 'Symbols Loaded', 'Symbols not found', etc. + // User-understandable description of if symbols were found for the module + // (ex: 'Symbols Loaded', 'Symbols not found', etc.) optional symbolStatus; // Version of Module. optional version; @@ -1205,7 +1290,7 @@ DAP_DECLARE_STRUCT_TYPEINFO(Module); // The event indicates that some information about a module has changed. struct ModuleEvent : public Event { - // The new, changed, or removed module. In case of 'removed' only the module + // The new, changed, or removed module. In case of `removed` only the module // id is used. Module module; // The reason for the event. @@ -1217,7 +1302,7 @@ struct ModuleEvent : public Event { DAP_DECLARE_STRUCT_TYPEINFO(ModuleEvent); -// Response to 'modules' request. +// Response to `modules` request. struct ModulesResponse : public Response { // All modules or range of modules. array modules; @@ -1229,12 +1314,12 @@ DAP_DECLARE_STRUCT_TYPEINFO(ModulesResponse); // Modules can be retrieved from the debug adapter with this request which can // either return all modules or a range of modules to support paging. Clients -// should only call this request if the capability 'supportsModulesRequest' is -// true. +// should only call this request if the corresponding capability +// `supportsModulesRequest` is true. struct ModulesRequest : public Request { using Response = ModulesResponse; - // The number of modules to return. If moduleCount is not specified or 0, all - // modules are returned. + // The number of modules to return. If `moduleCount` is not specified or 0, + // all modules are returned. optional moduleCount; // The index of the first module to return; if omitted modules start at 0. optional startModule; @@ -1242,28 +1327,35 @@ struct ModulesRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(ModulesRequest); -// Response to 'next' request. This is just an acknowledgement, so no body field +// Response to `next` request. This is just an acknowledgement, so no body field // is required. struct NextResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(NextResponse); -// The granularity of one 'step' in the stepping requests 'next', 'stepIn', -// 'stepOut', and 'stepBack'. +// The granularity of one 'step' in the stepping requests `next`, `stepIn`, +// `stepOut`, and `stepBack`. // // Must be one of the following enumeration values: // 'statement', 'line', 'instruction' using SteppingGranularity = string; -// The request starts the debuggee to run again for one step. -// The debug adapter first sends the response and then a 'stopped' event (with -// reason 'step') after the step has completed. +// The request executes one step (in the given granularity) for the specified +// thread and allows all other threads to run freely by resuming them. If the +// debug adapter supports single thread execution (see capability +// `supportsSingleThreadExecutionRequests`), setting the `singleThread` argument +// to true prevents other suspended threads from resuming. The debug adapter +// first sends the response and then a `stopped` event (with reason `step`) +// after the step has completed. struct NextRequest : public Request { using Response = NextResponse; - // Optional granularity to step. If no granularity is specified, a granularity - // of 'statement' is assumed. + // Stepping granularity. If no granularity is specified, a granularity of + // `statement` is assumed. optional granularity; - // Execute 'next' for this thread. + // If this flag is true, all other suspended threads are not resumed. + optional singleThread; + // Specifies the thread for which to resume execution for one step (of the + // given granularity). integer threadId; }; @@ -1271,15 +1363,18 @@ DAP_DECLARE_STRUCT_TYPEINFO(NextRequest); // The event indicates that the target has produced some output. struct OutputEvent : public Event { - // The output category. If not specified, 'console' is assumed. + // The output category. If not specified or if the category is not understood + // by the client, `console` is assumed. // // May be one of the following enumeration values: - // 'console', 'stdout', 'stderr', 'telemetry' + // 'console', 'important', 'stdout', 'stderr', 'telemetry' optional category; - // An optional source location column where the output was produced. + // The position in `line` where the output was produced. It is measured in + // UTF-16 code units and the client capability `columnsStartAt1` determines + // whether it is 0- or 1-based. optional column; - // Optional data to report. For the 'telemetry' category the data will be sent - // to telemetry, for the other categories the data is shown in JSON format. + // Additional data to report. For the `telemetry` category the data is sent to + // telemetry, for the other categories the data is shown in JSON format. optional, boolean, integer, null, number, object, string>> data; // Support for keeping an output log organized by grouping related messages. @@ -1287,30 +1382,30 @@ struct OutputEvent : public Event { // Must be one of the following enumeration values: // 'start', 'startCollapsed', 'end' optional group; - // An optional source location line where the output was produced. + // The source location's line where the output was produced. optional line; // The output to report. string output; - // An optional source location where the output was produced. + // The source location where the output was produced. optional source; - // If an attribute 'variablesReference' exists and its value is > 0, the + // If an attribute `variablesReference` exists and its value is > 0, the // output contains objects which can be retrieved by passing - // 'variablesReference' to the 'variables' request. The value should be less + // `variablesReference` to the `variables` request. The value should be less // than or equal to 2147483647 (2^31-1). optional variablesReference; }; DAP_DECLARE_STRUCT_TYPEINFO(OutputEvent); -// Response to 'pause' request. This is just an acknowledgement, so no body +// Response to `pause` request. This is just an acknowledgement, so no body // field is required. struct PauseResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(PauseResponse); // The request suspends the debuggee. -// The debug adapter first sends the response and then a 'stopped' event (with -// reason 'pause') after the thread has been paused successfully. +// The debug adapter first sends the response and then a `stopped` event (with +// reason `pause`) after the thread has been paused successfully. struct PauseRequest : public Request { using Response = PauseResponse; // Pause execution for this thread. @@ -1335,22 +1430,21 @@ struct ProcessEvent : public Event { // Must be one of the following enumeration values: // 'launch', 'attach', 'attachForSuspendedLaunch' optional startMethod; - // The system process id of the debugged process. This property will be - // missing for non-system processes. + // The system process id of the debugged process. This property is missing for + // non-system processes. optional systemProcessId; }; DAP_DECLARE_STRUCT_TYPEINFO(ProcessEvent); -// The event signals the end of the progress reporting with an optional final -// message. This event should only be sent if the client has passed the value -// true for the 'supportsProgressReporting' capability of the 'initialize' -// request. +// The event signals the end of the progress reporting with a final message. +// This event should only be sent if the corresponding capability +// `supportsProgressReporting` is true. struct ProgressEndEvent : public Event { - // Optional, more detailed progress message. If omitted, the previous message - // (if any) is used. + // More detailed progress message. If omitted, the previous message (if any) + // is used. optional message; - // The ID that was introduced in the initial 'ProgressStartEvent'. + // The ID that was introduced in the initial `ProgressStartEvent`. string progressId; }; @@ -1359,21 +1453,20 @@ DAP_DECLARE_STRUCT_TYPEINFO(ProgressEndEvent); // The event signals that a long running operation is about to start and // provides additional information for the client to set up a corresponding // progress and cancellation UI. The client is free to delay the showing of the -// UI in order to reduce flicker. This event should only be sent if the client -// has passed the value true for the 'supportsProgressReporting' capability of -// the 'initialize' request. +// UI in order to reduce flicker. This event should only be sent if the +// corresponding capability `supportsProgressReporting` is true. struct ProgressStartEvent : public Event { - // If true, the request that reports progress may be canceled with a 'cancel' + // If true, the request that reports progress may be cancelled with a `cancel` // request. So this property basically controls whether the client should use // UX that supports cancellation. Clients that don't support cancellation are // allowed to ignore the setting. optional cancellable; - // Optional, more detailed progress message. + // More detailed progress message. optional message; - // Optional progress percentage to display (value range: 0 to 100). If omitted - // no percentage will be shown. + // Progress percentage to display (value range: 0 to 100). If omitted no + // percentage is shown. optional percentage; - // An ID that must be used in subsequent 'progressUpdate' and 'progressEnd' + // An ID that can be used in subsequent `progressUpdate` and `progressEnd` // events to make them refer to the same progress reporting. IDs must be // unique within a debug session. string progressId; @@ -1383,74 +1476,73 @@ struct ProgressStartEvent : public Event { // request ID is omitted, the progress report is assumed to be related to some // general activity of the debug adapter. optional requestId; - // Mandatory (short) title of the progress reporting. Shown in the UI to - // describe the long running operation. + // Short title of the progress reporting. Shown in the UI to describe the long + // running operation. string title; }; DAP_DECLARE_STRUCT_TYPEINFO(ProgressStartEvent); -// The event signals that the progress reporting needs to updated with a new +// The event signals that the progress reporting needs to be updated with a new // message and/or percentage. The client does not have to update the UI // immediately, but the clients needs to keep track of the message and/or -// percentage values. This event should only be sent if the client has passed -// the value true for the 'supportsProgressReporting' capability of the -// 'initialize' request. +// percentage values. This event should only be sent if the corresponding +// capability `supportsProgressReporting` is true. struct ProgressUpdateEvent : public Event { - // Optional, more detailed progress message. If omitted, the previous message - // (if any) is used. + // More detailed progress message. If omitted, the previous message (if any) + // is used. optional message; - // Optional progress percentage to display (value range: 0 to 100). If omitted - // no percentage will be shown. + // Progress percentage to display (value range: 0 to 100). If omitted no + // percentage is shown. optional percentage; - // The ID that was introduced in the initial 'progressStart' event. + // The ID that was introduced in the initial `progressStart` event. string progressId; }; DAP_DECLARE_STRUCT_TYPEINFO(ProgressUpdateEvent); -// Response to 'readMemory' request. +// Response to `readMemory` request. struct ReadMemoryResponse : public Response { // The address of the first byte of data returned. - // Treated as a hex value if prefixed with '0x', or as a decimal value + // Treated as a hex value if prefixed with `0x`, or as a decimal value // otherwise. string address; // The bytes read from memory, encoded using base64. optional data; // The number of unreadable bytes encountered after the last successfully read - // byte. This can be used to determine the number of bytes that must be - // skipped before a subsequent 'readMemory' request will succeed. + // byte. This can be used to determine the number of bytes that should be + // skipped before a subsequent `readMemory` request succeeds. optional unreadableBytes; }; DAP_DECLARE_STRUCT_TYPEINFO(ReadMemoryResponse); // Reads bytes from memory at the provided location. -// Clients should only call this request if the capability -// 'supportsReadMemoryRequest' is true. +// Clients should only call this request if the corresponding capability +// `supportsReadMemoryRequest` is true. struct ReadMemoryRequest : public Request { using Response = ReadMemoryResponse; // Number of bytes to read at the specified location and offset. integer count; // Memory reference to the base location from which data should be read. string memoryReference; - // Optional offset (in bytes) to be applied to the reference location before - // reading data. Can be negative. + // Offset (in bytes) to be applied to the reference location before reading + // data. Can be negative. optional offset; }; DAP_DECLARE_STRUCT_TYPEINFO(ReadMemoryRequest); -// Response to 'restartFrame' request. This is just an acknowledgement, so no +// Response to `restartFrame` request. This is just an acknowledgement, so no // body field is required. struct RestartFrameResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(RestartFrameResponse); // The request restarts execution of the specified stackframe. -// The debug adapter first sends the response and then a 'stopped' event (with -// reason 'restart') after the restart has completed. Clients should only call -// this request if the capability 'supportsRestartFrame' is true. +// The debug adapter first sends the response and then a `stopped` event (with +// reason `restart`) after the restart has completed. Clients should only call +// this request if the corresponding capability `supportsRestartFrame` is true. struct RestartFrameRequest : public Request { using Response = RestartFrameResponse; // Restart this stackframe. @@ -1459,40 +1551,78 @@ struct RestartFrameRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(RestartFrameRequest); -// Response to 'restart' request. This is just an acknowledgement, so no body +// Response to `restart` request. This is just an acknowledgement, so no body // field is required. struct RestartResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(RestartResponse); +// Arguments for `launch` request. Additional attributes are implementation +// specific. +struct LaunchRequestArguments { + // Arbitrary data from the previous, restarted session. + // The data is sent as the `restart` attribute of the `terminated` event. + // The client should leave the data intact. + optional, boolean, integer, null, number, object, string>> + restart; + // If true, the launch request should launch the program without enabling + // debugging. + optional noDebug; +}; + +DAP_DECLARE_STRUCT_TYPEINFO(LaunchRequestArguments); + +// Arguments for `attach` request. Additional attributes are implementation +// specific. +struct AttachRequestArguments { + // Arbitrary data from the previous, restarted session. + // The data is sent as the `restart` attribute of the `terminated` event. + // The client should leave the data intact. + optional, boolean, integer, null, number, object, string>> + restart; +}; + +DAP_DECLARE_STRUCT_TYPEINFO(AttachRequestArguments); + // Restarts a debug session. Clients should only call this request if the -// capability 'supportsRestartRequest' is true. If the capability is missing or -// has the value false, a typical client will emulate 'restart' by terminating -// the debug adapter first and then launching it anew. +// corresponding capability `supportsRestartRequest` is true. If the capability +// is missing or has the value false, a typical client emulates `restart` by +// terminating the debug adapter first and then launching it anew. struct RestartRequest : public Request { using Response = RestartResponse; + // The latest version of the `launch` or `attach` configuration. + optional> arguments; }; DAP_DECLARE_STRUCT_TYPEINFO(RestartRequest); -// Response to 'reverseContinue' request. This is just an acknowledgement, so no +// Response to `reverseContinue` request. This is just an acknowledgement, so no // body field is required. struct ReverseContinueResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(ReverseContinueResponse); -// The request starts the debuggee to run backward. -// Clients should only call this request if the capability 'supportsStepBack' is -// true. +// The request resumes backward execution of all threads. If the debug adapter +// supports single thread execution (see capability +// `supportsSingleThreadExecutionRequests`), setting the `singleThread` argument +// to true resumes only the specified thread. If not all threads were resumed, +// the `allThreadsContinued` attribute of the response should be set to false. +// Clients should only call this request if the corresponding capability +// `supportsStepBack` is true. struct ReverseContinueRequest : public Request { using Response = ReverseContinueResponse; - // Execute 'reverseContinue' for this thread. + // If this flag is true, backward execution is resumed only for the thread + // with given `threadId`. + optional singleThread; + // Specifies the active thread. If the debug adapter supports single thread + // execution (see `supportsSingleThreadExecutionRequests`) and the + // `singleThread` argument is true, only the thread with this ID is resumed. integer threadId; }; DAP_DECLARE_STRUCT_TYPEINFO(ReverseContinueRequest); -// Response to 'runInTerminal' request. +// Response to `runInTerminal` request. struct RunInTerminalResponse : public Response { // The process ID. The value should be less than or equal to 2147483647 // (2^31-1). @@ -1504,15 +1634,32 @@ struct RunInTerminalResponse : public Response { DAP_DECLARE_STRUCT_TYPEINFO(RunInTerminalResponse); -// This optional request is sent from the debug adapter to the client to run a -// command in a terminal. This is typically used to launch the debuggee in a -// terminal provided by the client. This request should only be called if the -// client has passed the value true for the 'supportsRunInTerminalRequest' -// capability of the 'initialize' request. +// This request is sent from the debug adapter to the client to run a command in +// a terminal. This is typically used to launch the debuggee in a terminal +// provided by the client. This request should only be called if the +// corresponding client capability `supportsRunInTerminalRequest` is true. +// Client implementations of `runInTerminal` are free to run the command however +// they choose including issuing the command to a command line interpreter (aka +// 'shell'). Argument strings passed to the `runInTerminal` request must arrive +// verbatim in the command to be run. As a consequence, clients which use a +// shell are responsible for escaping any special shell characters in the +// argument strings to prevent them from being interpreted (and modified) by the +// shell. Some users may wish to take advantage of shell processing in the +// argument strings. For clients which implement `runInTerminal` using an +// intermediary shell, the `argsCanBeInterpretedByShell` property can be set to +// true. In this case the client is requested not to escape any special shell +// characters in the argument strings. struct RunInTerminalRequest : public Request { using Response = RunInTerminalResponse; // List of arguments. The first argument is the command to run. array args; + // This property should only be set if the corresponding capability + // `supportsArgsCanBeInterpretedByShell` is true. If the client uses an + // intermediary shell to launch the application, then the client must not + // attempt to escape characters with special meanings for the shell. The user + // is fully responsible for escaping as needed and that arguments using + // special characters may not be portable across shells. + optional argsCanBeInterpretedByShell; // Working directory for the command. For non-empty, valid paths this // typically results in execution of a change directory command. string cwd; @@ -1524,53 +1671,57 @@ struct RunInTerminalRequest : public Request { // Must be one of the following enumeration values: // 'integrated', 'external' optional kind; - // Optional title of the terminal. + // Title of the terminal. optional title; }; DAP_DECLARE_STRUCT_TYPEINFO(RunInTerminalRequest); -// A Scope is a named container for variables. Optionally a scope can map to a +// A `Scope` is a named container for variables. Optionally a scope can map to a // source or a range within a source. struct Scope { - // Optional start column of the range covered by this scope. + // Start position of the range covered by the scope. It is measured in UTF-16 + // code units and the client capability `columnsStartAt1` determines whether + // it is 0- or 1-based. optional column; - // Optional end column of the range covered by this scope. + // End position of the range covered by the scope. It is measured in UTF-16 + // code units and the client capability `columnsStartAt1` determines whether + // it is 0- or 1-based. optional endColumn; - // Optional end line of the range covered by this scope. + // The end line of the range covered by this scope. optional endLine; // If true, the number of variables in this scope is large or expensive to // retrieve. boolean expensive; // The number of indexed variables in this scope. - // The client can use this optional information to present the variables in a - // paged UI and fetch them in chunks. + // The client can use this information to present the variables in a paged UI + // and fetch them in chunks. optional indexedVariables; - // Optional start line of the range covered by this scope. + // The start line of the range covered by this scope. optional line; // Name of the scope such as 'Arguments', 'Locals', or 'Registers'. This // string is shown in the UI as is and can be translated. string name; // The number of named variables in this scope. - // The client can use this optional information to present the variables in a - // paged UI and fetch them in chunks. + // The client can use this information to present the variables in a paged UI + // and fetch them in chunks. optional namedVariables; - // An optional hint for how to present this scope in the UI. If this attribute - // is missing, the scope is shown with a generic UI. + // A hint for how to present this scope in the UI. If this attribute is + // missing, the scope is shown with a generic UI. // // May be one of the following enumeration values: // 'arguments', 'locals', 'registers' optional presentationHint; - // Optional source for this scope. + // The source for this scope. optional source; // The variables of this scope can be retrieved by passing the value of - // variablesReference to the VariablesRequest. + // `variablesReference` to the `variables` request. integer variablesReference; }; DAP_DECLARE_STRUCT_TYPEINFO(Scope); -// Response to 'scopes' request. +// Response to `scopes` request. struct ScopesResponse : public Response { // The scopes of the stackframe. If the array has length zero, there are no // scopes available. @@ -1588,39 +1739,42 @@ struct ScopesRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(ScopesRequest); -// Response to 'setBreakpoints' request. +// Response to `setBreakpoints` request. // Returned is information about each breakpoint created by this request. // This includes the actual code location and whether the breakpoint could be // verified. The breakpoints returned are in the same order as the elements of -// the 'breakpoints' (or the deprecated 'lines') array in the arguments. +// the `breakpoints` (or the deprecated `lines`) array in the arguments. struct SetBreakpointsResponse : public Response { // Information about the breakpoints. // The array elements are in the same order as the elements of the - // 'breakpoints' (or the deprecated 'lines') array in the arguments. + // `breakpoints` (or the deprecated `lines`) array in the arguments. array breakpoints; }; DAP_DECLARE_STRUCT_TYPEINFO(SetBreakpointsResponse); -// Properties of a breakpoint or logpoint passed to the setBreakpoints request. +// Properties of a breakpoint or logpoint passed to the `setBreakpoints` +// request. struct SourceBreakpoint { - // An optional source column of the breakpoint. + // Start position within source line of the breakpoint or logpoint. It is + // measured in UTF-16 code units and the client capability `columnsStartAt1` + // determines whether it is 0- or 1-based. optional column; - // An optional expression for conditional breakpoints. - // It is only honored by a debug adapter if the capability - // 'supportsConditionalBreakpoints' is true. + // The expression for conditional breakpoints. + // It is only honored by a debug adapter if the corresponding capability + // `supportsConditionalBreakpoints` is true. optional condition; - // An optional expression that controls how many hits of the breakpoint are - // ignored. The backend is expected to interpret the expression as needed. The - // attribute is only honored by a debug adapter if the capability - // 'supportsHitConditionalBreakpoints' is true. + // The expression that controls how many hits of the breakpoint are ignored. + // The debug adapter is expected to interpret the expression as needed. + // The attribute is only honored by a debug adapter if the corresponding + // capability `supportsHitConditionalBreakpoints` is true. optional hitCondition; // The source line of the breakpoint or logpoint. integer line; - // If this attribute exists and is non-empty, the backend must not 'break' - // (stop) but log the message instead. Expressions within {} are interpolated. - // The attribute is only honored by a debug adapter if the capability - // 'supportsLogPoints' is true. + // If this attribute exists and is non-empty, the debug adapter must not + // 'break' (stop) but log the message instead. Expressions within `{}` are + // interpolated. The attribute is only honored by a debug adapter if the + // corresponding capability `supportsLogPoints` is true. optional logMessage; }; @@ -1628,16 +1782,16 @@ DAP_DECLARE_STRUCT_TYPEINFO(SourceBreakpoint); // Sets multiple breakpoints for a single source and clears all previous // breakpoints in that source. To clear all breakpoint for a source, specify an -// empty array. When a breakpoint is hit, a 'stopped' event (with reason -// 'breakpoint') is generated. +// empty array. When a breakpoint is hit, a `stopped` event (with reason +// `breakpoint`) is generated. struct SetBreakpointsRequest : public Request { using Response = SetBreakpointsResponse; // The code locations of the breakpoints. optional> breakpoints; // Deprecated: The code locations of the breakpoints. optional> lines; - // The source location of the breakpoints; either 'source.path' or - // 'source.reference' must be specified. + // The source location of the breakpoints; either `source.path` or + // `source.sourceReference` must be specified. Source source; // A value of true indicates that the underlying source has been modified // which results in new breakpoint locations. @@ -1646,27 +1800,27 @@ struct SetBreakpointsRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(SetBreakpointsRequest); -// Response to 'setDataBreakpoints' request. +// Response to `setDataBreakpoints` request. // Returned is information about each breakpoint created by this request. struct SetDataBreakpointsResponse : public Response { // Information about the data breakpoints. The array elements correspond to - // the elements of the input argument 'breakpoints' array. + // the elements of the input argument `breakpoints` array. array breakpoints; }; DAP_DECLARE_STRUCT_TYPEINFO(SetDataBreakpointsResponse); -// Properties of a data breakpoint passed to the setDataBreakpoints request. +// Properties of a data breakpoint passed to the `setDataBreakpoints` request. struct DataBreakpoint { // The access type of the data. optional accessType; - // An optional expression for conditional breakpoints. + // An expression for conditional breakpoints. optional condition; // An id representing the data. This id is returned from the - // dataBreakpointInfo request. + // `dataBreakpointInfo` request. string dataId; - // An optional expression that controls how many hits of the breakpoint are - // ignored. The backend is expected to interpret the expression as needed. + // An expression that controls how many hits of the breakpoint are ignored. + // The debug adapter is expected to interpret the expression as needed. optional hitCondition; }; @@ -1674,9 +1828,9 @@ DAP_DECLARE_STRUCT_TYPEINFO(DataBreakpoint); // 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. Clients should only call this request if the -// capability 'supportsDataBreakpoints' is true. +// When a data breakpoint is hit, a `stopped` event (with reason `data +// breakpoint`) is generated. Clients should only call this request if the +// corresponding capability `supportsDataBreakpoints` is true. struct SetDataBreakpointsRequest : public Request { using Response = SetDataBreakpointsResponse; // The contents of this array replaces all existing data breakpoints. An empty @@ -1686,18 +1840,38 @@ struct SetDataBreakpointsRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(SetDataBreakpointsRequest); -// Response to 'setExceptionBreakpoints' request. This is just an -// acknowledgement, so no body field is required. -struct SetExceptionBreakpointsResponse : public Response {}; +// Response to `setExceptionBreakpoints` request. +// The response contains an array of `Breakpoint` objects with information about +// each exception breakpoint or filter. The `Breakpoint` objects are in the same +// order as the elements of the `filters`, `filterOptions`, `exceptionOptions` +// arrays given as arguments. If both `filters` and `filterOptions` are given, +// the returned array must start with `filters` information first, followed by +// `filterOptions` information. The `verified` property of a `Breakpoint` object +// signals whether the exception breakpoint or filter could be successfully +// created and whether the condition or hit count expressions are valid. In case +// of an error the `message` property explains the problem. The `id` property +// can be used to introduce a unique ID for the exception breakpoint or filter +// so that it can be updated subsequently by sending breakpoint events. For +// backward compatibility both the `breakpoints` array and the enclosing `body` +// are optional. If these elements are missing a client is not able to show +// problems for individual exception breakpoints or filters. +struct SetExceptionBreakpointsResponse : public Response { + // Information about the exception breakpoints or filters. + // The breakpoints returned are in the same order as the elements of the + // `filters`, `filterOptions`, `exceptionOptions` arrays in the arguments. If + // both `filters` and `filterOptions` are given, the returned array must start + // with `filters` information first, followed by `filterOptions` information. + optional> breakpoints; +}; DAP_DECLARE_STRUCT_TYPEINFO(SetExceptionBreakpointsResponse); -// An ExceptionPathSegment represents a segment in a path that is used to match -// leafs or nodes in a tree of exceptions. If a segment consists of more than -// one name, it matches the names provided if 'negate' is false or missing or it -// matches anything except the names provided if 'negate' is true. +// An `ExceptionPathSegment` represents a segment in a path that is used to +// match leafs or nodes in a tree of exceptions. If a segment consists of more +// than one name, it matches the names provided if `negate` is false or missing, +// or it matches anything except the names provided if `negate` is true. struct ExceptionPathSegment { - // Depending on the value of 'negate' the names that should match or not + // Depending on the value of `negate` the names that should match or not // match. array names; // If false or missing this segment matches the names provided, otherwise it @@ -1707,11 +1881,11 @@ struct ExceptionPathSegment { DAP_DECLARE_STRUCT_TYPEINFO(ExceptionPathSegment); -// An ExceptionOptions assigns configuration options to a set of exceptions. +// An `ExceptionOptions` assigns configuration options to a set of exceptions. struct ExceptionOptions { // Condition when a thrown exception should result in a break. ExceptionBreakMode breakMode = "never"; - // A path that selects a single or multiple exceptions in a tree. If 'path' is + // A path that selects a single or multiple exceptions in a tree. If `path` is // missing, the whole tree is selected. By convention the first segment of the // path is a category that is used to group exceptions in the UI. optional> path; @@ -1719,81 +1893,81 @@ struct ExceptionOptions { DAP_DECLARE_STRUCT_TYPEINFO(ExceptionOptions); -// An ExceptionFilterOptions is used to specify an exception filter together -// with a condition for the setExceptionsFilter request. +// An `ExceptionFilterOptions` is used to specify an exception filter together +// with a condition for the `setExceptionBreakpoints` request. struct ExceptionFilterOptions { - // An optional expression for conditional exceptions. - // The exception will break into the debugger if the result of the condition - // is true. + // An expression for conditional exceptions. + // The exception breaks into the debugger if the result of the condition is + // true. optional condition; - // ID of an exception filter returned by the 'exceptionBreakpointFilters' + // ID of an exception filter returned by the `exceptionBreakpointFilters` // capability. string filterId; }; DAP_DECLARE_STRUCT_TYPEINFO(ExceptionFilterOptions); -// The request configures the debuggers response to thrown exceptions. -// If an exception is configured to break, a 'stopped' event is fired (with -// reason 'exception'). Clients should only call this request if the capability -// 'exceptionBreakpointFilters' returns one or more filters. If a filter or -// filter option is invalid (e.g. due to an invalid 'condition'), the request -// should fail with an 'ErrorResponse' explaining the problem(s). +// The request configures the debugger's response to thrown exceptions. +// If an exception is configured to break, a `stopped` event is fired (with +// reason `exception`). Clients should only call this request if the +// corresponding capability `exceptionBreakpointFilters` returns one or more +// filters. struct SetExceptionBreakpointsRequest : public Request { using Response = SetExceptionBreakpointsResponse; // Configuration options for selected exceptions. - // The attribute is only honored by a debug adapter if the capability - // 'supportsExceptionOptions' is true. + // The attribute is only honored by a debug adapter if the corresponding + // capability `supportsExceptionOptions` is true. optional> exceptionOptions; // Set of exception filters and their options. The set of all possible - // exception filters is defined by the 'exceptionBreakpointFilters' + // exception filters is defined by the `exceptionBreakpointFilters` // capability. This attribute is only honored by a debug adapter if the - // capability 'supportsExceptionFilterOptions' is true. The 'filter' and - // 'filterOptions' sets are additive. + // corresponding capability `supportsExceptionFilterOptions` is true. The + // `filter` and `filterOptions` sets are additive. optional> filterOptions; // Set of exception filters specified by their ID. The set of all possible - // exception filters is defined by the 'exceptionBreakpointFilters' - // capability. The 'filter' and 'filterOptions' sets are additive. + // exception filters is defined by the `exceptionBreakpointFilters` + // capability. The `filter` and `filterOptions` sets are additive. array filters; }; DAP_DECLARE_STRUCT_TYPEINFO(SetExceptionBreakpointsRequest); -// Response to 'setExpression' request. +// Response to `setExpression` request. struct SetExpressionResponse : public Response { // The number of indexed child variables. - // The client can use this optional information to present the variables in a - // paged UI and fetch them in chunks. The value should be less than or equal - // to 2147483647 (2^31-1). + // The client can use this information to present the variables in a paged UI + // and fetch them in chunks. The value should be less than or equal to + // 2147483647 (2^31-1). optional indexedVariables; // The number of named child variables. - // The client can use this optional information to present the variables in a - // paged UI and fetch them in chunks. The value should be less than or equal - // to 2147483647 (2^31-1). + // The client can use this information to present the variables in a paged UI + // and fetch them in chunks. The value should be less than or equal to + // 2147483647 (2^31-1). optional namedVariables; // Properties of a value that can be used to determine how to render the // result in the UI. optional presentationHint; - // The optional type of the value. - // This attribute should only be returned by a debug adapter if the client has - // passed the value true for the 'supportsVariableType' capability of the - // 'initialize' request. + // The type of the value. + // This attribute should only be returned by a debug adapter if the + // corresponding capability `supportsVariableType` is true. optional type; // The new value of the expression. string value; - // If variablesReference is > 0, the value is structured and its children can - // be retrieved by passing variablesReference to the VariablesRequest. The - // value should be less than or equal to 2147483647 (2^31-1). + // If `variablesReference` is > 0, the value is structured and its children + // can be retrieved by passing `variablesReference` to the `variables` + // request. The value should be less than or equal to 2147483647 (2^31-1). optional variablesReference; }; DAP_DECLARE_STRUCT_TYPEINFO(SetExpressionResponse); -// Evaluates the given 'value' expression and assigns it to the 'expression' +// Evaluates the given `value` expression and assigns it to the `expression` // which must be a modifiable l-value. The expressions have access to any // variables and arguments that are in scope of the specified frame. Clients -// should only call this request if the capability 'supportsSetExpression' is -// true. +// should only call this request if the corresponding capability +// `supportsSetExpression` is true. If a debug adapter implements both +// `setExpression` and `setVariable`, a client uses `setExpression` if the +// variable has an `evaluateName` property. struct SetExpressionRequest : public Request { using Response = SetExpressionResponse; // The l-value expression to assign to. @@ -1809,26 +1983,26 @@ struct SetExpressionRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(SetExpressionRequest); -// Response to 'setFunctionBreakpoints' request. +// Response to `setFunctionBreakpoints` request. // Returned is information about each breakpoint created by this request. struct SetFunctionBreakpointsResponse : public Response { // Information about the breakpoints. The array elements correspond to the - // elements of the 'breakpoints' array. + // elements of the `breakpoints` array. array breakpoints; }; DAP_DECLARE_STRUCT_TYPEINFO(SetFunctionBreakpointsResponse); -// Properties of a breakpoint passed to the setFunctionBreakpoints request. +// Properties of a breakpoint passed to the `setFunctionBreakpoints` request. struct FunctionBreakpoint { - // An optional expression for conditional breakpoints. - // It is only honored by a debug adapter if the capability - // 'supportsConditionalBreakpoints' is true. + // An expression for conditional breakpoints. + // It is only honored by a debug adapter if the corresponding capability + // `supportsConditionalBreakpoints` is true. optional condition; - // An optional expression that controls how many hits of the breakpoint are - // ignored. The backend is expected to interpret the expression as needed. The - // attribute is only honored by a debug adapter if the capability - // 'supportsHitConditionalBreakpoints' is true. + // An expression that controls how many hits of the breakpoint are ignored. + // The debug adapter is expected to interpret the expression as needed. + // The attribute is only honored by a debug adapter if the corresponding + // capability `supportsHitConditionalBreakpoints` is true. optional hitCondition; // The name of the function. string name; @@ -1838,9 +2012,9 @@ DAP_DECLARE_STRUCT_TYPEINFO(FunctionBreakpoint); // Replaces all existing function breakpoints with new function breakpoints. // To clear all function breakpoints, specify an empty array. -// When a function breakpoint is hit, a 'stopped' event (with reason 'function -// breakpoint') is generated. Clients should only call this request if the -// capability 'supportsFunctionBreakpoints' is true. +// When a function breakpoint is hit, a `stopped` event (with reason `function +// breakpoint`) is generated. Clients should only call this request if the +// corresponding capability `supportsFunctionBreakpoints` is true. struct SetFunctionBreakpointsRequest : public Request { using Response = SetFunctionBreakpointsResponse; // The function names of the breakpoints. @@ -1849,31 +2023,32 @@ struct SetFunctionBreakpointsRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(SetFunctionBreakpointsRequest); -// Response to 'setInstructionBreakpoints' request +// Response to `setInstructionBreakpoints` request struct SetInstructionBreakpointsResponse : public Response { // Information about the breakpoints. The array elements correspond to the - // elements of the 'breakpoints' array. + // elements of the `breakpoints` array. array breakpoints; }; DAP_DECLARE_STRUCT_TYPEINFO(SetInstructionBreakpointsResponse); -// Properties of a breakpoint passed to the setInstructionBreakpoints request +// Properties of a breakpoint passed to the `setInstructionBreakpoints` request struct InstructionBreakpoint { - // An optional expression for conditional breakpoints. - // It is only honored by a debug adapter if the capability - // 'supportsConditionalBreakpoints' is true. + // An expression for conditional breakpoints. + // It is only honored by a debug adapter if the corresponding capability + // `supportsConditionalBreakpoints` is true. optional condition; - // An optional expression that controls how many hits of the breakpoint are - // ignored. The backend is expected to interpret the expression as needed. The - // attribute is only honored by a debug adapter if the capability - // 'supportsHitConditionalBreakpoints' is true. + // An expression that controls how many hits of the breakpoint are ignored. + // The debug adapter is expected to interpret the expression as needed. + // The attribute is only honored by a debug adapter if the corresponding + // capability `supportsHitConditionalBreakpoints` is true. optional hitCondition; // The instruction reference of the breakpoint. // This should be a memory or instruction pointer reference from an - // EvaluateResponse, Variable, StackFrame, GotoTarget, or Breakpoint. + // `EvaluateResponse`, `Variable`, `StackFrame`, `GotoTarget`, or + // `Breakpoint`. string instructionReference; - // An optional offset from the instruction reference. + // The offset from the instruction reference. // This can be negative. optional offset; }; @@ -1881,11 +2056,11 @@ struct InstructionBreakpoint { DAP_DECLARE_STRUCT_TYPEINFO(InstructionBreakpoint); // Replaces all existing instruction breakpoints. Typically, instruction -// breakpoints would be set from a diassembly window. To clear all instruction +// breakpoints would be set from a disassembly window. To clear all instruction // breakpoints, specify an empty array. When an instruction breakpoint is hit, a -// 'stopped' event (with reason 'instruction breakpoint') is generated. Clients -// should only call this request if the capability -// 'supportsInstructionBreakpoints' is true. +// `stopped` event (with reason `instruction breakpoint`) is generated. Clients +// should only call this request if the corresponding capability +// `supportsInstructionBreakpoints` is true. struct SetInstructionBreakpointsRequest : public Request { using Response = SetInstructionBreakpointsResponse; // The instruction references of the breakpoints @@ -1894,34 +2069,37 @@ struct SetInstructionBreakpointsRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(SetInstructionBreakpointsRequest); -// Response to 'setVariable' request. +// Response to `setVariable` request. struct SetVariableResponse : public Response { // The number of indexed child variables. - // The client can use this optional information to present the variables in a - // paged UI and fetch them in chunks. The value should be less than or equal - // to 2147483647 (2^31-1). + // The client can use this information to present the variables in a paged UI + // and fetch them in chunks. The value should be less than or equal to + // 2147483647 (2^31-1). optional indexedVariables; // The number of named child variables. - // The client can use this optional information to present the variables in a - // paged UI and fetch them in chunks. The value should be less than or equal - // to 2147483647 (2^31-1). + // The client can use this information to present the variables in a paged UI + // and fetch them in chunks. The value should be less than or equal to + // 2147483647 (2^31-1). optional namedVariables; // The type of the new value. Typically shown in the UI when hovering over the // value. optional type; // The new value of the variable. string value; - // If variablesReference is > 0, the new value is structured and its children - // can be retrieved by passing variablesReference to the VariablesRequest. The - // value should be less than or equal to 2147483647 (2^31-1). + // If `variablesReference` is > 0, the new value is structured and its + // children can be retrieved by passing `variablesReference` to the + // `variables` request. The value should be less than or equal to 2147483647 + // (2^31-1). optional variablesReference; }; DAP_DECLARE_STRUCT_TYPEINFO(SetVariableResponse); // Set the variable with the given name in the variable container to a new -// value. Clients should only call this request if the capability -// 'supportsSetVariable' is true. +// value. Clients should only call this request if the corresponding capability +// `supportsSetVariable` is true. If a debug adapter implements both +// `setVariable` and `setExpression`, a client will only use `setExpression` if +// the variable has an `evaluateName` property. struct SetVariableRequest : public Request { using Response = SetVariableResponse; // Specifies details on how to format the response value. @@ -1936,11 +2114,11 @@ struct SetVariableRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(SetVariableRequest); -// Response to 'source' request. +// Response to `source` request. struct SourceResponse : public Response { // Content of the source reference. string content; - // Optional content type (mime type) of the source. + // Content type (MIME type) of the source. optional mimeType; }; @@ -1949,12 +2127,12 @@ DAP_DECLARE_STRUCT_TYPEINFO(SourceResponse); // The request retrieves the source code for a given source reference. struct SourceRequest : public Request { using Response = SourceResponse; - // Specifies the source content to load. Either source.path or - // source.sourceReference must be specified. + // Specifies the source content to load. Either `source.path` or + // `source.sourceReference` must be specified. optional source; - // The reference to the source. This is the same as source.sourceReference. - // This is provided for backward compatibility since old backends do not - // understand the 'source' attribute. + // The reference to the source. This is the same as `source.sourceReference`. + // This is provided for backward compatibility since old clients do not + // understand the `source` attribute. integer sourceReference; }; @@ -1962,57 +2140,60 @@ DAP_DECLARE_STRUCT_TYPEINFO(SourceRequest); // A Stackframe contains the source location. struct StackFrame { - // Indicates whether this frame can be restarted with the 'restart' request. - // Clients should only use this if the debug adapter supports the 'restart' - // request (capability 'supportsRestartRequest' is true). + // Indicates whether this frame can be restarted with the `restart` request. + // Clients should only use this if the debug adapter supports the `restart` + // request and the corresponding capability `supportsRestartRequest` is true. optional canRestart; - // The column within the line. If source is null or doesn't exist, column is 0 - // and must be ignored. + // Start position of the range covered by the stack frame. It is measured in + // UTF-16 code units and the client capability `columnsStartAt1` determines + // whether it is 0- or 1-based. If attribute `source` is missing or doesn't + // exist, `column` is 0 and should be ignored by the client. integer column; - // An optional end column of the range covered by the stack frame. + // End position of the range covered by the stack frame. It is measured in + // UTF-16 code units and the client capability `columnsStartAt1` determines + // whether it is 0- or 1-based. optional endColumn; - // An optional end line of the range covered by the stack frame. + // The end line of the range covered by the stack frame. optional endLine; // An identifier for the stack frame. It must be unique across all threads. - // This id can be used to retrieve the scopes of the frame with the - // 'scopesRequest' or to restart the execution of a stackframe. + // This id can be used to retrieve the scopes of the frame with the `scopes` + // request or to restart the execution of a stackframe. integer id; - // Optional memory reference for the current instruction pointer in this - // frame. + // A memory reference for the current instruction pointer in this frame. optional instructionPointerReference; - // The line within the file of the frame. If source is null or doesn't exist, - // line is 0 and must be ignored. + // The line within the source of the frame. If the source attribute is missing + // or doesn't exist, `line` is 0 and should be ignored by the client. integer line; // The module associated with this frame, if any. optional> moduleId; // The name of the stack frame, typically a method name. string name; - // An optional hint for how to present this frame in the UI. - // A value of 'label' can be used to indicate that the frame is an artificial - // frame that is used as a visual label or separator. A value of 'subtle' can + // A hint for how to present this frame in the UI. + // A value of `label` can be used to indicate that the frame is an artificial + // frame that is used as a visual label or separator. A value of `subtle` can // be used to change the appearance of a frame in a 'subtle' way. // // Must be one of the following enumeration values: // 'normal', 'label', 'subtle' optional presentationHint; - // The optional source of the frame. + // The source of the frame. optional source; }; DAP_DECLARE_STRUCT_TYPEINFO(StackFrame); -// Response to 'stackTrace' request. +// Response to `stackTrace` request. struct StackTraceResponse : public Response { // The frames of the stackframe. If the array has length zero, there are no // stackframes available. This means that there is no location information // available. array stackFrames; // The total number of frames available in the stack. If omitted or if - // totalFrames is larger than the available frames, a client is expected to + // `totalFrames` is larger than the available frames, a client is expected to // request frames until a request returns less frames than requested (which // indicates the end of the stack). Returning monotonically increasing - // totalFrames values for subsequent requests can be used to enforce paging in - // the client. + // `totalFrames` values for subsequent requests can be used to enforce paging + // in the client. optional totalFrames; }; @@ -2041,20 +2222,20 @@ DAP_DECLARE_STRUCT_TYPEINFO(StackFrameFormat); // The request returns a stacktrace from the current execution state of a given // thread. A client can request all stack frames by omitting the startFrame and -// levels arguments. For performance conscious clients and if the debug -// adapter's 'supportsDelayedStackTraceLoading' capability is true, stack frames -// can be retrieved in a piecemeal way with the startFrame and levels arguments. -// The response of the stackTrace request may contain a totalFrames property +// levels arguments. For performance-conscious clients and if the corresponding +// capability `supportsDelayedStackTraceLoading` is true, stack frames can be +// retrieved in a piecemeal way with the `startFrame` and `levels` arguments. +// The response of the `stackTrace` request may contain a `totalFrames` property // that hints at the total number of frames in the stack. If a client needs this // total number upfront, it can issue a request for a single (first) frame and -// depending on the value of totalFrames decide how to proceed. In any case a -// client should be prepared to receive less frames than requested, which is an +// depending on the value of `totalFrames` decide how to proceed. In any case a +// client should be prepared to receive fewer frames than requested, which is an // indication that the end of the stack has been reached. struct StackTraceRequest : public Request { using Response = StackTraceResponse; // Specifies details on how to format the stack frames. - // The attribute is only honored by a debug adapter if the capability - // 'supportsValueFormattingOptions' is true. + // The attribute is only honored by a debug adapter if the corresponding + // capability `supportsValueFormattingOptions` is true. optional format; // The maximum number of frames to return. If levels is not specified or 0, // all frames are returned. @@ -2067,122 +2248,184 @@ struct StackTraceRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(StackTraceRequest); -// Response to 'stepBack' request. This is just an acknowledgement, so no body +// Response to `startDebugging` request. This is just an acknowledgement, so no +// body field is required. +struct StartDebuggingResponse : public Response {}; + +DAP_DECLARE_STRUCT_TYPEINFO(StartDebuggingResponse); + +// This request is sent from the debug adapter to the client to start a new +// debug session of the same type as the caller. This request should only be +// sent if the corresponding client capability `supportsStartDebuggingRequest` +// is true. A client implementation of `startDebugging` should start a new debug +// session (of the same type as the caller) in the same way that the caller's +// session was started. If the client supports hierarchical debug sessions, the +// newly created session can be treated as a child of the caller session. +struct StartDebuggingRequest : public Request { + using Response = StartDebuggingResponse; + // Arguments passed to the new debug session. The arguments must only contain + // properties understood by the `launch` or `attach` requests of the debug + // adapter and they must not contain any client-specific properties (e.g. + // `type`) or client-specific features (e.g. substitutable 'variables'). + object configuration; + // Indicates whether the new debug session should be started with a `launch` + // or `attach` request. + // + // Must be one of the following enumeration values: + // 'launch', 'attach' + string request = "launch"; +}; + +DAP_DECLARE_STRUCT_TYPEINFO(StartDebuggingRequest); + +// Response to `stepBack` request. This is just an acknowledgement, so no body // field is required. struct StepBackResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(StepBackResponse); -// The request starts the debuggee to run one step backwards. -// The debug adapter first sends the response and then a 'stopped' event (with -// reason 'step') after the step has completed. Clients should only call this -// request if the capability 'supportsStepBack' is true. +// The request executes one backward step (in the given granularity) for the +// specified thread and allows all other threads to run backward freely by +// resuming them. If the debug adapter supports single thread execution (see +// capability `supportsSingleThreadExecutionRequests`), setting the +// `singleThread` argument to true prevents other suspended threads from +// resuming. The debug adapter first sends the response and then a `stopped` +// event (with reason `step`) after the step has completed. Clients should only +// call this request if the corresponding capability `supportsStepBack` is true. struct StepBackRequest : public Request { using Response = StepBackResponse; - // Optional granularity to step. If no granularity is specified, a granularity - // of 'statement' is assumed. + // Stepping granularity to step. If no granularity is specified, a granularity + // of `statement` is assumed. optional granularity; - // Execute 'stepBack' for this thread. + // If this flag is true, all other suspended threads are not resumed. + optional singleThread; + // Specifies the thread for which to resume execution for one step backwards + // (of the given granularity). integer threadId; }; DAP_DECLARE_STRUCT_TYPEINFO(StepBackRequest); -// Response to 'stepIn' request. This is just an acknowledgement, so no body +// Response to `stepIn` request. This is just an acknowledgement, so no body // field is required. struct StepInResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(StepInResponse); -// The request starts the debuggee to step into a function/method if possible. -// If it cannot step into a target, 'stepIn' behaves like 'next'. -// The debug adapter first sends the response and then a 'stopped' event (with -// reason 'step') after the step has completed. If there are multiple -// function/method calls (or other targets) on the source line, the optional -// argument 'targetId' can be used to control into which target the 'stepIn' -// should occur. The list of possible targets for a given source line can be -// retrieved via the 'stepInTargets' request. +// The request resumes the given thread to step into a function/method and +// allows all other threads to run freely by resuming them. If the debug adapter +// supports single thread execution (see capability +// `supportsSingleThreadExecutionRequests`), setting the `singleThread` argument +// to true prevents other suspended threads from resuming. If the request cannot +// step into a target, `stepIn` behaves like the `next` request. The debug +// adapter first sends the response and then a `stopped` event (with reason +// `step`) after the step has completed. If there are multiple function/method +// calls (or other targets) on the source line, the argument `targetId` can be +// used to control into which target the `stepIn` should occur. The list of +// possible targets for a given source line can be retrieved via the +// `stepInTargets` request. struct StepInRequest : public Request { using Response = StepInResponse; - // Optional granularity to step. If no granularity is specified, a granularity - // of 'statement' is assumed. + // Stepping granularity. If no granularity is specified, a granularity of + // `statement` is assumed. optional granularity; - // Optional id of the target to step into. + // If this flag is true, all other suspended threads are not resumed. + optional singleThread; + // Id of the target to step into. optional targetId; - // Execute 'stepIn' for this thread. + // Specifies the thread for which to resume execution for one step-into (of + // the given granularity). integer threadId; }; DAP_DECLARE_STRUCT_TYPEINFO(StepInRequest); -// A StepInTarget can be used in the 'stepIn' request and determines into which -// single target the stepIn request should step. +// A `StepInTarget` can be used in the `stepIn` request and determines into +// which single target the `stepIn` request should step. struct StepInTarget { - // Unique identifier for a stepIn target. + // Start position of the range covered by the step in target. It is measured + // in UTF-16 code units and the client capability `columnsStartAt1` determines + // whether it is 0- or 1-based. + optional column; + // End position of the range covered by the step in target. It is measured in + // UTF-16 code units and the client capability `columnsStartAt1` determines + // whether it is 0- or 1-based. + optional endColumn; + // The end line of the range covered by the step-in target. + optional endLine; + // Unique identifier for a step-in target. integer id; - // The name of the stepIn target (shown in the UI). + // The name of the step-in target (shown in the UI). string label; + // The line of the step-in target. + optional line; }; DAP_DECLARE_STRUCT_TYPEINFO(StepInTarget); -// Response to 'stepInTargets' request. +// Response to `stepInTargets` request. struct StepInTargetsResponse : public Response { - // The possible stepIn targets of the specified source location. + // The possible step-in targets of the specified source location. array targets; }; DAP_DECLARE_STRUCT_TYPEINFO(StepInTargetsResponse); -// This request retrieves the possible stepIn targets for the specified stack -// frame. These targets can be used in the 'stepIn' request. The StepInTargets -// may only be called if the 'supportsStepInTargetsRequest' capability exists -// and is true. Clients should only call this request if the capability -// 'supportsStepInTargetsRequest' is true. +// This request retrieves the possible step-in targets for the specified stack +// frame. These targets can be used in the `stepIn` request. Clients should only +// call this request if the corresponding capability +// `supportsStepInTargetsRequest` is true. struct StepInTargetsRequest : public Request { using Response = StepInTargetsResponse; - // The stack frame for which to retrieve the possible stepIn targets. + // The stack frame for which to retrieve the possible step-in targets. integer frameId; }; DAP_DECLARE_STRUCT_TYPEINFO(StepInTargetsRequest); -// Response to 'stepOut' request. This is just an acknowledgement, so no body +// Response to `stepOut` request. This is just an acknowledgement, so no body // field is required. struct StepOutResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(StepOutResponse); -// The request starts the debuggee to run again for one step. -// The debug adapter first sends the response and then a 'stopped' event (with -// reason 'step') after the step has completed. +// The request resumes the given thread to step out (return) from a +// function/method and allows all other threads to run freely by resuming them. +// If the debug adapter supports single thread execution (see capability +// `supportsSingleThreadExecutionRequests`), setting the `singleThread` argument +// to true prevents other suspended threads from resuming. The debug adapter +// first sends the response and then a `stopped` event (with reason `step`) +// after the step has completed. struct StepOutRequest : public Request { using Response = StepOutResponse; - // Optional granularity to step. If no granularity is specified, a granularity - // of 'statement' is assumed. + // Stepping granularity. If no granularity is specified, a granularity of + // `statement` is assumed. optional granularity; - // Execute 'stepOut' for this thread. + // If this flag is true, all other suspended threads are not resumed. + optional singleThread; + // Specifies the thread for which to resume execution for one step-out (of the + // given granularity). integer threadId; }; DAP_DECLARE_STRUCT_TYPEINFO(StepOutRequest); // The event indicates that the execution of the debuggee has stopped due to -// some condition. This can be caused by a break point previously set, a -// stepping request has completed, by executing a debugger statement etc. +// some condition. This can be caused by a breakpoint previously set, a stepping +// request has completed, by executing a debugger statement etc. struct StoppedEvent : public Event { - // If 'allThreadsStopped' is true, a debug adapter can announce that all + // If `allThreadsStopped` is true, a debug adapter can announce that all // threads have stopped. // - The client should use this information to enable that all threads can be // expanded to access their stacktraces. // - If the attribute is missing or false, only the thread with the given - // threadId can be expanded. + // `threadId` can be expanded. optional allThreadsStopped; // The full reason for the event, e.g. 'Paused on exception'. This string is - // shown in the UI as is and must be translated. + // shown in the UI as is and can be translated. optional description; - // Ids of the breakpoints that triggered the event. In most cases there will - // be only a single breakpoint but here are some examples for multiple + // Ids of the breakpoints that triggered the event. In most cases there is + // only a single breakpoint but here are some examples for multiple // breakpoints: // - Different types of breakpoints map to the same location. // - Multiple source breakpoints get collapsed to the same instruction by the @@ -2190,18 +2433,18 @@ struct StoppedEvent : public Event { // - Multiple function breakpoints with different function names map to the // same location. optional> hitBreakpointIds; - // A value of true hints to the frontend that this event should not change the + // A value of true hints to the client that this event should not change the // focus. optional preserveFocusHint; // 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). + // `description` attribute is missing (but it must not be translated). // // May be one of the following enumeration values: // 'step', 'breakpoint', 'exception', 'pause', 'entry', 'goto', 'function // breakpoint', 'data breakpoint', 'instruction breakpoint' string reason; - // Additional information. E.g. if reason is 'exception', text contains the + // Additional information. E.g. if reason is `exception`, text contains the // exception name. This string is shown in the UI. optional text; // The thread which was stopped. @@ -2210,33 +2453,42 @@ struct StoppedEvent : public Event { DAP_DECLARE_STRUCT_TYPEINFO(StoppedEvent); -// Response to 'terminate' request. This is just an acknowledgement, so no body +// Response to `terminate` request. This is just an acknowledgement, so no body // field is required. struct TerminateResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(TerminateResponse); -// The 'terminate' request is sent from the client to the debug adapter in order -// to give the debuggee a chance for terminating itself. Clients should only -// call this request if the capability 'supportsTerminateRequest' is true. +// The `terminate` request is sent from the client to the debug adapter in order +// to shut down the debuggee gracefully. Clients should only call this request +// if the capability `supportsTerminateRequest` is true. Typically a debug +// adapter implements `terminate` by sending a software signal which the +// debuggee intercepts in order to clean things up properly before terminating +// itself. Please note that this request does not directly affect the state of +// the debug session: if the debuggee decides to veto the graceful shutdown for +// any reason by not terminating itself, then the debug session just continues. +// Clients can surface the `terminate` request as an explicit command or they +// can integrate it into a two stage Stop command that first sends `terminate` +// to request a graceful shutdown, and if that fails uses `disconnect` for a +// forceful shutdown. struct TerminateRequest : public Request { using Response = TerminateResponse; - // A value of true indicates that this 'terminate' request is part of a + // A value of true indicates that this `terminate` request is part of a // restart sequence. optional restart; }; DAP_DECLARE_STRUCT_TYPEINFO(TerminateRequest); -// Response to 'terminateThreads' request. This is just an acknowledgement, so -// no body field is required. +// Response to `terminateThreads` request. This is just an acknowledgement, no +// body field is required. struct TerminateThreadsResponse : public Response {}; DAP_DECLARE_STRUCT_TYPEINFO(TerminateThreadsResponse); // The request terminates the threads with the given ids. -// Clients should only call this request if the capability -// 'supportsTerminateThreadsRequest' is true. +// Clients should only call this request if the corresponding capability +// `supportsTerminateThreadsRequest` is true. struct TerminateThreadsRequest : public Request { using Response = TerminateThreadsResponse; // Ids of threads to be terminated. @@ -2248,10 +2500,10 @@ DAP_DECLARE_STRUCT_TYPEINFO(TerminateThreadsRequest); // The event indicates that debugging of the debuggee has terminated. This does // **not** mean that the debuggee itself has exited. struct TerminatedEvent : public Event { - // A debug adapter may set 'restart' to true (or to an arbitrary object) to - // request that the front end restarts the session. The value is not - // interpreted by the client and passed unmodified as an attribute '__restart' - // to the 'launch' and 'attach' requests. + // A debug adapter may set `restart` to true (or to an arbitrary object) to + // request that the client restarts the session. The value is not interpreted + // by the client and passed unmodified as an attribute `__restart` to the + // `launch` and `attach` requests. optional, boolean, integer, null, number, object, string>> restart; }; @@ -2275,13 +2527,13 @@ DAP_DECLARE_STRUCT_TYPEINFO(ThreadEvent); struct Thread { // Unique identifier for the thread. integer id; - // A name of the thread. + // The name of the thread. string name; }; DAP_DECLARE_STRUCT_TYPEINFO(Thread); -// Response to 'threads' request. +// Response to `threads` request. struct ThreadsResponse : public Response { // All threads. array threads; @@ -2297,53 +2549,56 @@ struct ThreadsRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(ThreadsRequest); // A Variable is a name/value pair. -// Optionally a variable can have a 'type' that is shown if space permits or -// when hovering over the variable's name. An optional 'kind' is used to render -// additional properties of the variable, e.g. different icons can be used to -// indicate that a variable is public or private. If the value is structured -// (has children), a handle is provided to retrieve the children with the -// VariablesRequest. If the number of named or indexed children is large, the -// numbers should be returned via the optional 'namedVariables' and -// 'indexedVariables' attributes. The client can use this optional information -// to present the children in a paged UI and fetch them in chunks. +// The `type` attribute is shown if space permits or when hovering over the +// variable's name. The `kind` attribute is used to render additional properties +// of the variable, e.g. different icons can be used to indicate that a variable +// is public or private. If the value is structured (has children), a handle is +// provided to retrieve the children with the `variables` request. If the number +// of named or indexed children is large, the numbers should be returned via the +// `namedVariables` and `indexedVariables` attributes. The client can use this +// information to present the children in a paged UI and fetch them in chunks. struct Variable { - // Optional evaluatable name of this variable which can be passed to the - // 'EvaluateRequest' to fetch the variable's value. + // The evaluatable name of this variable which can be passed to the `evaluate` + // request to fetch the variable's value. optional evaluateName; // The number of indexed child variables. - // The client can use this optional information to present the children in a - // paged UI and fetch them in chunks. + // The client can use this information to present the children in a paged UI + // and fetch them in chunks. optional indexedVariables; - // Optional memory reference for the variable if the variable represents - // executable code, such as a function pointer. This attribute is only - // required if the client has passed the value true for the - // 'supportsMemoryReferences' capability of the 'initialize' request. + // 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. optional memoryReference; // The variable's name. string name; // The number of named child variables. - // The client can use this optional information to present the children in a - // paged UI and fetch them in chunks. + // The client can use this information to present the children in a paged UI + // and fetch them in chunks. optional namedVariables; // Properties of a variable that can be used to determine how to render the // variable in the UI. optional presentationHint; // The type of the variable's value. Typically shown in the UI when hovering // over the value. This attribute should only be returned by a debug adapter - // if the client has passed the value true for the 'supportsVariableType' - // capability of the 'initialize' request. + // if the corresponding capability `supportsVariableType` is true. optional type; - // The variable's value. This can be a multi-line text, e.g. for a function - // the body of a function. + // The variable's value. + // This can be a multi-line text, e.g. for a function the body of a function. + // For structured variables (which do not have a simple value), it is + // recommended to provide a one-line representation of the structured object. + // This helps to identify the structured object in the collapsed state when + // its children are not yet visible. An empty string can be used if no value + // should be shown in the UI. string value; - // If variablesReference is > 0, the variable is structured and its children - // can be retrieved by passing variablesReference to the VariablesRequest. + // If `variablesReference` is > 0, the variable is structured and its children + // can be retrieved by passing `variablesReference` to the `variables` + // request. integer variablesReference; }; DAP_DECLARE_STRUCT_TYPEINFO(Variable); -// Response to 'variables' request. +// Response to `variables` request. struct VariablesResponse : public Response { // All (or a range) of variables for the given variable reference. array variables; @@ -2352,22 +2607,22 @@ struct VariablesResponse : public Response { DAP_DECLARE_STRUCT_TYPEINFO(VariablesResponse); // Retrieves all child variables for the given variable reference. -// An optional filter can be used to limit the fetched children to either named -// or indexed children. +// A filter can be used to limit the fetched children to either named or indexed +// children. struct VariablesRequest : public Request { using Response = VariablesResponse; // The number of variables to return. If count is missing or 0, all variables // are returned. optional count; - // Optional filter to limit the child variables to either named or indexed. If - // omitted, both types are fetched. + // Filter to limit the child variables to either named or indexed. If omitted, + // both types are fetched. // // Must be one of the following enumeration values: // 'indexed', 'named' optional filter; // Specifies details on how to format the Variable values. - // The attribute is only honored by a debug adapter if the capability - // 'supportsValueFormattingOptions' is true. + // The attribute is only honored by a debug adapter if the corresponding + // capability `supportsValueFormattingOptions` is true. optional format; // The index of the first variable to return; if omitted children start at 0. optional start; @@ -2377,6 +2632,42 @@ struct VariablesRequest : public Request { DAP_DECLARE_STRUCT_TYPEINFO(VariablesRequest); +// Response to `writeMemory` request. +struct WriteMemoryResponse : public Response { + // Property that should be returned when `allowPartial` is true to indicate + // the number of bytes starting from address that were successfully written. + optional bytesWritten; + // Property that should be returned when `allowPartial` is true to indicate + // the offset of the first byte of data successfully written. Can be negative. + optional offset; +}; + +DAP_DECLARE_STRUCT_TYPEINFO(WriteMemoryResponse); + +// Writes bytes to memory at the provided location. +// Clients should only call this request if the corresponding capability +// `supportsWriteMemoryRequest` is true. +struct WriteMemoryRequest : public Request { + using Response = WriteMemoryResponse; + // Property to control partial writes. If true, the debug adapter should + // attempt to write memory even if the entire memory region is not writable. + // In such a case the debug adapter should stop after hitting the first byte + // of memory that cannot be written and return the number of bytes written in + // the response via the `offset` and `bytesWritten` properties. If false or + // missing, a debug adapter should attempt to verify the region is writable + // before writing, and fail the response if it is not. + optional allowPartial; + // Bytes to write, encoded using base64. + string data; + // Memory reference to the base location to which data should be written. + string memoryReference; + // Offset (in bytes) to be applied to the reference location before writing + // data. Can be negative. + optional offset; +}; + +DAP_DECLARE_STRUCT_TYPEINFO(WriteMemoryRequest); + } // namespace dap #endif // dap_protocol_h diff --git a/src/protocol_events.cpp b/src/protocol_events.cpp index 1fbcb3e..4ad1a85 100644 --- a/src/protocol_events.cpp +++ b/src/protocol_events.cpp @@ -15,7 +15,7 @@ // Generated with protocol_gen.go -- do not edit this file. // go run scripts/protocol_gen/protocol_gen.go // -// DAP version 1.46.0 +// DAP version 1.58.0 #include "dap/protocol.h" @@ -53,6 +53,12 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(LoadedSourceEvent, DAP_FIELD(reason, "reason"), DAP_FIELD(source, "source")); +DAP_IMPLEMENT_STRUCT_TYPEINFO(MemoryEvent, + "memory", + DAP_FIELD(count, "count"), + DAP_FIELD(memoryReference, "memoryReference"), + DAP_FIELD(offset, "offset")); + DAP_IMPLEMENT_STRUCT_TYPEINFO(ModuleEvent, "module", DAP_FIELD(module, "module"), diff --git a/src/protocol_requests.cpp b/src/protocol_requests.cpp index dc3e10a..0517223 100644 --- a/src/protocol_requests.cpp +++ b/src/protocol_requests.cpp @@ -15,7 +15,7 @@ // Generated with protocol_gen.go -- do not edit this file. // go run scripts/protocol_gen/protocol_gen.go // -// DAP version 1.46.0 +// DAP version 1.58.0 #include "dap/protocol.h" @@ -49,6 +49,7 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(ConfigurationDoneRequest, "configurationDone"); DAP_IMPLEMENT_STRUCT_TYPEINFO(ContinueRequest, "continue", + DAP_FIELD(singleThread, "singleThread"), DAP_FIELD(threadId, "threadId")); DAP_IMPLEMENT_STRUCT_TYPEINFO(DataBreakpointInfoRequest, @@ -68,6 +69,7 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(DisassembleRequest, DAP_IMPLEMENT_STRUCT_TYPEINFO(DisconnectRequest, "disconnect", DAP_FIELD(restart, "restart"), + DAP_FIELD(suspendDebuggee, "suspendDebuggee"), DAP_FIELD(terminateDebuggee, "terminateDebuggee")); @@ -103,10 +105,14 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO( DAP_FIELD(linesStartAt1, "linesStartAt1"), DAP_FIELD(locale, "locale"), DAP_FIELD(pathFormat, "pathFormat"), + DAP_FIELD(supportsArgsCanBeInterpretedByShell, + "supportsArgsCanBeInterpretedByShell"), DAP_FIELD(supportsInvalidatedEvent, "supportsInvalidatedEvent"), + DAP_FIELD(supportsMemoryEvent, "supportsMemoryEvent"), DAP_FIELD(supportsMemoryReferences, "supportsMemoryReferences"), DAP_FIELD(supportsProgressReporting, "supportsProgressReporting"), DAP_FIELD(supportsRunInTerminalRequest, "supportsRunInTerminalRequest"), + DAP_FIELD(supportsStartDebuggingRequest, "supportsStartDebuggingRequest"), DAP_FIELD(supportsVariablePaging, "supportsVariablePaging"), DAP_FIELD(supportsVariableType, "supportsVariableType")); @@ -125,6 +131,7 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(ModulesRequest, DAP_IMPLEMENT_STRUCT_TYPEINFO(NextRequest, "next", DAP_FIELD(granularity, "granularity"), + DAP_FIELD(singleThread, "singleThread"), DAP_FIELD(threadId, "threadId")); DAP_IMPLEMENT_STRUCT_TYPEINFO(PauseRequest, @@ -141,15 +148,20 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(RestartFrameRequest, "restartFrame", DAP_FIELD(frameId, "frameId")); -DAP_IMPLEMENT_STRUCT_TYPEINFO(RestartRequest, "restart"); +DAP_IMPLEMENT_STRUCT_TYPEINFO(RestartRequest, + "restart", + DAP_FIELD(arguments, "arguments")); DAP_IMPLEMENT_STRUCT_TYPEINFO(ReverseContinueRequest, "reverseContinue", + DAP_FIELD(singleThread, "singleThread"), DAP_FIELD(threadId, "threadId")); DAP_IMPLEMENT_STRUCT_TYPEINFO(RunInTerminalRequest, "runInTerminal", DAP_FIELD(args, "args"), + DAP_FIELD(argsCanBeInterpretedByShell, + "argsCanBeInterpretedByShell"), DAP_FIELD(cwd, "cwd"), DAP_FIELD(env, "env"), DAP_FIELD(kind, "kind"), @@ -211,14 +223,21 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(StackTraceRequest, DAP_FIELD(startFrame, "startFrame"), DAP_FIELD(threadId, "threadId")); +DAP_IMPLEMENT_STRUCT_TYPEINFO(StartDebuggingRequest, + "startDebugging", + DAP_FIELD(configuration, "configuration"), + DAP_FIELD(request, "request")); + DAP_IMPLEMENT_STRUCT_TYPEINFO(StepBackRequest, "stepBack", DAP_FIELD(granularity, "granularity"), + DAP_FIELD(singleThread, "singleThread"), DAP_FIELD(threadId, "threadId")); DAP_IMPLEMENT_STRUCT_TYPEINFO(StepInRequest, "stepIn", DAP_FIELD(granularity, "granularity"), + DAP_FIELD(singleThread, "singleThread"), DAP_FIELD(targetId, "targetId"), DAP_FIELD(threadId, "threadId")); @@ -229,6 +248,7 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(StepInTargetsRequest, DAP_IMPLEMENT_STRUCT_TYPEINFO(StepOutRequest, "stepOut", DAP_FIELD(granularity, "granularity"), + DAP_FIELD(singleThread, "singleThread"), DAP_FIELD(threadId, "threadId")); DAP_IMPLEMENT_STRUCT_TYPEINFO(TerminateRequest, @@ -250,4 +270,11 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(VariablesRequest, DAP_FIELD(variablesReference, "variablesReference")); +DAP_IMPLEMENT_STRUCT_TYPEINFO(WriteMemoryRequest, + "writeMemory", + DAP_FIELD(allowPartial, "allowPartial"), + DAP_FIELD(data, "data"), + DAP_FIELD(memoryReference, "memoryReference"), + DAP_FIELD(offset, "offset")); + } // namespace dap diff --git a/src/protocol_response.cpp b/src/protocol_response.cpp index 038c69d..79816a7 100644 --- a/src/protocol_response.cpp +++ b/src/protocol_response.cpp @@ -15,7 +15,7 @@ // Generated with protocol_gen.go -- do not edit this file. // go run scripts/protocol_gen/protocol_gen.go // -// DAP version 1.46.0 +// DAP version 1.58.0 #include "dap/protocol.h" @@ -85,6 +85,7 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO( DAP_FIELD(additionalModuleColumns, "additionalModuleColumns"), DAP_FIELD(completionTriggerCharacters, "completionTriggerCharacters"), DAP_FIELD(exceptionBreakpointFilters, "exceptionBreakpointFilters"), + DAP_FIELD(supportSuspendDebuggee, "supportSuspendDebuggee"), DAP_FIELD(supportTerminateDebuggee, "supportTerminateDebuggee"), DAP_FIELD(supportedChecksumAlgorithms, "supportedChecksumAlgorithms"), DAP_FIELD(supportsBreakpointLocationsRequest, @@ -116,14 +117,16 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO( DAP_FIELD(supportsRestartRequest, "supportsRestartRequest"), DAP_FIELD(supportsSetExpression, "supportsSetExpression"), DAP_FIELD(supportsSetVariable, "supportsSetVariable"), + DAP_FIELD(supportsSingleThreadExecutionRequests, + "supportsSingleThreadExecutionRequests"), DAP_FIELD(supportsStepBack, "supportsStepBack"), DAP_FIELD(supportsStepInTargetsRequest, "supportsStepInTargetsRequest"), DAP_FIELD(supportsSteppingGranularity, "supportsSteppingGranularity"), DAP_FIELD(supportsTerminateRequest, "supportsTerminateRequest"), DAP_FIELD(supportsTerminateThreadsRequest, "supportsTerminateThreadsRequest"), - DAP_FIELD(supportsValueFormattingOptions, - "supportsValueFormattingOptions")); + DAP_FIELD(supportsValueFormattingOptions, "supportsValueFormattingOptions"), + DAP_FIELD(supportsWriteMemoryRequest, "supportsWriteMemoryRequest")); DAP_IMPLEMENT_STRUCT_TYPEINFO(LaunchResponse, ""); @@ -167,7 +170,9 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(SetDataBreakpointsResponse, "", DAP_FIELD(breakpoints, "breakpoints")); -DAP_IMPLEMENT_STRUCT_TYPEINFO(SetExceptionBreakpointsResponse, ""); +DAP_IMPLEMENT_STRUCT_TYPEINFO(SetExceptionBreakpointsResponse, + "", + DAP_FIELD(breakpoints, "breakpoints")); DAP_IMPLEMENT_STRUCT_TYPEINFO(SetExpressionResponse, "", @@ -206,6 +211,8 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(StackTraceResponse, DAP_FIELD(stackFrames, "stackFrames"), DAP_FIELD(totalFrames, "totalFrames")); +DAP_IMPLEMENT_STRUCT_TYPEINFO(StartDebuggingResponse, ""); + DAP_IMPLEMENT_STRUCT_TYPEINFO(StepBackResponse, ""); DAP_IMPLEMENT_STRUCT_TYPEINFO(StepInResponse, ""); @@ -228,4 +235,9 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(VariablesResponse, "", DAP_FIELD(variables, "variables")); +DAP_IMPLEMENT_STRUCT_TYPEINFO(WriteMemoryResponse, + "", + DAP_FIELD(bytesWritten, "bytesWritten"), + DAP_FIELD(offset, "offset")); + } // namespace dap diff --git a/src/protocol_types.cpp b/src/protocol_types.cpp index 2adaf97..cc1126c 100644 --- a/src/protocol_types.cpp +++ b/src/protocol_types.cpp @@ -15,7 +15,7 @@ // Generated with protocol_gen.go -- do not edit this file. // go run scripts/protocol_gen/protocol_gen.go // -// DAP version 1.46.0 +// DAP version 1.58.0 #include "dap/protocol.h" @@ -83,6 +83,7 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO( DAP_FIELD(additionalModuleColumns, "additionalModuleColumns"), DAP_FIELD(completionTriggerCharacters, "completionTriggerCharacters"), DAP_FIELD(exceptionBreakpointFilters, "exceptionBreakpointFilters"), + DAP_FIELD(supportSuspendDebuggee, "supportSuspendDebuggee"), DAP_FIELD(supportTerminateDebuggee, "supportTerminateDebuggee"), DAP_FIELD(supportedChecksumAlgorithms, "supportedChecksumAlgorithms"), DAP_FIELD(supportsBreakpointLocationsRequest, @@ -114,17 +115,20 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO( DAP_FIELD(supportsRestartRequest, "supportsRestartRequest"), DAP_FIELD(supportsSetExpression, "supportsSetExpression"), DAP_FIELD(supportsSetVariable, "supportsSetVariable"), + DAP_FIELD(supportsSingleThreadExecutionRequests, + "supportsSingleThreadExecutionRequests"), DAP_FIELD(supportsStepBack, "supportsStepBack"), DAP_FIELD(supportsStepInTargetsRequest, "supportsStepInTargetsRequest"), DAP_FIELD(supportsSteppingGranularity, "supportsSteppingGranularity"), DAP_FIELD(supportsTerminateRequest, "supportsTerminateRequest"), DAP_FIELD(supportsTerminateThreadsRequest, "supportsTerminateThreadsRequest"), - DAP_FIELD(supportsValueFormattingOptions, - "supportsValueFormattingOptions")); + DAP_FIELD(supportsValueFormattingOptions, "supportsValueFormattingOptions"), + DAP_FIELD(supportsWriteMemoryRequest, "supportsWriteMemoryRequest")); DAP_IMPLEMENT_STRUCT_TYPEINFO(CompletionItem, "", + DAP_FIELD(detail, "detail"), DAP_FIELD(label, "label"), DAP_FIELD(length, "length"), DAP_FIELD(selectionLength, "selectionLength"), @@ -160,6 +164,7 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(VariablePresentationHint, "", DAP_FIELD(attributes, "attributes"), DAP_FIELD(kind, "kind"), + DAP_FIELD(lazy, "lazy"), DAP_FIELD(visibility, "visibility")); DAP_IMPLEMENT_STRUCT_TYPEINFO(ValueFormat, "", DAP_FIELD(hex, "hex")); @@ -197,6 +202,15 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(Module, DAP_FIELD(symbolStatus, "symbolStatus"), DAP_FIELD(version, "version")); +DAP_IMPLEMENT_STRUCT_TYPEINFO(LaunchRequestArguments, + "", + DAP_FIELD(restart, "__restart"), + DAP_FIELD(noDebug, "noDebug")); + +DAP_IMPLEMENT_STRUCT_TYPEINFO(AttachRequestArguments, + "", + DAP_FIELD(restart, "__restart")); + DAP_IMPLEMENT_STRUCT_TYPEINFO(Scope, "", DAP_FIELD(column, "column"), @@ -283,8 +297,12 @@ DAP_IMPLEMENT_STRUCT_TYPEINFO(StackFrameFormat, DAP_IMPLEMENT_STRUCT_TYPEINFO(StepInTarget, "", + DAP_FIELD(column, "column"), + DAP_FIELD(endColumn, "endColumn"), + DAP_FIELD(endLine, "endLine"), DAP_FIELD(id, "id"), - DAP_FIELD(label, "label")); + DAP_FIELD(label, "label"), + DAP_FIELD(line, "line")); DAP_IMPLEMENT_STRUCT_TYPEINFO(Thread, "", diff --git a/tools/protocol_gen/protocol_gen.go b/tools/protocol_gen/protocol_gen.go index 624a76b..c32e56b 100644 --- a/tools/protocol_gen/protocol_gen.go +++ b/tools/protocol_gen/protocol_gen.go @@ -152,6 +152,7 @@ type definition struct { Description string `json:"description"` Properties properties `json:"properties"` Required []string `json:"required"` + OneOf []*definition `json:"oneOf"` AllOf []*definition `json:"allOf"` Ref string `json:"$ref"` OpenEnum []string `json:"_enum"` @@ -486,6 +487,28 @@ func (r *root) getType(def *definition) (builtType cppType, err error) { return ref.def.cppType, nil } + if len(def.OneOf) != 0 { + args := []string{} + deps := []cppType{} + for i := 0; i < len(def.OneOf); i++ { + if def.OneOf[i] == nil { + return nil, fmt.Errorf("Item %d in oneOf is nil", i) + } + + elTy, err := r.getType(def.OneOf[i]) + if err != nil { + return nil, err + } + deps = append(deps, elTy) + args = append(args, elTy.Name()) + } + return &cppBasicType{ + name: "variant<" + strings.Join(args, ", ") + ">", + desc: def.Description, + deps: deps, + }, nil + } + v := reflect.ValueOf(def.Ty) if v.Kind() == reflect.Interface {