# TextGraph A small terminal utility which displays graphs as plain text, with the goal of having few dependencies, being lightweight, and reasonably performant. It is meant to be used in a traditional unix way, by piping data through it. It was written because I sometimes have the need to watch some state in a sql table for a short while. The documentation is in the manual file `textgraph.1`. It is only tested with glibc and terminals with ansi escape code support. ## Usage There is a script in `packaging` which can be used to make a `.deb`. If you are on a debian based distro, you should be able to run `./packaging/package-debian.sh`. Then a `textgraph.deb` file should be made somewhere in `/tmp/`. There is a script in `packaging` which can be used to make a `.rpm`. If you are on a rpm based distro, you should be able to run `./packaging/package-fedora.sh`. Then a `textgraph-.rpm` should be build in `~/rpmbuild/RPMS/x86_64/`. You can compile it with `cargo build --release`. If you compile with `cargo build --release`, you can copy it to your path, e.g. ``` sudo install target/release/textgraph /usr/local/bin/textgraph sudo install textgraph.1 /usr/share/man/man1/textgraph.1 ``` ### Features By default `libc` and `ansi` is enabled. The `libc` feature makes the program able to get the terminal size, and catch signals like SIGINT. The last part is needed if you want the program to use the alternate screen in filter-mode. It does not currently use the `libc`-crate, but it does use c-functions. The `ansi` feature enables the use of ansi escape codes, this is used for manipulating the terminal. Like adding colors to the graph, and switching back and fourth from the alternate screen (this will only happen when `libc` also is enabled). ## Example 1 Some examples of the different modes, from the same input file with random numbers ### Star mode ``` 100┌─────────────────────────────────────────────┐ 89 │ * * │ 79 │ * * * ** │ 68 │ ** * * │ 58 │ * * * * * * * │ 47 │ * * * * * **│ 37 │* * *** * * * * * │ 26 │ * * * * * │ 16 │ ** * * * │ 5 └─────────────────────────────────────────────┘ ``` ### Ascii mode ``` 100┌─────────────────────────────────────────────┐ 89 │ ╭╮ ╭╮ │ 79 │ ││╭╮ ╭╮ ╭╮ ╭─╮ ││ │ 68 │ ╭─╯│││ ╭╯│ ││ ╭╮ │ │ ││ │ 58 │╭╮ ╭╮ │ ││╰╮ │ │ ╭╮││ │╰╮│ │ ╭╮ ╭╯│ │ 47 ││╰╮ │╰╮│ ││ ╰╮│ │ │││╰╮ │ ││ ╰╮││ │ │╭──┤ 37 ├╯ │ │ ╰╯ ││ ││ ╰──╯╰╯ │ ╭╮│ ╰╯ ╰╯│ │ ╰╯ │ 26 │ ╰╮ │ ╰╯ ╰╯ │╭╯││ │╭╯ │ 16 │ ╰─╯ ╰╯ ╰╯ ╰╯ │ 5 └─────────────────────────────────────────────┘ ``` ### Braille mode (Probably the most buggy mode) ``` 100┌────────────────────┐ 89 │ ⠄⠂ │ 79 │ ⠄ │ 68 │ ⠠ ⠂ ⠠ │ 58 │⠠ ⠠ ⠄ ⠂⠠ │ 47 │ ⠄ ⠂ ⠂│ 37 │ ⠠ ⠂ ⠄ ⠐ ⠠ ⠐ │ 26 │ ⠠ ⠂ ⠂ │ 16 │⠂ ⠠ ⠂ ⠐ │ 5 └────────────────────┘ ``` ## Example 2 Example of a simple sinusoid ### Star ``` 10 ┌──────────────────────────────────────────────────────────────────────┐ 8 │ ********** │ 6 │ ***** ***** │ 3 │ *** *** │ 1 │ *** *** │ -1 │ *** *** │ -3 │ *** *** │ -6 │ **** **** │ -8 │******** **********│ -10└──────────────────────────────────────────────────────────────────────┘ ``` ### Ascii ``` 10 ┌──────────────────────────────────────────────────────────────────────┐ 8 │ ╭─────────╮ │ 6 │ ╭────╯ ╰────╮ │ 3 │ ╭──╯ ╰──╮ │ 1 │ ╭──╯ ╰──╮ │ -1 │ ╭──╯ ╰──╮ │ -3 │ ╭──╯ ╰──╮ │ -6 │ ╭───╯ ╰───╮ │ -8 ├───────╯ ╰──────────┤ -10└──────────────────────────────────────────────────────────────────────┘ ``` ### Braille ``` 10 ┌───────────────────────────────────┐ 8 │ ⠠⠔⠊⠉⠉⠑⠢⠄ │ 6 │ ⠔⠁ ⠈⠢ │ 3 │ ⠠⠊ ⠑⠄ │ 1 │ ⠔⠁ ⠈⠢ │ -1 │ ⠌ ⠡ │ -3 │ ⠠⠊ ⠑⠄ │ -6 │ ⠠⠔⠁ ⠈⠢⠄ │ -8 │⠤⠤⠤⠒⠁ ⠈⠒⠤⠤⠤⠒│ -10└───────────────────────────────────┘ ``` ## Manual For reference, this is a translation of the manual page. Best is to check to manual page itself, not the README `man -l textgraph.1`. ``` TEXTGRAPH(1) General Commands Manual TEXTGRAPH(1) name TextGraph - Text graphing utility SYNOPSIS textgraph [OPTIONS] [input_file] DESCRIPTION textgraph TermGraph is a utility for graphing OPTIONS --help Display help information. -s, --silent Disable distracting elements, such as axis and non-graph text. -n, --last-n count If specified, only the newest count samples will be plotted. This can be useful if you want to follow the latest state of a graph that is piped in. -c, --cut This is a special case of --last-n. Where the number of columns --width will be used for the count. -a, --ascii Shorthand for -t ascii, if multiple options setting mode is specified, the last will likely be respected. -b, --braille Shorthand for -t braille, if multiple options setting mode is specified, the last will likely be respected. -t star|ascii|braille|braille6|braille8 The type of graph to draw, it defaults to star, which is the fastest one. star Scatter plot using only the '*' character. ascii Ascii is slightly prettier to look at. braille, braille6 Uses braille characters to draw higher resolu‐ tion plots. braille8 This is the most scatter-plot-ish with the highest res‐ olution, but also the most buggy. -w, --width width Specify a width for the output. If not specified, it will at‐ tempt to determine the TTY width and use that. If it cannot be automatically determined, it will fail. -h, --height height Specify a height for the output. If not specified, it will at‐ tempt to determine the TTY height and use that. If it cannot be automatically determined, it will fail. --color yes|no Enable or disable colors, by default color will be enabled if it looks like a tty is connected. It can therefore be nice to use --color yes if you are piping the output into another program that supports colors. EXAMPLES The simplest version is if you have a text file of values cat file | textgraph 2024-06-08 TEXTGRAPH(1) ```