Docs about shell runners

- Relates #558

Author: jvalkeal

spring-shell-docs/src/main/asciidoc/using-shell-commands-interactionmode.adoc

@@ -0,0 +1,24 @@
+[[commands-interactionmode]]
+=== Interaction Mode
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+Command registration can define `InteractionMode` which is used to hide commands
+depending which mode shell is executing. More about that in <<using-shell-execution-interactionmode>>.
+
+You can define it with `CommandRegisration`.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationInteractionModeSnippets.java[tag=snippet1]
+----
+====
+
+Or with `@ShellMethod`.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationInteractionModeSnippets.java[tag=snippet2]
+----
+====

spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc

@@ -14,3 +14,5 @@ include::using-shell-commands-availability.adoc[]
 include::using-shell-commands-exceptionhandling.adoc[]
 
 include::using-shell-commands-hidden.adoc[]
+
+include::using-shell-commands-interactionmode.adoc[]

spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc

@@ -1,7 +1,10 @@
+[[using-shell-execution]]
 == Execution
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 This section describes how to set up a Spring Shell to work in interactive mode.
 
+[[using-shell-execution-interactionmode]]
 === Interaction Mode
 
 Version 2.1.x introduced built-in support to distinguish between interactive
@@ -18,3 +21,15 @@ have no meaning in non-interactive mode, because it is used to exit interactive
 
 The `@ShellMethod` annotation has a field called `interactionMode` that you can use to inform
 shell about when a particular command is available.
+
+[[using-shell-execution-shellrunner]]
+=== Shell Runners
+
+`ShellApplicationRunner` is a main interface where Boot's `ApplicationArguments` are passed
+and its default implementation makes a choice which `ShellRunner` is used. There can be
+only one `ShellApplicationRunner` but it can be redefined if needed for some reason.
+
+Three `ShellRunner` implementation exists, named `InteractiveShellRunner`,
+`NonInteractiveShellRunner` and `ScriptShellRunner`. These are enabled on default but
+can be disable if needed using properties `spring.shell.interactive.enabled`,
+`spring.shell.noninteractive.enabled` and `spring.shell.script.enabled` respecively.

spring-shell-docs/src/test/java/org/springframework/shell/docs/CommandRegistrationInteractionModeSnippets.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.shell.docs;
+
+import org.springframework.shell.command.CommandRegistration;
+import org.springframework.shell.context.InteractionMode;
+import org.springframework.shell.standard.ShellMethod;
+
+public class CommandRegistrationInteractionModeSnippets {
+
+	// tag::snippet1[]
+	CommandRegistration commandRegistration() {
+		return CommandRegistration.builder()
+			.command("mycommand")
+			// can be defined for all modes
+			.interactionMode(InteractionMode.ALL)
+			// can be defined only for interactive
+			.interactionMode(InteractionMode.INTERACTIVE)
+			// can be defined only for non-interactive
+			.interactionMode(InteractionMode.NONINTERACTIVE)
+			.build();
+	}
+	// end::snippet1[]
+
+	static class Dump1 {
+
+		// tag::snippet2[]
+		@ShellMethod(key = "mycommand", interactionMode = InteractionMode.INTERACTIVE)
+		public void mycommand() {
+		}
+		// end::snippet2[]
+	}
+
+}