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