@@ -7,30 +7,49 @@ declare module 'vscode' {
7
7
8
8
// https://github.com/microsoft/vscode/issues/145234
9
9
10
- // TODO: Add missing docs
11
- // TODO: Review and polish up all docs
10
+ /**
11
+ * A command that was executed in a terminal.
12
+ */
12
13
export interface TerminalShellExecution {
13
14
/**
14
- * The full command line that was executed, including both the command and arguments. The
15
- * {@link TerminalShellExecutionCommandLineConfidence confidence} of this value depends on
16
- * the specific shell's shell integration implementation. This value may become more
17
- * accurate after {@link onDidEndTerminalShellExecution} is fired.
15
+ * The command line that was executed. The {@link TerminalShellExecutionCommandLineConfidence confidence}
16
+ * of this value depends on the specific shell's shell integration implementation. This
17
+ * value may become more accurate after {@link window.onDidEndTerminalShellExecution} is
18
+ * fired.
19
+ *
20
+ * @example
21
+ * // Log the details of the command line on start and end
22
+ * window.onDidStartTerminalShellExecution(event => {
23
+ * const commandLine = event.execution.commandLine;
24
+ * console.log(`Command started\n${summarizeCommandLine(commandLine)}`);
25
+ * });
26
+ * window.onDidEndTerminalShellExecution(event => {
27
+ * const commandLine = event.execution.commandLine;
28
+ * console.log(`Command ended\n${summarizeCommandLine(commandLine)}`);
29
+ * });
30
+ * function summarizeCommandLine(commandLine: TerminalShellExecutionCommandLine) {
31
+ * return [
32
+ * ` Command line: ${command.ommandLine.value}`,
33
+ * ` Confidence: ${command.ommandLine.confidence}`,
34
+ * ` Trusted: ${command.ommandLine.isTrusted}
35
+ * ].join('\n');
36
+ * }
18
37
*/
19
38
readonly commandLine : TerminalShellExecutionCommandLine ;
20
39
21
40
/**
22
41
* The working directory that was reported by the shell when this command executed. This
23
- * will be a {@link Uri} if the path reported by the shell can reliably be mapped to the
24
- * connected machine. This requires the shell integration to support working directory
25
- * reporting.
42
+ * {@link Uri} may represent a file on another machine (eg. ssh into another machine). This
43
+ * requires the shell integration to support working directory reporting.
26
44
*/
27
45
readonly cwd : Uri | undefined ;
28
46
29
47
/**
30
48
* Creates a stream of raw data (including escape sequences) that is written to the
31
- * terminal. This will only include data that was written after `stream` was called for the
32
- * first time, ie. you must call `dataStream` immediately after the command is executed via
33
- * {@link executeCommand} or {@link onDidStartTerminalShellExecution} to not miss any data.
49
+ * terminal. This will only include data that was written after `readData` was called for
50
+ * the first time, ie. you must call `readData` immediately after the command is executed
51
+ * via {@link TerminalShellIntegration.executeCommand} or
52
+ * {@link window.onDidStartTerminalShellExecution} to not miss any data.
34
53
*
35
54
* @example
36
55
* // Log all data written to the terminal for a command
@@ -50,24 +69,25 @@ declare module 'vscode' {
50
69
/**
51
70
* The full command line that was executed, including both the command and its arguments.
52
71
*/
53
- value : string ;
72
+ readonly value : string ;
54
73
55
74
/**
56
75
* Whether the command line value came from a trusted source and is therefore safe to
57
76
* execute without user additional confirmation, such as a notification that asks "Do you
58
- * want to execute (command)?".
77
+ * want to execute (command)?". This verification is likely only needed if you are going to
78
+ * execute the command again.
59
79
*
60
- * This is false when the command line was reported explicitly by the shell integration
61
- * script (ie. {@link TerminalShellExecutionCommandLineConfidence.High high confidence}),
62
- * but did not include a nonce for verification.
80
+ * This is `true` only when the command line was reported explicitly by the shell
81
+ * integration script (ie. {@link TerminalShellExecutionCommandLineConfidence.High high confidence})
82
+ * and it used a nonce for verification.
63
83
*/
64
- isTrusted : boolean ;
84
+ readonly isTrusted : boolean ;
65
85
66
86
/**
67
87
* The confidence of the command line value which is determined by how the value was
68
88
* obtained. This depends upon the implementation of the shell integration script.
69
89
*/
70
- confidence : TerminalShellExecutionCommandLineConfidence ;
90
+ readonly confidence : TerminalShellExecutionCommandLineConfidence ;
71
91
}
72
92
73
93
/**
@@ -95,15 +115,16 @@ declare module 'vscode' {
95
115
96
116
/**
97
117
* The command line value confidence is high. This means that the value was explicitly sent
98
- * from the shell integration script.
118
+ * from the shell integration script or the command was executed via the
119
+ * {@link TerminalShellIntegration.executeCommand} API.
99
120
*/
100
121
High = 2
101
122
}
102
123
103
124
export interface Terminal {
104
125
/**
105
126
* An object that contains [shell integration](https://code.visualstudio.com/docs/terminal/shell-integration)-powered
106
- * features for the terminal. This will always be undefined immediately after the terminal
127
+ * features for the terminal. This will always be ` undefined` immediately after the terminal
107
128
* is created. Listen to {@link window.onDidActivateTerminalShellIntegration} to be notified
108
129
* when shell integration is activated for a terminal.
109
130
*
@@ -114,10 +135,14 @@ declare module 'vscode' {
114
135
readonly shellIntegration : TerminalShellIntegration | undefined ;
115
136
}
116
137
138
+ /**
139
+ * [Shell integration](https://code.visualstudio.com/docs/terminal/shell-integration)-powered capabilities owned by a terminal.
140
+ */
117
141
export interface TerminalShellIntegration {
118
142
/**
119
- * The current working directory of the terminal. This will be a {@link Uri} if the path
120
- * reported by the shell can reliably be mapped to the connected machine.
143
+ * The current working directory of the terminal. This {@link Uri} may represent a file on
144
+ * another machine (eg. ssh into another machine). This requires the shell integration to
145
+ * support working directory reporting.
121
146
*/
122
147
readonly cwd : Uri | undefined ;
123
148
0 commit comments