mirror of https://github.com/aristocratos/bashtop
97 lines
3.5 KiB
Markdown
97 lines
3.5 KiB
Markdown
# Bash Data Viewer
|
|
|
|
A TUI (Text-based User Interface) tool, written purely in Bash, for displaying CSV, TSV, or JSON data. The display refreshes at a configurable interval, inspired by tools like bashtop.
|
|
|
|
## Features
|
|
|
|
* Displays CSV, TSV, and JSON data in a tabular format.
|
|
* Configurable refresh interval for the data display.
|
|
* Basic TUI for easy viewing in the terminal.
|
|
* Error handling for file issues and unsupported formats.
|
|
|
|
## Dependencies
|
|
|
|
* **Bash**: Version 4.4 or later.
|
|
* **jq**: Required for parsing JSON files. You can usually install it via your system's package manager (e.g., `sudo apt install jq`, `sudo yum install jq`, `brew install jq`).
|
|
|
|
## Usage
|
|
|
|
To use the Bash Data Viewer, run the script from your terminal:
|
|
|
|
```shell
|
|
./dataviewer.sh [path_to_data_file] [refresh_interval_seconds]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
* `path_to_data_file` (optional): The path to the CSV, TSV, or JSON file you want to display.
|
|
* If not provided, the TUI will launch and show "No input file specified."
|
|
* `refresh_interval_seconds` (optional): The time in seconds between display refreshes.
|
|
* Defaults to 5 seconds if not provided.
|
|
* Must be a positive integer.
|
|
|
|
**Examples:**
|
|
|
|
* Display a CSV file with a 2-second refresh interval:
|
|
```shell
|
|
./dataviewer.sh data.csv 2
|
|
```
|
|
* Display a JSON file with the default 5-second refresh interval:
|
|
```shell
|
|
./dataviewer.sh logs.json
|
|
```
|
|
* Launch the TUI without an initial file (it will show an appropriate message):
|
|
```shell
|
|
./dataviewer.sh
|
|
```
|
|
|
|
## Supported Data Formats
|
|
|
|
### CSV (Comma-Separated Values)
|
|
* File extension must be `.csv`.
|
|
* The first line is treated as the header row.
|
|
* Uses comma (`,`) as the delimiter.
|
|
|
|
### TSV (Tab-Separated Values)
|
|
* File extension must be `.tsv`.
|
|
* The first line is treated as the header row.
|
|
* Uses tab (`\t`) as the delimiter.
|
|
|
|
### JSON (JavaScript Object Notation)
|
|
* File extension must be `.json`.
|
|
* Requires `jq` to be installed.
|
|
* **Supported Structures:**
|
|
1. **Array of Objects**:
|
|
* Example: `[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 24}]`
|
|
* The keys of the first object in the array are used as headers.
|
|
* Each object in the array is displayed as a row.
|
|
2. **Single Object**:
|
|
* Example: `{"hostname": "server1", "ip": "192.168.1.10", "status": "running"}`
|
|
* The keys of the object are used as headers.
|
|
* The object's values are displayed as a single data row.
|
|
3. **Empty Array**:
|
|
* Example: `[]`
|
|
* Displays an info message: "Info: JSON file is an empty array []".
|
|
* Other JSON structures (e.g., simple arrays of strings/numbers, nested complex objects without a clear tabular mapping) might show an "Unsupported JSON structure" error or may not display as intended.
|
|
|
|
## Controls
|
|
|
|
* **`q`**: Quit the application.
|
|
* **`r`**: Manually re-parse the input file and refresh the display. This is useful if the data file has been updated.
|
|
|
|
## Error Handling
|
|
|
|
The TUI will display messages for common errors, such as:
|
|
* File not found.
|
|
* Unknown file type.
|
|
* `jq` not installed (for JSON files).
|
|
* Empty or invalid JSON files.
|
|
* Unsupported JSON structures.
|
|
|
|
## TODO / Potential Future Enhancements
|
|
* More sophisticated column width calculation (e.g., based on content).
|
|
* Scrolling (up/down, left/right) for larger datasets.
|
|
* Configuration file for persistent settings.
|
|
* Theming support.
|
|
* Search/filter data within the TUI.
|