Command Registration

定义命令注册是介绍命令及其选项和参数结构的第一步。这与后来发生的事情(例如解析命令行输入和运行实际目标代码)大体无关。从本质上来说,这是向用户展示的命令 API 的定义。

Defining a command registration is a first step to introducing the structure of a command and its options and parameters. This is loosely decoupled from what happens later, such as parsing command-line input and running actual target code. Essentially, it is the definition of a command API that is shown to a user.

Commands

spring-shell 结构中的命令被定义为一个命令数组。这产生了一个类似于以下示例的结构:

A command in a spring-shell structure is defined as an array of commands. This yields a structure similar to the following example:

command1 sub1
command2 sub1 subsub1
command2 sub2 subsub1
command2 sub2 subsub2

目前如定义子命令,我们不支持对显式父项映射命令。例如,command1 sub1command1 sub1 subsub1 不能同时注册。

We do not currently support mapping commands to an explicit parent if sub-commands are defined. For example, command1 sub1 and command1 sub1 subsub1 cannot both be registered.

Interaction Mode

Spring Shell 被设计为以两种模式工作:交互式(其本质上是 REPL,其中你有 shell 实例贯穿于一系列命令)和非交互式(其中命令从命令行逐个执行)。

Spring Shell has been designed to work on two modes: interactive (which essentially is a REPL where you have an active shell instance throughout a series of commands) and non-interactive (where commands are executed one by one from a command line).

这些模式之间的差异主要围绕在每种模式下可以执行的操作的限制。例如,如果 shell 不再处于活动状态,显示命令的先前堆栈跟踪将不可行。通常,shell 是否仍处于活动状态决定了哪些信息可用。

Differentation between these modes is mostly around limitations about what can be done in each mode. For example, it would not be feasible to show what was a previous stacktrace of a command if the shell is no longer active. Generally, whether the shell is still active dictates the available information.

此外,处于活动 REPL 会话中可能会提供有关用户在活动会话中已经做了 чего 的更多信息。

Also, being on an active REPL session may provide more information about what the user has been doing within an active session.

Options

选项可以定义为长选项和短选项,其前缀分别为 ---。以下示例显示长选项和短选项:

Options can be defined as long and short, where the prefixing is -- and -, respectively. The following examples show long and short options:

Unresolved include directive in modules/ROOT/pages/appendices/techintro/registration.adoc - include::../../../../../src/test/java/org/springframework/shell/docs/CommandRegistrationSnippets.java[]
Unresolved include directive in modules/ROOT/pages/appendices/techintro/registration.adoc - include::../../../../../src/test/java/org/springframework/shell/docs/CommandRegistrationSnippets.java[]

Target

目标定义命令的执行目标。它可以是 POJO 中的方法、 ConsumerFunction

The target defines the execution target of a command. It can be a method in a POJO, a Consumer, or a Function.

Method

在现有 POJO 中使用 Method 是定义目标的一种方法。考虑以下类:

Using a Method in an existing POJO is one way to define a target. Consider the following class:

Unresolved include directive in modules/ROOT/pages/appendices/techintro/registration.adoc - include::../../../../../src/test/java/org/springframework/shell/docs/CommandTargetSnippets.java[]

考虑到前面清单中显示的现有类,然后你可以注册其方法:

Given the existing class shown in the preceding listing, you can then register its method:

Unresolved include directive in modules/ROOT/pages/appendices/techintro/registration.adoc - include::../../../../../src/test/java/org/springframework/shell/docs/CommandTargetSnippets.java[]

Function

使用 Function 作为目标提供了很大的灵活性来处理命令执行中的内容,因为你可以使用给定 FunctionCommandContext 手动处理很多事情。然后, Function 的返回类型将作为结果打印到 shell 中。考虑以下示例:

Using a Function as a target gives a lot of flexibility to handle what happens in a command execution, because you can handle many things manually by using a CommandContext given to a Function. The return type from a Function is then what gets printed into the shell as a result. Consider the following example:

Unresolved include directive in modules/ROOT/pages/appendices/techintro/registration.adoc - include::../../../../../src/test/java/org/springframework/shell/docs/CommandTargetSnippets.java[]

Consumer

使用 Consumer 基本上与使用 Function 相同,区别在于没有返回类型。如果你需要将某内容打印到 shell 中,你可以从上下文获取 Terminal 的引用并通过它打印某内容。考虑以下示例:

Using a Consumer is basically the same as using a Function, with the difference being that there is no return type. If you need to print something into a shell, you can get a reference to a Terminal from a context and print something through it. Consider the following example:

Unresolved include directive in modules/ROOT/pages/appendices/techintro/registration.adoc - include::../../../../../src/test/java/org/springframework/shell/docs/CommandTargetSnippets.java[]