From 83e906d2e7eedf518d009e9cf628f9ed6320e5b1 Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Thu, 8 Dec 2022 09:51:59 +0000 Subject: [PATCH] Document writing to console - Relates #579 --- .../using-shell-commands-writing.adoc | 27 +++++++ .../main/asciidoc/using-shell-commands.adoc | 2 + .../shell/docs/WritingSnippets.java | 53 ++++++++++++++ .../shell/samples/e2e/WriteCommands.java | 71 +++++++++++++++++++ 4 files changed, 153 insertions(+) create mode 100644 spring-shell-docs/src/main/asciidoc/using-shell-commands-writing.adoc create mode 100644 spring-shell-docs/src/test/java/org/springframework/shell/docs/WritingSnippets.java create mode 100644 spring-shell-samples/src/main/java/org/springframework/shell/samples/e2e/WriteCommands.java diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-writing.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-writing.adoc new file mode 100644 index 00000000..518a6a18 --- /dev/null +++ b/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] +---- +==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc index 2a4187c0..a8053ace 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc +++ b/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[] diff --git a/spring-shell-docs/src/test/java/org/springframework/shell/docs/WritingSnippets.java b/spring-shell-docs/src/test/java/org/springframework/shell/docs/WritingSnippets.java new file mode 100644 index 00000000..9ba34c07 --- /dev/null +++ b/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[] + } +} diff --git a/spring-shell-samples/src/main/java/org/springframework/shell/samples/e2e/WriteCommands.java b/spring-shell-samples/src/main/java/org/springframework/shell/samples/e2e/WriteCommands.java new file mode 100644 index 00000000..eaa8f39b --- /dev/null +++ b/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 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 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"); + } +}