Document writing to console

- Relates #579

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

@@ -0,0 +1,27 @@
+=== Writing
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+When something needs to get written into your console you can always
+use JDK's `System.out` which then goes directly into JDK's own streams.
+Other recommended way is to use JLine's `Terminal` and get _writer_
+instance from there.
+
+If using target enpoints, i.e. _consumer_ which is not expected
+to return anything given `CommandContext` contains reference to
+`Terminal` and writer can be accessed from there.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/WritingSnippets.java[tag=reg-terminal-writer]
+----
+====
+
+It's possible to autowire `Terminal` to get access to its writer.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/WritingSnippets.java[tag=anno-terminal-writer]
+----
+====

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

@@ -20,3 +20,5 @@ include::using-shell-commands-helpoptions.adoc[]
 include::using-shell-commands-interactionmode.adoc[]
 
 include::using-shell-commands-builtin.adoc[]
+
+include::using-shell-commands-writing.adoc[]

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

@@ -0,0 +1,53 @@
+/*
+ * 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.jline.terminal.Terminal;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.shell.command.CommandRegistration;
+import org.springframework.shell.standard.ShellMethod;
+
+class WritingSnippets {
+
+	class Dump1 {
+
+		// tag::anno-terminal-writer[]
+		@Autowired
+		Terminal terminal;
+
+		@ShellMethod
+		public void example() {
+			terminal.writer().println("hi");
+			terminal.writer().flush();
+		}
+		// end::anno-terminal-writer[]
+	}
+
+	void dump1() {
+		// tag::reg-terminal-writer[]
+		CommandRegistration.builder()
+			.command("example")
+			.withTarget()
+				.consumer(ctx -> {
+					ctx.getTerminal().writer().println("hi");
+					ctx.getTerminal().writer().flush();
+				})
+				.and()
+			.build();
+		// end::reg-terminal-writer[]
+	}
+}

spring-shell-samples/src/main/java/org/springframework/shell/samples/e2e/WriteCommands.java

@@ -0,0 +1,71 @@
+/*
+ * 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.samples.e2e;
+
+import java.util.function.Supplier;
+
+import org.jline.terminal.Terminal;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.shell.command.CommandRegistration;
+import org.springframework.shell.standard.ShellComponent;
+import org.springframework.shell.standard.ShellMethod;
+
+@ShellComponent
+public class WriteCommands extends BaseE2ECommands {
+
+	@Autowired
+	Terminal terminal;
+
+	@Bean
+	public CommandRegistration writeTerminalWriterRegistration(Supplier<CommandRegistration.Builder> builder) {
+		return builder.get()
+			.command(REG, "write-terminalwriter")
+			.group(GROUP)
+			.withTarget()
+				.consumer(ctx -> {
+					ctx.getTerminal().writer().println("hi");
+					ctx.getTerminal().writer().flush();
+				})
+				.and()
+			.build();
+	}
+
+	@ShellMethod(key = LEGACY_ANNO + "write-terminalwriter", group = GROUP)
+	public void writeTerminalWriterAnnotation() {
+		terminal.writer().println("hi");
+		terminal.writer().flush();
+	}
+
+	@Bean
+	public CommandRegistration writeSystemOutRegistration(Supplier<CommandRegistration.Builder> builder) {
+		return builder.get()
+			.command(REG, "write-terminalwriter")
+			.group(GROUP)
+			.withTarget()
+				.consumer(ctx -> {
+					System.out.println("hi");
+				})
+				.and()
+			.build();
+	}
+
+	@ShellMethod(key = LEGACY_ANNO + "write-systemout", group = GROUP)
+	public void writeSystemOutAnnotation() {
+		System.out.println("hi");
+	}
+}