Add comprehensive documentation for terminal-ui
- Introduced new documentation files: `Components.md`, `Examples.md`, `Home.md`, `Install.md`, and `index.md`. - Provided detailed guides on usage, examples, installation, and API components. - Linked GitHub Pages and repository resources for easy navigation.
This commit is contained in:
!verity
63
docs/Components.md
Normal file
63
docs/Components.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# Components
|
||||
|
||||
Overview of what terminal-ui provides. All entry points are on `Terminal.*`.
|
||||
|
||||
## Output & text
|
||||
|
||||
| API | Description |
|
||||
|-----|-------------|
|
||||
| `Terminal.print(String)` | Styled text (chain `.color()`, `.bold()`, `.println()`) |
|
||||
| `Terminal.rule()` | Horizontal rule (e.g. `====`) |
|
||||
| `Terminal.keyValue()` | Key-value pairs |
|
||||
| `Terminal.box()` | Box around content |
|
||||
|
||||
## Tables & layout
|
||||
|
||||
| API | Description |
|
||||
|-----|-------------|
|
||||
| `Terminal.table()` | Tables with header/rows |
|
||||
| `Terminal.tree()` | Tree structure |
|
||||
| `Terminal.columns()` | Multi-column layout |
|
||||
| `Terminal.steps()` | Step indicator |
|
||||
| `Terminal.breadcrumb()` | Breadcrumb trail |
|
||||
| `Terminal.toc()` | Table of contents |
|
||||
|
||||
## Interactive
|
||||
|
||||
| API | Description |
|
||||
|-----|-------------|
|
||||
| `Terminal.prompt(String)` | Text input (`.ask()`, `.masked().ask()`) |
|
||||
| `Terminal.confirm(String)` | Y/n confirmation |
|
||||
| `Terminal.menu()` | Numbered menu (`.option()`, `.select()`) |
|
||||
| `Terminal.selectList()` | List with arrow keys + Enter |
|
||||
| `Terminal.pager()` | Paged output (Enter/arrows/q) |
|
||||
|
||||
## Live / progress
|
||||
|
||||
| API | Description |
|
||||
|-----|-------------|
|
||||
| `Terminal.progressBar()` | Progress bar (`.total()`, `.build()`) |
|
||||
| `Terminal.spinner()` | Spinning indicator (`.message()`, `.start()`) |
|
||||
| `Terminal.dashboard()` | Refreshing widget panel |
|
||||
|
||||
## Data & visuals
|
||||
|
||||
| API | Description |
|
||||
|-----|-------------|
|
||||
| `Terminal.diff()` | Diff view |
|
||||
| `Terminal.log()` | Log-style output |
|
||||
| `Terminal.timeline()` | Timeline |
|
||||
| `Terminal.heatmap()` | Heatmap |
|
||||
| `Terminal.chart()` | Charts |
|
||||
|
||||
## Other
|
||||
|
||||
| API | Description |
|
||||
|-----|-------------|
|
||||
| `Terminal.badge(String, Color)` | Colored badge |
|
||||
| `Terminal.notify(String, Type)` | Notification (info/success/warning/error) |
|
||||
| `Terminal.code(String)` | Code block with language |
|
||||
| `Terminal.sysinfo()` | System info (OS, Java, etc.) |
|
||||
| `Terminal.markdown(String)` | Render markdown to terminal |
|
||||
|
||||
Use the fluent API from `Terminal.*`. For tests or to disable ANSI, inject a custom `TerminalSupport`.
|
||||
262
docs/Examples.md
Normal file
262
docs/Examples.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# Examples
|
||||
|
||||
All examples use `import dev.jakub.terminal.Terminal;` and `import dev.jakub.terminal.core.Color;` where needed. Use `System.out` or omit the argument where `.print()` has a no-arg overload.
|
||||
|
||||
---
|
||||
|
||||
## Text & rules
|
||||
|
||||
```java
|
||||
Terminal.print("Hello").color(Color.CYAN).bold().println();
|
||||
|
||||
Terminal.rule().character('=').print();
|
||||
Terminal.rule().doubles().prefix("-- ").suffix(" --").print();
|
||||
```
|
||||
|
||||
## Key-value & box
|
||||
|
||||
```java
|
||||
Terminal.keyValue()
|
||||
.row("Name", "terminal-ui")
|
||||
.row("Version", "1.0")
|
||||
.separator(" = ")
|
||||
.print(System.out);
|
||||
|
||||
Terminal.box()
|
||||
.title("Info")
|
||||
.line("First line")
|
||||
.lines("Second", "Third")
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Table
|
||||
|
||||
```java
|
||||
Terminal.table()
|
||||
.header("Col A", "Col B", "Col C")
|
||||
.row("1", "2", "3")
|
||||
.row("4", "5", "6")
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Tree
|
||||
|
||||
```java
|
||||
Terminal.tree()
|
||||
.node("root")
|
||||
.child("src")
|
||||
.child("main").end()
|
||||
.child("test").end()
|
||||
.end()
|
||||
.child("docs")
|
||||
.end()
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Columns
|
||||
|
||||
```java
|
||||
Terminal.columns()
|
||||
.column("Left\ncolumn\ntext")
|
||||
.column("Middle")
|
||||
.column("Right")
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Steps (wizard-style)
|
||||
|
||||
```java
|
||||
Terminal.steps()
|
||||
.step("Setup", Steps.Status.DONE)
|
||||
.step("Build", Steps.Status.RUNNING)
|
||||
.step("Deploy", Steps.Status.PENDING)
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
(Use `import dev.jakub.terminal.components.Steps;` for `Steps.Status`.)
|
||||
|
||||
## Breadcrumb
|
||||
|
||||
```java
|
||||
Terminal.breadcrumb()
|
||||
.crumb("Home")
|
||||
.crumb("Projects")
|
||||
.crumb("terminal-ui")
|
||||
.separator(" / ")
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Interactive: Prompt
|
||||
|
||||
```java
|
||||
String name = Terminal.prompt("Name: ").ask();
|
||||
String secret = Terminal.prompt("Password: ").masked().ask();
|
||||
// With shared scanner (e.g. in a loop):
|
||||
String line = Terminal.prompt("Input: ").ask(sharedScanner);
|
||||
```
|
||||
|
||||
## Interactive: Confirm
|
||||
|
||||
```java
|
||||
boolean yes = Terminal.confirm("Continue?").defaultYes().ask();
|
||||
boolean no = Terminal.confirm("Delete?").defaultNo().ask();
|
||||
boolean answer = Terminal.confirm("Proceed?").ask(sharedScanner);
|
||||
```
|
||||
|
||||
## Interactive: Menu
|
||||
|
||||
```java
|
||||
String env = Terminal.menu()
|
||||
.title("Choose environment")
|
||||
.option("Development")
|
||||
.option("Staging")
|
||||
.option("Production")
|
||||
.select();
|
||||
```
|
||||
|
||||
## Interactive: SelectList (arrows + Enter)
|
||||
|
||||
```java
|
||||
String choice = Terminal.selectList()
|
||||
.title("Pick one")
|
||||
.option("Option A")
|
||||
.option("Option B")
|
||||
.option("Option C")
|
||||
.select();
|
||||
```
|
||||
|
||||
## Interactive: Pager
|
||||
|
||||
```java
|
||||
Terminal.pager()
|
||||
.lines("Line 1", "Line 2", "Line 3", "Line 4", "Line 5")
|
||||
.pageSize(3)
|
||||
.interactive();
|
||||
```
|
||||
|
||||
## Progress bar
|
||||
|
||||
```java
|
||||
ProgressBar bar = Terminal.progressBar()
|
||||
.total(100)
|
||||
.width(40)
|
||||
.style(ProgressBar.Style.BLOCK)
|
||||
.build();
|
||||
for (int i = 0; i <= 100; i++) {
|
||||
bar.update(i);
|
||||
Thread.sleep(30);
|
||||
}
|
||||
```
|
||||
|
||||
(Use `import dev.jakub.terminal.live.ProgressBar;`.)
|
||||
|
||||
## Spinner
|
||||
|
||||
```java
|
||||
Spinner spin = Terminal.spinner().message("Loading...").start();
|
||||
// ... do work ...
|
||||
spin.stop();
|
||||
```
|
||||
|
||||
(Use `import dev.jakub.terminal.live.Spinner;`.)
|
||||
|
||||
## Diff
|
||||
|
||||
```java
|
||||
Terminal.diff()
|
||||
.before("old line 1\nold line 2")
|
||||
.after("new line 1\nnew line 2\nnew line 3")
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Log
|
||||
|
||||
```java
|
||||
Terminal.log()
|
||||
.info("Started")
|
||||
.warn("Deprecation notice")
|
||||
.error("Something failed")
|
||||
.withTimestamp()
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Timeline
|
||||
|
||||
```java
|
||||
Terminal.timeline()
|
||||
.event("2024-01-01", "First release")
|
||||
.event("2024-06-01", "Added SelectList")
|
||||
.event("2025-01-01", "GitHub Packages")
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Heatmap
|
||||
|
||||
```java
|
||||
Terminal.heatmap()
|
||||
.row("Mon", 10, 20, 5, 30)
|
||||
.row("Tue", 15, 25, 10, 20)
|
||||
.row("Wed", 5, 15, 25, 35)
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Chart (sparkline / bar)
|
||||
|
||||
```java
|
||||
Terminal.chart()
|
||||
.data(1.0, 2.0, 1.5, 3.0, 2.5)
|
||||
.height(5)
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Badge & notification
|
||||
|
||||
```java
|
||||
Terminal.badge("OK", Color.GREEN).println();
|
||||
Terminal.badge("WARN", Color.YELLOW).print(System.out);
|
||||
|
||||
Terminal.notify("Done!", Notification.Type.SUCCESS);
|
||||
Terminal.notify("Warning", Notification.Type.WARNING);
|
||||
Terminal.notify("Error", Notification.Type.ERROR);
|
||||
Terminal.notify("Info", Notification.Type.INFO);
|
||||
```
|
||||
|
||||
(Use `import dev.jakub.terminal.components.Notification;`.)
|
||||
|
||||
## Code block
|
||||
|
||||
```java
|
||||
Terminal.code("java")
|
||||
.line("public static void main(String[] args) {")
|
||||
.line(" System.out.println(\"Hello\");")
|
||||
.line("}")
|
||||
.lineNumbers()
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## SysInfo
|
||||
|
||||
```java
|
||||
Terminal.sysinfo().print(System.out);
|
||||
```
|
||||
|
||||
## Markdown
|
||||
|
||||
```java
|
||||
Terminal.markdown("# Title\n\n**Bold** and *italic*.\n\n- Item 1\n- Item 2\n\n---")
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
## Table of contents
|
||||
|
||||
```java
|
||||
Terminal.toc()
|
||||
.section("Introduction").sub("Overview").sub("Install")
|
||||
.section("API").sub("Reference")
|
||||
.section("Examples")
|
||||
.print(System.out);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
For more, see the [README](https://github.com/jakubbbdev/terminal-ui#usage-excerpt) and the source.
|
||||
25
docs/Home.md
Normal file
25
docs/Home.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# terminal-ui
|
||||
|
||||
Java library for building terminal UIs: tables, rules, colors, prompts, menus, SelectList, pager, and more. Fluent API, ANSI support, testable.
|
||||
|
||||
## Quick links
|
||||
|
||||
- **[Install](Install)** – Gradle / Maven dependency
|
||||
- **[Components](Components)** – What's in the library
|
||||
- **[Examples](Examples)** – Code snippets
|
||||
|
||||
## Requirements
|
||||
|
||||
- Java 21
|
||||
- Gradle 9.x or Maven (wrapper included in repo)
|
||||
|
||||
## Build from source
|
||||
|
||||
```bash
|
||||
./gradlew build
|
||||
./gradlew test
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT – see [LICENSE](https://github.com/jakubbbdev/terminal-ui/blob/master/LICENSE) in the repo.
|
||||
45
docs/Install.md
Normal file
45
docs/Install.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# Install
|
||||
|
||||
Published to [GitHub Packages](https://github.com/jakubbbdev/terminal-ui/packages). Use a [release](https://github.com/jakubbbdev/terminal-ui/releases) version (e.g. `1.0.1`) for `VERSION`.
|
||||
|
||||
## Gradle (Kotlin DSL)
|
||||
|
||||
```kotlin
|
||||
repositories {
|
||||
mavenCentral()
|
||||
maven { url = uri("https://maven.pkg.github.com/jakubbbdev/terminal-ui") }
|
||||
}
|
||||
dependencies {
|
||||
implementation("dev.jakub.terminal:terminal-ui:VERSION")
|
||||
}
|
||||
```
|
||||
|
||||
## Gradle (Groovy)
|
||||
|
||||
```groovy
|
||||
repositories {
|
||||
mavenCentral()
|
||||
maven { url "https://maven.pkg.github.com/jakubbbdev/terminal-ui" }
|
||||
}
|
||||
dependencies {
|
||||
implementation "dev.jakub.terminal:terminal-ui:VERSION"
|
||||
}
|
||||
```
|
||||
|
||||
## Maven
|
||||
|
||||
```xml
|
||||
<repository>
|
||||
<id>github</id>
|
||||
<url>https://maven.pkg.github.com/jakubbbdev/terminal-ui</url>
|
||||
</repository>
|
||||
<dependency>
|
||||
<groupId>dev.jakub.terminal</groupId>
|
||||
<artifactId>terminal-ui</artifactId>
|
||||
<version>VERSION</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## Auth (if required)
|
||||
|
||||
For public packages, resolution often works without credentials. If your build asks for auth, use a [GitHub PAT](https://github.com/settings/tokens) with `read:packages`: username = your GitHub username, password = token.
|
||||
10
docs/index.md
Normal file
10
docs/index.md
Normal file
@@ -0,0 +1,10 @@
|
||||
# terminal-ui
|
||||
|
||||
Java library for terminal UIs: tables, prompts, menus, and more.
|
||||
|
||||
- **[Home](Home)** – overview
|
||||
- **[Install](Install)** – Gradle / Maven
|
||||
- **[Components](Components)** – what's in the library
|
||||
- **[Examples](Examples)** – runnable code snippets
|
||||
|
||||
[GitHub repo](https://github.com/jakubbbdev/terminal-ui) · [Releases](https://github.com/jakubbbdev/terminal-ui/releases) · [Packages](https://github.com/jakubbbdev/terminal-ui/packages)
|
||||
Reference in New Issue
Block a user