Skip to content

Commit 009e137

Browse files
committed
update demo and docs
1 parent 9832c8e commit 009e137

26 files changed

+428
-244
lines changed

NOTICE

+35-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,37 @@
1-
2-
Copyright 2016 Text IO development team
1+
Copyright 2016-2017 Text IO development team
32

43
This product includes software developed at The Apache Software Foundation (http://www.apache.org/).
4+
5+
===========================================================================
6+
Apache License - v 2.0 (http://www.apache.org/licenses/LICENSE-2.0.txt)
7+
===========================================================================
8+
The following components are provided under the Apache License - v 2.0. See project link for details.
9+
com.google.code.gson:gson (https://github.com/google/gson)
10+
com.sparkjava:spark-core (http://www.sparkjava.com)
11+
org.apache.commons:commons-lang3 (http://commons.apache.org/proper/commons-lang/)
12+
org.eclipse.jetty:* (http://www.eclipse.org/jetty)
13+
org.eclipse.jetty.websocket:* (http://www.eclipse.org/jetty)
14+
15+
16+
===========================================================================
17+
Eclipse Public License - v 1.0 (http://www.eclipse.org/legal/epl-v10.html)
18+
===========================================================================
19+
The following components are provided under the Eclipse Public License - v 1.0. See project link for details.
20+
ch.qos.logback:logback-classic (http://logback.qos.ch/)
21+
ch.qos.logback:logback-core (http://logback.qos.ch/)
22+
23+
24+
===========================================================================
25+
The BSD 2-Clause License (http://opensource.org/licenses/BSD-2-Clause)
26+
===========================================================================
27+
The following components are provided under the BSD 2-Clause License. See project link for details.
28+
jline:jline (https://github.com/jline/jline2)
29+
30+
===========================================================================
31+
The MIT License (http://www.opensource.org/licenses/mit-license.php)
32+
===========================================================================
33+
The following components are provided under the MIT License. See project link for details.
34+
org.slf4j:slf4j-api (http://www.slf4j.org)
35+
36+
Portions of the javascript code in the text-io-web module have been adapted from
37+
https://github.com/AVGP/terminal.js, which is also provided under the MIT License.

README.md

+4
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,10 @@ Click on the image below to see the output of the above example in a Swing-based
4949

5050
<a href="https://github.com/beryx/text-io/raw/master/doc/img/swing-terminal-animated.gif"><img src="https://github.com/beryx/text-io/raw/master/doc/img/swing-terminal-thumb.gif"></a>
5151

52+
You can also use a web-based terminal, which allows you to access your application via a browser, as shown in the image below.
53+
54+
<a href="https://github.com/beryx/text-io/raw/master/doc/img/web-terminal-animated.gif"><img src="https://github.com/beryx/text-io/raw/master/doc/img/web-terminal-thumb.gif"></a>
55+
5256
Before starting to use the library, try the demo application included in the **[release](https://github.com/beryx/text-io/releases/latest)**
5357
and read the **[documentation](http://text-io.beryx.org)** and the **[javadoc](http://text-io.beryx.org/releases/latest/javadoc)**.
5458

doc/getting_started.adoc

+18-2
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,28 @@ Text-IO is available in Maven Central and JCenter.
99
----
1010
&lt;dependency&gt;
1111
&lt;groupId&gt;{project-group}&lt;/groupId&gt;
12-
&lt;artifactId&gt;{project-name}&lt;/artifactId&gt;
12+
&lt;artifactId&gt;text-io&lt;/artifactId&gt;
1313
&lt;version&gt;{project-version}&lt;/version&gt;
1414
&lt;/dependency&gt;
1515
----
1616

1717
[subs="attributes",options="nowrap",title="Gradle"]
1818
----
19-
compile '{project-group}:{project-name}:{project-version}'
19+
compile '{project-group}:text-io:{project-version}'
20+
----
21+
22+
In order to use the WebTextTerminal, you have to include the `text-io-web` artifact:
23+
24+
[subs="attributes",options="nowrap",title="Maven"]
25+
----
26+
&lt;dependency&gt;
27+
&lt;groupId&gt;{project-group}&lt;/groupId&gt;
28+
&lt;artifactId&gt;text-io-web&lt;/artifactId&gt;
29+
&lt;version&gt;{project-version}&lt;/version&gt;
30+
&lt;/dependency&gt;
31+
----
32+
33+
[subs="attributes",options="nowrap",title="Gradle"]
34+
----
35+
compile '{project-group}:text-io-web:{project-version}'
2036
----

doc/img/swing-terminal-thumb.png

-7.37 KB
Binary file not shown.

doc/img/web-terminal-animated.gif

50.8 KB
Loading

doc/img/web-terminal-thumb.gif

7.08 KB
Loading

doc/img/web-terminal.png

29.6 KB
Loading

doc/introduction.adoc

+4
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,10 @@ Click on the image below to see the output of the above example in a Swing-based
5050
image::swing-terminal-thumb.gif[role="thumb" link="https://github.com/beryx/text-io/raw/master/doc/img/swing-terminal-animated.gif"]
5151

5252

53+
You can also use a web-based terminal, which allows you to access your application via a browser, as shown in the image below.
54+
55+
image::web-terminal-thumb.gif[role="thumb" link="https://github.com/beryx/text-io/raw/master/doc/img/web-terminal-animated.gif"]
56+
5357

5458
== Demo
5559

doc/user_guide.adoc

+10-5
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ The following concrete implementations are provided by the Text-IO library:
1818

1919
- link:javadoc/org/beryx/textio/jline/JLineTextTerminal.html[JLineTextTerminal], which is backed by a
2020
https://github.com/jline/jline2[JLine] ReadConsole.
21+
- link:javadoc/org/beryx/textio/jline/AnsiTextTerminal.html[AnsiTextTerminal], which extends JLineTextTerminal
22+
by allowing to customize the appearance of the prompt messages (colors and boldness).
2123
- link:javadoc/org/beryx/textio/console/ConsoleTextTerminal.html[ConsoleTextTerminal], which is backed by a
2224
http://docs.oracle.com/javase/8/docs/api/java/io/Console.html[java.io.Console].
2325
- link:javadoc/org/beryx/textio/swing/SwingTextTerminal.html[SwingTextTerminal], which uses a
@@ -28,6 +30,8 @@ http://docs.oracle.com/javase/8/docs/api/java/lang/System.html#out[System.out],
2830
http://docs.oracle.com/javase/8/docs/api/java/lang/System.html#in[System.in] and
2931
http://docs.oracle.com/javase/8/docs/api/java/util/Scanner.html[Scanner].
3032
It is not capable to mask input strings, therefore not recommended when reading sensitive data.
33+
- link:javadoc/org/beryx/textio/web/WebTextTerminal.html[WebTextTerminal], which allows accessing
34+
your application via a browser. Only WebKit-based browsers (such as Chrome, Opera or Safari) are currently able to mask input strings.
3135

3236
== Input Readers
3337

@@ -72,8 +76,8 @@ to read a comma-separated list of values.
7276
These methods repeatedly prompt the user to enter a value or a comma-separated list of values, until a valid input is provided.
7377

7478
TIP: Look at the source code of
75-
link:{blob-root}/src/test/groovy/org/beryx/textio/TextIoReadSpec.groovy[TextIoReadSpec.groovy]
76-
and link:{blob-root}/src/test/groovy/org/beryx/textio/TextIoReadListSpec.groovy[TextIoReadListSpec.groovy]
79+
link:{blob-root}/text-io/src/test/groovy/org/beryx/textio/TextIoReadSpec.groovy[TextIoReadSpec.groovy]
80+
and link:{blob-root}/text-io/src/test/groovy/org/beryx/textio/TextIoReadListSpec.groovy[TextIoReadListSpec.groovy]
7781
for examples of using the input readers.
7882

7983

@@ -113,6 +117,7 @@ link:javadoc/org/beryx/textio/console/ConsoleTextTerminal.html[ConsoleTextTermin
113117
- else, a link:javadoc/org/beryx/textio/system/SystemTextTerminal.html[SystemTextTerminal] is provided.
114118

115119
TIP: Look at the source code of
116-
link:{blob-root}/src/main/java/org/beryx/textio/demo/TextIoDemo.java[TextIoDemo.java]
117-
and link:{blob-root}/src/main/java/org/beryx/textio/demo/ColorTextTerminal.java[ColorTextTerminal.java]
118-
for an example of defining and configuring a custom TextTerminal.
120+
link:{blob-root}/text-io-demo/src/main/java/org/beryx/textio/demo/Simple.java[SimpleApp.java]
121+
for an example of using the default TextTerminal provided by TextIofactory,
122+
and link:{blob-root}/text-io-demo/src/main/java/org/beryx/textio/demo/TextIoDemo.java[TextIoDemo.java]
123+
for examples of using custom TextTerminals.

text-io-demo/src/main/java/org/beryx/textio/demo/ColorTextTerminal.java

-45
This file was deleted.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
/*
2+
* Copyright 2016 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package org.beryx.textio.demo;
17+
18+
import org.beryx.textio.TextIO;
19+
import org.beryx.textio.TextIoFactory;
20+
21+
import java.time.Month;
22+
23+
/**
24+
* A simple application illustrating the use of TextIO.
25+
*/
26+
public class SimpleApp {
27+
public static void main(String[] args) {
28+
TextIO textIO = TextIoFactory.getTextIO();
29+
execute(textIO);
30+
}
31+
32+
public static void execute(TextIO textIO) {
33+
String user = textIO.newStringInputReader()
34+
.withDefaultValue("admin")
35+
.read("Username");
36+
37+
String password = textIO.newStringInputReader()
38+
.withMinLength(6)
39+
.withInputMasking(true)
40+
.read("Password");
41+
42+
int age = textIO.newIntInputReader()
43+
.withMinVal(13)
44+
.read("Age");
45+
46+
Month month = textIO.newEnumInputReader(Month.class)
47+
.read("What month were you born in?");
48+
49+
textIO.getTextTerminal().printf("\nUser %s is %d years old, was born in %s and has the password %s.\n", user, age, month, password);
50+
51+
textIO.newStringInputReader().withMinLength(0).read("\nPress enter to terminate...");
52+
textIO.dispose();
53+
}
54+
}

text-io-demo/src/main/java/org/beryx/textio/demo/TextIoDemo.java

+96-32
Original file line numberDiff line numberDiff line change
@@ -18,51 +18,115 @@
1818
import org.beryx.textio.TextIO;
1919
import org.beryx.textio.TextIoFactory;
2020
import org.beryx.textio.TextTerminal;
21+
import org.beryx.textio.TextTerminalProvider;
22+
import org.beryx.textio.console.ConsoleTextTerminalProvider;
23+
import org.beryx.textio.jline.AnsiTextTerminal;
24+
import org.beryx.textio.jline.JLineTextTerminalProvider;
25+
import org.beryx.textio.swing.SwingTextTerminalProvider;
26+
import org.beryx.textio.system.SystemTextTerminal;
27+
import org.beryx.textio.system.SystemTextTerminalProvider;
28+
import org.beryx.textio.web.WebTextTerminal;
29+
import spark.Service;
2130

22-
import java.time.Month;
31+
import java.util.function.Supplier;
2332

2433
/**
25-
* Demo application illustrating the use of TextIO.
26-
* <br>If an argument is provided, it will be used to set the value of the <tt>{@value TextIoFactory#TEXT_TERMINAL_CLASS_PROPERTY}</tt> system property.
27-
* This means that the program will interpret the argument as the fully-qualified name of a concrete {@link TextTerminal} class and will try to create and use an instance of this class.
28-
* <br>Example: run the program with the argument <tt>org.beryx.textio.demo.ColorTextTerminal</tt>.
34+
* Demo application showing various TextTerminals.
2935
*/
3036
public class TextIoDemo {
37+
private static int webServerPort = -1;
38+
39+
private static class NamedProvider implements TextTerminalProvider {
40+
final String name;
41+
final Supplier<TextTerminal> supplier;
42+
43+
NamedProvider(String name, Supplier<TextTerminal> supplier) {
44+
this.name = name;
45+
this.supplier = supplier;
46+
}
47+
48+
@Override
49+
public TextTerminal getTextTerminal() {
50+
return supplier.get();
51+
}
52+
53+
@Override
54+
public String toString() {
55+
return name;
56+
}
57+
}
58+
3159
public static void main(String[] args) {
32-
if(args.length > 0) {
33-
System.setProperty(TextIoFactory.TEXT_TERMINAL_CLASS_PROPERTY, args[0]);
60+
TextIO textIO = chooseTextIO();
61+
if(textIO.getTextTerminal() instanceof WebTextTerminal) {
62+
WebTextIoExecutor webTextIoExecutor = new WebTextIoExecutor().withPort(webServerPort);
63+
webTextIoExecutor.execute(SimpleApp::execute);
64+
} else {
65+
SimpleApp.execute(textIO);
3466
}
35-
TextIO textIO = TextIoFactory.getTextIO();
36-
TextTerminal terminal = textIO.getTextTerminal();
37-
if(args.length == 0) {
38-
terminal.println("-------------------------------------------------------------------------");
39-
terminal.println("Usage tip:");
40-
terminal.println(" Provide as argument the fully-qualified name of a TextTerminal class.");
41-
terminal.println(" Example: run with the argument org.beryx.textio.demo.ColorTextTerminal.");
42-
terminal.println("-------------------------------------------------------------------------");
43-
terminal.println();
44-
terminal.println();
67+
}
68+
69+
private static TextIO chooseTextIO() {
70+
TextTerminal terminal = new SystemTextTerminal();
71+
TextIO textIO = new TextIO(terminal);
72+
while(true) {
73+
TextTerminalProvider terminalProvider = textIO.<TextTerminalProvider>newGenericInputReader(null)
74+
.withNumberedPossibleValues(
75+
new NamedProvider("Default terminal (provided by TextIoFactory)", TextIoFactory::getTextTerminal),
76+
new SystemTextTerminalProvider(),
77+
new ConsoleTextTerminalProvider(),
78+
new JLineTextTerminalProvider(),
79+
new NamedProvider("ANSI terminal", () -> createAnsiTextTerminal(textIO)),
80+
new SwingTextTerminalProvider(),
81+
new NamedProvider("Web terminal", () -> createWebTextTerminal(textIO))
82+
)
83+
.read("Choose the terminal to be used for running the demo");
84+
85+
TextTerminal chosenTerminal = null;
86+
String errMsg = null;
87+
try {
88+
chosenTerminal = terminalProvider.getTextTerminal();
89+
} catch (Exception e) {
90+
errMsg = e.getMessage();
91+
}
92+
if(chosenTerminal == null) {
93+
terminal.printf("\nCannot create a %s%s\n\n", terminalProvider, ((errMsg != null) ? (": " + errMsg) : "."));
94+
continue;
95+
}
96+
return new TextIO(chosenTerminal);
4597
}
98+
}
4699

47-
String user = textIO.newStringInputReader()
48-
.withDefaultValue("admin")
49-
.read("Username");
100+
private static AnsiTextTerminal createAnsiTextTerminal(TextIO textIO) {
101+
boolean bold = textIO.newBooleanInputReader()
102+
.withDefaultValue(false)
103+
.read("Bold text?");
50104

51-
String password = textIO.newStringInputReader()
52-
.withMinLength(6)
53-
.withInputMasking(true)
54-
.read("Password");
105+
String[] colors = AnsiTextTerminal.ANSI_COLOR_MAP.keySet().toArray(new String[0]);
106+
String color = textIO.newStringInputReader()
107+
.withNumberedPossibleValues(colors)
108+
.withDefaultValue("yellow")
109+
.read("Text color");
55110

56-
int age = textIO.newIntInputReader()
57-
.withMinVal(13)
58-
.read("Age");
111+
String bgColor = textIO.newStringInputReader()
112+
.withNumberedPossibleValues(colors)
113+
.withDefaultValue("blue")
114+
.read("Background color");
59115

60-
Month month = textIO.newEnumInputReader(Month.class)
61-
.read("What month were you born in?");
116+
AnsiTextTerminal terminal = new AnsiTextTerminal();
117+
terminal.withBold(bold);
118+
terminal.withColor(color);
119+
terminal.withBackgroundColor(bgColor);
120+
return terminal;
121+
}
62122

63-
terminal.printf("\nUser %s is %d years old, was born in %s and has the password %s.\n", user, age, month, password);
123+
private static WebTextTerminal createWebTextTerminal(TextIO textIO) {
124+
webServerPort = textIO.newIntInputReader()
125+
.withDefaultValue(Service.SPARK_DEFAULT_PORT)
126+
.read("Server port number");
64127

65-
textIO.newStringInputReader().withMinLength(0).read("\nPress enter to terminate...");
66-
textIO.dispose();
128+
// The returned WebTextTerminal is not actually used, but treated as a marker that triggers the creation of a WebTextIoExecutor.
129+
// This WebTextIoExecutor will instantiate a new WebTextTerminal each time a client starts a new session.
130+
return new WebTextTerminal();
67131
}
68132
}

0 commit comments

Comments
 (0)