This repository has been archived by the owner on Nov 13, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 28
/
ICommandDefinition.ts
212 lines (208 loc) · 8.07 KB
/
ICommandDefinition.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
/*
* This program and the accompanying materials are made available under the terms of the
* Eclipse Public License v2.0 which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-v20.html
*
* SPDX-License-Identifier: EPL-2.0
*
* Copyright Contributors to the Zowe Project.
*
*/
import { ICommandExampleDefinition } from "./ICommandExampleDefinition";
import { IChainedHandlerEntry } from "./handler/IChainedHandlerEntry";
import { ICommandOptionDefinition } from "./option/ICommandOptionDefinition";
import { ICommandPositionalDefinition } from "./option/ICommandPositionalDefinition";
import { ICommandDefinitionPassOn } from "./ICommandDefinitionPassOn";
import { ICommandProfile } from "../../src/doc/profiles/definition/ICommandProfile";
/**
* Command Segment type - either "group" or "command".
*
* "group" implies no handler and should have children. Use groups to logically arrange portions of your CLI.
* "command" implies there is a handler and may or may not have children.
*/
export type ICommandNodeType = "group" | "command";
export const compareCommands = (a: ICommandDefinition, b: ICommandDefinition) => {
return a.name.localeCompare(b.name);
};
/**
* Interface describing the syntax and behavior definition of a command
* or group of commands
*/
export interface ICommandDefinition {
/**
* The command or group name
* @type {string}
* @memberof ICommandDefinition
*/
name: string;
/**
* The description - keep group descriptions "small" and include lengthier descriptions for "commands".
* @type {string}
* @memberof ICommandDefinition
*/
description: string;
/**
* A shorter (~one line) description of your command
* @type {string}
* @memberof ICommandDefinition
*/
summary?: string;
/**
* This documents segment type - either "group" or "command". See the type definition for more detail.
* @type {ICommandNodeType}
* @memberof ICommandDefinition
*/
type: ICommandNodeType;
/**
* Pass on attributes of the current definition node to children
* @type {ICommandDefinitionPassOn[]}
* @memberof ICommandDefinition
*/
passOn?: ICommandDefinitionPassOn[];
/**
* Aliases - any number of single or more character aliases can be specified.
* @type {string[]}
* @memberof ICommandDefinition
*/
aliases?: string[];
/**
* If true, stdin will automatically be read before the handler of this command is invoked.
* @type {string[]}
* @memberof ICommandDefinition
*/
enableStdin?: boolean;
/**
* The description for the stdin option - used if enableStdin is true
* @type {string}
* @memberof ICommandDefinition
*/
stdinOptionDescription?: string;
/**
* If this property exists, the command is deprecated. The property value
* is a string that identifies the replacement command. It is used in a
* deprecation message similar to the following:
* This command is deprecated.
* Recommended replacement: value_of_deprecatedReplacement_goes_here
*
* @type {string}
* @memberof ICommandDefinition
*/
deprecatedReplacement?: string;
/**
* The set of examples displayed in the help for this command.
* @type {ICommandExampleDefinition[]}
* @memberof ICommandDefinition
*/
examples?: ICommandExampleDefinition[];
/**
* The handler for this command - this is a string literal that is used on the "require" statement to load the
* command handler - The handler itself must implement ICommandHandler. A string is used over an actual
* instance because we do not want the handler (and its required dependencies) to be loaded before it is issued.
* @type {string}
* @memberof ICommandDefinition
*/
handler?: string;
/**
* Build this command from multiple handlers chained together, remapping the response
* to arguments for future handlers in the command.
*
* Limitations of chained handlers include:
* - The syntax of the command for each handler is not validated, since the full definition is not provided
* - You can only map arguments from the "data" field of the command response, so whatever you need
* to pass to a future handler in the chain must be passed to response.data.setObj
* @type {IChainedHandlerEntry[]}
* @memberof ICommandDefinition
*/
chainedHandlers?: IChainedHandlerEntry[];
/**
* The Children for this command - used when the type is provider or group. Use the children to build complex
* nested syntaxes - however bright modules must follow the prescribed command syntax structure for Brightside.
* @type {ICommandDefinition[]}
* @memberof ICommandDefinition
*/
children?: ICommandDefinition[];
/**
* The options to be exposed on the command.
* @type {ICommandOptionDefinition[]}
* @memberof ICommandDefinition
*/
options?: ICommandOptionDefinition[];
/**
* The positional arguments to be exposed on the command.
* @type {ICommandPositionalDefinition[]}
* @memberof ICommandDefinition
*/
positionals?: ICommandPositionalDefinition[];
/**
* Must specify one indicates that you must specify one of the options listed.
* @type {string[]}
* @memberof ICommandDefinition
*/
mustSpecifyOne?: string[];
/**
* Only one of the listed options can be specified
* @type {string[]}
* @memberof ICommandDefinition
*/
onlyOneOf?: string[];
/**
* Auto-loading of profile specifications - see the interface definition for more details.
* @type {ICommandProfile}
* @memberof ICommandDefinition
*/
profile?: ICommandProfile;
/**
* The command handlers are passed the definition document for the command. You can place any additional
* "custom" definition information here.
* @type {any}
* @memberof ICommandDefinition
*/
customize?: any;
/**
* Is this command experimental? If you set this to true, the command will
* be marked with help text indicating that it is experimental. If this command
* is of type "group" all descendant commands will be marked experimental
* as well.
* @type {boolean}
* @memberof ICommandDefinition
*/
experimental?: boolean;
/**
* Enable output format options (e.g. "--response-format-type"). The output format options are applied to data
* that is presented to the handler response format APIs (see IHandlerResponseApi, "format" property). The intent
* of of the output format options:
*
* 1) Simplify the code in a command handler. A "common" use-case for handler output is printing tables (or lists)
* of JSON objects/data OR a single JSON response object.
*
* 2) Passing the data described in (1) to the handler response format API and enabling the format options gives
* the user full control over the output format. They can choose to output an array of JSON objects as a table
* OR a list of prettified objects. The use can also choose to include table headers and filter fields. The user
* can also reduce the output of a table to a single column (or a JSON object to a single property) eliminating
* the need to manually code options such as "--only-print-this-one-field"
*
* See the "ICommandOutputFormat" JSDoc for details on the format types.
*
* The options enabled:
*
* --response-format-type [table|list|object|string]
*
* Allows the user to control the output format of the data. See the "ICommandOutputFormat" interface for details.
*
* --response-format-filter [array of fields]
*
* Allows the user to include only the fields specified in the filter array.
*
* --response-format-header [boolean]
*
* Allows the user to optionally include the header with a table.
*
* @type {boolean}
* @memberof ICommandDefinition
*/
outputFormatOptions?: boolean;
/**
* Index signature
*/
[key: string]: any;
}