Skip to content

Commit 03e3666

Browse files
gnodetgnodet
committed
Add documentation for JLine modules: builtins, style, console, and console-ui
1 parent 51a0140 commit 03e3666

File tree

7 files changed

+2169
-1
lines changed

7 files changed

+2169
-1
lines changed

‎.idea/AugmentWebviewStateStore.xml

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎jline-docs/docs/modules/builtins.md

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# JLine Builtins
6+
7+
The `jline-builtins` module provides a set of ready-to-use commands and utilities that you can incorporate into your command-line applications. These built-in components save you time and effort when implementing common command-line functionality.
8+
9+
## Maven Dependency
10+
11+
To use the builtins module, add the following dependency to your project:
12+
13+
```xml
14+
<dependency>
15+
<groupId>org.jline</groupId>
16+
<artifactId>jline-builtins</artifactId>
17+
<version>3.25.0</version>
18+
</dependency>
19+
```
20+
21+
## Built-in Commands
22+
23+
The builtins module includes several ready-to-use commands that you can incorporate into your application:
24+
25+
### File Operations
26+
27+
```java title="FileOperationsExample.java" showLineNumbers
28+
import org.jline.builtins.Commands;
29+
import org.jline.builtins.Completers.FilesCompleter;
30+
import org.jline.reader.LineReader;
31+
import org.jline.reader.LineReaderBuilder;
32+
import org.jline.reader.impl.completer.ArgumentCompleter;
33+
import org.jline.reader.impl.completer.StringsCompleter;
34+
import org.jline.terminal.Terminal;
35+
import org.jline.terminal.TerminalBuilder;
36+
37+
import java.io.IOException;
38+
import java.io.PrintWriter;
39+
import java.nio.file.Path;
40+
import java.nio.file.Paths;
41+
42+
public class FileOperationsExample {
43+
public static void main(String[] args) throws IOException {
44+
Terminal terminal = TerminalBuilder.builder().build();
45+
PrintWriter writer = terminal.writer();
46+
47+
// Create a line reader with file operations completers
48+
LineReader reader = LineReaderBuilder.builder()
49+
.terminal(terminal)
50+
.completer(new ArgumentCompleter(
51+
new StringsCompleter("ls", "cat", "less"),
52+
new FilesCompleter(Paths.get("."))))
53+
.build();
54+
55+
// Main command loop
56+
while (true) {
57+
String line = reader.readLine("builtin> ");
58+
String[] arguments = line.split("\\s+");
59+
60+
try {
61+
if (arguments.length > 0) {
62+
switch (arguments[0]) {
63+
// highlight-start
64+
case "ls":
65+
// List files in a directory
66+
Path path = arguments.length > 1 ? Paths.get(arguments[1]) : Paths.get(".");
67+
Commands.ls(terminal, writer, path, false, false, false, false);
68+
break;
69+
// highlight-end
70+
71+
case "cat":
72+
// Display file contents
73+
if (arguments.length > 1) {
74+
Commands.cat(terminal, writer, Paths.get(arguments[1]));
75+
} else {
76+
writer.println("Usage: cat <file>");
77+
}
78+
break;
79+
80+
case "less":
81+
// Display file contents with paging
82+
if (arguments.length > 1) {
83+
Commands.less(terminal, Paths.get(arguments[1]));
84+
} else {
85+
writer.println("Usage: less <file>");
86+
}
87+
break;
88+
89+
case "exit":
90+
return;
91+
92+
default:
93+
writer.println("Unknown command: " + arguments[0]);
94+
}
95+
}
96+
} catch (Exception e) {
97+
writer.println("Error: " + e.getMessage());
98+
}
99+
writer.flush();
100+
}
101+
}
102+
}
103+
```
104+
105+
### Table Formatting
106+
107+
The builtins module includes utilities for formatting tabular data:
108+
109+
```java title="TableFormattingExample.java"
110+
import org.jline.builtins.Styles;
111+
import org.jline.builtins.Styles.AttributedStringBuilder;
112+
import org.jline.builtins.Styles.AttributedStyle;
113+
import org.jline.builtins.Tables;
114+
import org.jline.builtins.Tables.Column;
115+
import org.jline.builtins.Tables.ColumnType;
116+
import org.jline.terminal.Terminal;
117+
import org.jline.terminal.TerminalBuilder;
118+
119+
import java.io.IOException;
120+
import java.io.PrintWriter;
121+
import java.util.ArrayList;
122+
import java.util.Arrays;
123+
import java.util.List;
124+
125+
public class TableFormattingExample {
126+
public static void main(String[] args) throws IOException {
127+
Terminal terminal = TerminalBuilder.builder().build();
128+
PrintWriter writer = terminal.writer();
129+
130+
// highlight-start
131+
// Define table columns
132+
List<Column> columns = Arrays.asList(
133+
new Column("ID", ColumnType.Number),
134+
new Column("Name", ColumnType.String),
135+
new Column("Role", ColumnType.String),
136+
new Column("Salary", ColumnType.Number)
137+
);
138+
// highlight-end
139+
140+
// Create table data
141+
List<List<String>> data = new ArrayList<>();
142+
data.add(Arrays.asList("1", "John Doe", "Developer", "75000"));
143+
data.add(Arrays.asList("2", "Jane Smith", "Manager", "85000"));
144+
data.add(Arrays.asList("3", "Bob Johnson", "Designer", "65000"));
145+
146+
// Print the table
147+
Tables.TableBuilder tableBuilder = new Tables.TableBuilder(columns);
148+
tableBuilder.addAll(data);
149+
150+
// Format and display the table
151+
Tables.Table table = tableBuilder.build();
152+
String result = table.toStringWithColumns(
153+
terminal.getWidth(),
154+
true, // display borders
155+
true // display header
156+
);
157+
158+
writer.println(result);
159+
writer.flush();
160+
}
161+
}
162+
```
163+
164+
## Widgets
165+
166+
The builtins module provides several widgets that can be used with the LineReader:
167+
168+
```java title="WidgetsExample.java"
169+
import org.jline.builtins.Widgets;
170+
import org.jline.builtins.Widgets.TailTipWidgets;
171+
import org.jline.builtins.Widgets.TailTipWidgets.TipType;
172+
import org.jline.reader.LineReader;
173+
import org.jline.reader.LineReaderBuilder;
174+
import org.jline.reader.impl.DefaultParser;
175+
import org.jline.terminal.Terminal;
176+
import org.jline.terminal.TerminalBuilder;
177+
178+
import java.io.IOException;
179+
import java.util.HashMap;
180+
import java.util.Map;
181+
182+
public class WidgetsExample {
183+
public static void main(String[] args) throws IOException {
184+
Terminal terminal = TerminalBuilder.builder().build();
185+
DefaultParser parser = new DefaultParser();
186+
187+
LineReader reader = LineReaderBuilder.builder()
188+
.terminal(terminal)
189+
.parser(parser)
190+
.build();
191+
192+
// highlight-start
193+
// Create command descriptions for TailTip widget
194+
Map<String, List<String>> commandDescriptions = new HashMap<>();
195+
commandDescriptions.put("help", Arrays.asList("Display help information"));
196+
commandDescriptions.put("exit", Arrays.asList("Exit the application"));
197+
commandDescriptions.put("ls", Arrays.asList("[path]", "List directory contents"));
198+
commandDescriptions.put("cat", Arrays.asList("<file>", "Display file contents"));
199+
200+
// Create and install the TailTip widget
201+
TailTipWidgets widgets = new TailTipWidgets(reader, commandDescriptions, 5, TipType.COMPLETER);
202+
widgets.enable();
203+
// highlight-end
204+
205+
// Main command loop
206+
while (true) {
207+
String line = reader.readLine("widgets> ");
208+
if ("exit".equals(line)) {
209+
break;
210+
}
211+
terminal.writer().println("You entered: " + line);
212+
terminal.writer().flush();
213+
}
214+
}
215+
}
216+
```
217+
218+
## SystemRegistryImpl
219+
220+
The builtins module includes a `SystemRegistryImpl` class that provides a registry for commands:
221+
222+
```java title="SystemRegistryExample.java" showLineNumbers
223+
import org.jline.builtins.Builtins;
224+
import org.jline.builtins.Completers.SystemCompleter;
225+
import org.jline.builtins.Options.HelpException;
226+
import org.jline.builtins.SystemRegistry;
227+
import org.jline.builtins.SystemRegistryImpl;
228+
import org.jline.reader.LineReader;
229+
import org.jline.reader.LineReaderBuilder;
230+
import org.jline.reader.impl.DefaultParser;
231+
import org.jline.terminal.Terminal;
232+
import org.jline.terminal.TerminalBuilder;
233+
234+
import java.io.IOException;
235+
import java.io.PrintWriter;
236+
import java.nio.file.Paths;
237+
import java.util.function.Supplier;
238+
239+
public class SystemRegistryExample {
240+
public static void main(String[] args) throws IOException {
241+
Terminal terminal = TerminalBuilder.builder().build();
242+
DefaultParser parser = new DefaultParser();
243+
244+
// highlight-start
245+
// Create the registry
246+
SystemRegistry registry = new SystemRegistryImpl(parser, terminal, () -> Paths.get("."), null);
247+
248+
// Create builtins
249+
Builtins builtins = new Builtins(registry::commandRegistry, () -> Paths.get("."), null, null);
250+
// highlight-end
251+
252+
// Register commands
253+
registry.register("help", builtins::help);
254+
registry.register("ls", builtins::ls);
255+
registry.register("cat", builtins::cat);
256+
registry.register("less", builtins::less);
257+
258+
// Set up completers
259+
SystemCompleter completer = builtins.compileCompleters();
260+
261+
// Create line reader
262+
LineReader reader = LineReaderBuilder.builder()
263+
.terminal(terminal)
264+
.completer(completer)
265+
.parser(parser)
266+
.build();
267+
268+
registry.setLineReader(reader);
269+
270+
// Main command loop
271+
PrintWriter writer = terminal.writer();
272+
while (true) {
273+
try {
274+
String line = reader.readLine("registry> ");
275+
if (line.trim().equalsIgnoreCase("exit")) {
276+
break;
277+
}
278+
279+
// Execute the command
280+
registry.execute(line);
281+
} catch (HelpException e) {
282+
writer.println(e.getMessage());
283+
} catch (Exception e) {
284+
writer.println("Error: " + e.getMessage());
285+
e.printStackTrace(writer);
286+
}
287+
writer.flush();
288+
}
289+
}
290+
}
291+
```
292+
293+
## Nano Text Editor
294+
295+
The builtins module includes a Nano-like text editor:
296+
297+
```java title="NanoEditorExample.java"
298+
import org.jline.builtins.Nano;
299+
import org.jline.builtins.Nano.NanoConfig;
300+
import org.jline.terminal.Terminal;
301+
import org.jline.terminal.TerminalBuilder;
302+
303+
import java.io.IOException;
304+
import java.nio.file.Paths;
305+
306+
public class NanoEditorExample {
307+
public static void main(String[] args) throws IOException {
308+
Terminal terminal = TerminalBuilder.builder().build();
309+
310+
// highlight-start
311+
// Configure Nano
312+
NanoConfig config = new NanoConfig.Builder()
313+
.tabSize(4)
314+
.tabToSpaces(true)
315+
.build();
316+
317+
// Launch Nano editor
318+
Nano nano = new Nano(terminal, config);
319+
nano.open(Paths.get("example.txt"));
320+
// highlight-end
321+
}
322+
}
323+
```
324+
325+
## Best Practices
326+
327+
When using the JLine builtins module, consider these best practices:
328+
329+
1. **Use SystemRegistry for Command Management**: The `SystemRegistryImpl` provides a clean way to register and manage commands.
330+
331+
2. **Leverage Built-in Commands**: Use the provided commands like `ls`, `cat`, and `less` instead of reimplementing them.
332+
333+
3. **Combine with Completers**: Pair built-in commands with appropriate completers for a better user experience.
334+
335+
4. **Use TailTipWidgets for Contextual Help**: The TailTip widgets provide inline help that improves usability.
336+
337+
5. **Customize Table Formatting**: Adjust table formatting to match your application's style and the terminal's capabilities.
338+
339+
6. **Handle Exceptions Properly**: Built-in commands may throw exceptions that should be caught and handled appropriately.
340+
341+
7. **Consider Terminal Capabilities**: Some built-in features may depend on terminal capabilities, so check for support before using them.

0 commit comments

Comments
 (0)