termplot 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af619edab0c7e963e4c03ba538d48ade05230afe5ef6e1572d39beffc4c56840
-  data.tar.gz: 1b138486f66e7db0423d27ffb25656486579cdf918d05d5744a24a14c42f7525
+  metadata.gz: dda87efbf9aed716a37a8ca65eab2d8f773f9e4a18ea9db6ab7aff4dc820c2ff
+  data.tar.gz: 82a897c92653354d77de8515cd370507aaba295f9a35425134af1a0752fb6d2a
 SHA512:
-  metadata.gz: 4550da91464682e063918b5655e27f14fcebae4d17905c6bb7584eed545030fa4212e43ce32d659cd53b10795aa1c8ffded70bdde53eca5400413b6aa65702d8
-  data.tar.gz: e41b6eae186fb4ce0dc69a2fb2851b96addc211f7304512ea6139d9588dc2e305ba9dcb382d96389ebe1783d865719ee6bdfa54619a2b1fa9dd772bc70fc6aed
+  metadata.gz: 16969163d4b669fd5cf930310af369aaa6e4a83d25e16bd51ba528d1ebb71c303d1beead130f4a9ef6d39992f7c92017fc149b2dbf0fcd46be6c0df15ed9b760
+  data.tar.gz: d509eeb9d34180fe4b338de314bcab5060e9f25a9d63d1ad4ff04e137c4d3b282209df7ff660a74a30e82c663d2eedd96fcc3d1204d8f3e16bf88d0ea47f1e76

data/.gitignore

@@ -8,3 +8,4 @@
 
 squiggles.txt
 Gemfile.lock
+README.md.html

data/README.md

@@ -2,15 +2,13 @@
 
 Termplot is a simple terminal plotting tool for visualising streaming data.
 
-See the demo on Asciinema:
-
-[![Termplot Demo Asciicast](https://asciinema.org/a/370325.svg)](https://asciinema.org/a/3rzeUSXp2fRjnErX0p3SptP5e)
+![Termplot Demo Image](doc/demo.png)
 
 ## Overview
 
-Termplot draws trendlines of data piped into the command from standard input.
-It's handy for quickly visualising streaming data in your terminal and works
-with any numeric data you can pipe into stdin.
+Termplot draws live plots of data in your terminal. It's handy for quickly
+visualising streaming data and works with any numeric data you can pipe into
+stdin or otherwise obtain by running a shell command.
 
 ## Installation
 
@@ -20,87 +18,156 @@ The tool is a ruby gem and can be installed with:
 
 ## Usage
 
-The basic usage is simple:
+There are 3 ways to provide input to termplot:
+- **Stdin:** Pipe data into standard input
+- **Command:** Specify a command to be ran at an interval
+- **Configuration file:** Read a multi-chart configuration from a file
 
+### Pipe data into standard input
 ```
-{command} | termplot [OPTIONS]
+COMMAND | termplot [OPTIONS]
 ```
 
-`{command}` is any command that will periodically output numbers to standard out
-delimited by a newline. You can also instead specify a command to run at a given
-interval to produce the data.
-
-Options and examples are given below. All command line options are
-optional.
+`COMMAND` is any command that will periodically output numbers to standard out
+delimited by a newline. These will be consumed by termplot and drawn to a chart. 
 
+You can specify the following options (all are optional):
+```
+    -r, --rows ROWS           Number of rows in the chart window (default: 19)
+    -c, --cols COLS           Number of cols in the chart window (default: 100)
+        --full-screen         Render to the full available terminal size
+
+        --type TYPE           The type of chart to render.
+                              Options are: timeseries (default), stats, hist
+
+        --timeseries          Shorthand for --type timeseries
+        --stats               Shorthand for --type stats
+        --hist                Shorthand for --type hist
+
+    -t, --title TITLE         Title of the series (default: 'Series')
+        --color COLOR         Series color, specified as ansi 16-bit color name:
+                              (i.e. black, light_black, red, light_red,
+                              green (default), light_green, yellow,
+                              light_yellow, blue, light_blue, magenta,
+                              light_magenta, cyan, light_cyan, white,
+                              light_white, default)
+
+        --line-style STYLE    Line style.
+                              Options are: line, heavy-line (default), dot, star, x, bar
 ```
-Usage: termplot [OPTIONS]
-  -r, --rows ROWS          Number of rows in the chart window (default: 19)
 
-  -c, --cols COLS          Number of cols in the chart window (default: 80)
+#### Examples
 
-  -t, --title TITLE        Title of the series (default: 'Series')
+##### Plot a sine wave from standard in:
 
-      --line-style STYLE   Line style. Options are: line (default), heavy-line, dot, star, x
+```
+for i in $(seq 500); do \
+  echo $i | awk '{ print sin($0/10) }'; \
+  sleep 0.5; \
+  done | termplot -t "Sin(x)" --color red
+```
+![Sine Wave Plot](doc/sin.png)
 
-      --color COLOR        Series color, specified as ansi 16-bit color name:
-                           (i.e. black, light_black, red (default), light_red, green,
-                           light_green, yellow, light_yellow, blue, light_blue, magenta,
-                           light_magenta, cyan, light_cyan, white, light_white, default)
+##### Plot histogram of network times as reported by `ping`:
+```
+ping example.com |
+  awk '{ split($8,arr,"="); print arr[2]; fflush("/dev/stdout") }' |
+  termplot -t "Ping Response Times (ms)" --hist
+```
+![Ping Response Times Plot](doc/ping.png)
 
-      --command COMMAND    Enables command mode, where input is received by executing
-                           the specified command in intervals rather than from stdin
+##### Plot histogram of data from column 33 of a CSV file
+```
+cat file.csv | cut -d, -f33 | tail -n +2 |
+  termplot -- --hist -r30 -t "Data" --color light_black
+```
+![File Data Plot](doc/file.png)
 
-      --interval INTERVAL  The interval at which to run the specified command in
-                           command mode in milliseconds (default: 1000)
 
-  -h, --help               Display this help message
+### Run command at an interval
+To run a command at an interval, specify `--command`, and optionally
+`--interval` to termplot:
+```
+termplot --command 'COMMAND' --interval INTERVAL [OPTIONS]
 ```
-Note: Make sure to wrap your command in single quotes when using `--command` if
-you use shell variables (e.g. `$1`) in your command.
 
-## Examples
+`COMMAND` will be invoked at the specified interval in milliseconds (default:
+1000) and its output will be used as the data for the chart. You can specify all
+the same additional options as in stdin mode above.
 
-#### Sine wave
+#### Examples
+##### Plot number of TCP connections over time:
 
 ```
-for i in $(seq 500); do \
-  echo $i | awk '{ print sin($0/10) }'; \
-  sleep 0.5; \
-  done | termplot -t "Sin(x)"
+termplot --command 'ss -s | head -n1 | cut -d" " -f2' \
+  --interval 500 -t "TCP Connections"
 ```
-![Sine Wave Plot](doc/sin.png)
+![TCP Connections Plot](doc/tcp.png)
+
+##### Plot memory usage of process with PID 4396:
 
-#### Memory usage (%)
 ```
-termplot --command 'free | awk "NR==2 { print ($3/$2) * 100 }"' \
-  -t "Memory (% used)" --color light_magenta --line-style heavy-line
+termplot --command "ps -q 4396 -o rss= | awk '{ print (\$0/1024.0) }'" \
+  -t "Process 4396 Memory (MB)" --color light_magenta
 ```
-![Free Memory % Chart](doc/memory.png)
+![Process Memory Plot](doc/memory.png)
 
-#### Real time stock ticker
+### Specify a multi-chart configuration 
+You can configure termplot to set up a multi-chart dashboard using a ruby
+configuration file:
 
-(Using [ticker.sh](https://github.com/pstadler/ticker.sh)) 😉:
+```
+termplot --file FILE
+```
 
+The configuration file uses a simple ruby DSL to arrange charts into rows and
+columns. Each chart will take a command and optionally an interval as well as
+formatting options. Termplot will then run the command at the specified interval
+and render the resulting data into the charts.
+
+Example file (sample.rb):
+```ruby
+col do
+  row do
+    cpu_command =
+      "top -b -n 1 | awk -F',' 'NR==3{ split($4, arr, \" \"); print 100.0 - arr[1] }'"
+
+    histogram  title: "CPU (%)", command: cpu_command, color: "light_cyan"
+    timeseries title: "CPU (%)", command: cpu_command, color: "light_cyan"
+    statistics title: "CPU (%)", command: cpu_command
+  end
+
+  row do
+    memory_command = "free | awk 'NR==2 { print ($3/$2) * 100 }'"
+
+    histogram  title: "Memory (%)", command: memory_command, color: "light_magenta"
+    timeseries title: "Memory (%)", command: memory_command, color: "light_magenta"
+    statistics title: "Memory (%)", command: memory_command
+  end
+end
+```
+Run it with:
 ```
-termplot --command 'NO_COLOR=1 ticker.sh MSFT | awk "{ print $2 }"' \
-  --interval 10000 -t "MSFT" --color light_green
+termplot -f sample.rb --cols 150 --rows 20
 ```
-![MSFT ticker chart](doc/MSFT.png)
+
+Result: 
+![CPU_Ram_dashboard](doc/dash.png)
+
 
 ## Notes
 
-- The command should work just fine if you have a monospaced unicode font.
+- Termplot should work just fine if you have a monospaced unicode font.
   Tested on linux, and should work on MacOS too. Not too sure about windows.
-- The samples received are plotted in sequence order, and there is no notion of
-  temporal spacing. So even if the time between samples is inconsistent, they
-  will be plotted with the same amount of space between them.
+- On timeseries plots, samples received are plotted in sequence order, and there
+  is no notion of temporal spacing. So even if the time between samples is
+  inconsistent, they will be plotted with the same amount of space between them.
 
-## Background
+## Background 
 
-I recently needed to be able to monitor the number of open TCP connections on my
-linux machine. I could get the data I needed from `ss` with some text processing
-but I didn't have a quick and easy way to eyeball the overall trend.
+A while back I needed to be able to monitor the number of open TCP connections
+on my linux machine. I could get the data I needed from `ss` with some text
+processing but I didn't have a quick and easy way to eyeball the overall trend.
 
 I mainly work with ruby, so taking
 inspiration from fantastic libraries like [Unicode Plots
@@ -116,6 +183,9 @@ termplot --command 'ss -s | head -n1 | cut -d" " -f2' --interval 500 -t "TCP Con
 
 ![TCP Connections](doc/tcp.png)
 
+In the end termplot turned out to be useful for all sorts of command line
+visualisation tasks.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. There are

data/Rakefile

@@ -1,20 +1,33 @@
+require_relative "./lib/termplot/commands"
 require "bundler/gem_tasks"
 
-task :bin do
-  exec "ruby", "-Ilib", "bin/termplot", *ARGV[2..-1]
-end
+extend Termplot::Commands
+extend Termplot::StdinCommands
 
-task :sin_test do
-  cmd = <<-CMD
-    for i in $(seq 5000);
-    do
-      echo $i | awk '{ print sin($0/10)* 10; fflush("/dev/stdout") }';
-      sleep 0.1;
-    done | ruby -Ilib bin/termplot -- -t 'sin(x)'
-  CMD
-  exec cmd
+SAMPLE_FILES_PATH = "examples"
+def termplot_binary
+  "ruby -Ilib bin/termplot"
 end
 
-task :command_test do
-  exec "ruby -Ilib bin/termplot --command 'echo $RANDOM' --interval 900"
+namespace :test do
+  task :bin do
+    exec "ruby", "-Ilib", "bin/termplot", *ARGV[2..-1]
+  end
+
+  task :file do
+    cmd = %( #{termplot_binary} -f #{File.join(SAMPLE_FILES_PATH, ARGV[2])} #{ARGV[3..-1].join(" ")})
+    exec cmd 
+  end
+
+  namespace :timeseries do
+    task :sin do
+      cmd = "#{sin(500)} | #{termplot_binary} -t 'sin(x)'"
+      exec cmd
+    end
+
+    task :random do
+      cmd = %( #{termplot_binary} --command '#{random}' --interval 900% )
+      exec cmd
+    end
+  end
 end

data/examples/sample.rb

@@ -0,0 +1,17 @@
+col do
+  row do
+    cpu_command = "top -b -n 1 | awk -F',' 'NR==3{ split($4, arr, \" \"); print 100.0 - arr[1] }'"
+
+    histogram  title: "CPU (%)", command: cpu_command, color: "light_cyan"
+    timeseries title: "CPU (%)", command: cpu_command, color: "light_cyan"
+    statistics title: "CPU (%)", command: cpu_command
+  end
+
+  row do
+    memory_command = "free | awk 'NR==2 { print ($3/$2) * 100 }'"
+
+    histogram  title: "Memory (%)", command: memory_command, color: "light_magenta"
+    timeseries title: "Memory (%)", command: memory_command, color: "light_magenta"
+    statistics title: "Memory (%)", command: memory_command
+  end
+end

data/lib/termplot/character_map.rb

@@ -12,7 +12,9 @@ module Termplot
       top_left:   "┌",
       bot_right:  "┘",
       tick_right: "┤",
-      extended:   true
+      tick_left:  "├",
+      extended:   true,
+      filled:     false
     }
     DEFAULT = LINE
 
@@ -26,13 +28,15 @@ module Termplot
       top_right:  "┓",
       top_left:   "┏",
       bot_right:  "┛",
-      tick_right: "┫"
+      tick_right: "┫",
+      tick_left:  "┣",
     )
 
     BASIC = {
       empty:      " ",
       point:      "•",
-      extended:   false
+      extended:   false,
+      filled:     false
     }
     DOTS = BASIC
 
@@ -44,12 +48,19 @@ module Termplot
       point: "*"
     )
 
+    BAR = LINE.merge(
+      point: "▄",
+      extended: false,
+      filled: true
+    )
+
     LINE_STYLES = {
       "line"       => LINE,
       "heavy-line" => HEAVY_LINE,
       "dot"        => DOTS,
       "star"       => STAR,
-      "x"          => X
+      "x"          => X,
+      "bar"        => BAR,
     }
   end
 end

data/lib/termplot/cli.rb

@@ -1,12 +1,25 @@
 # frozen_string_literal: true
 require "termplot/options"
-require "termplot/consumer"
+require "termplot/consumers"
 
 module Termplot
   class CLI
     def self.run
-      opts = Options.new.parse_options!
-      Consumer.new(opts).run
+      options = Termplot::Options.new
+      options.parse_options!
+      run_consumer(options)
+    end
+
+    private
+
+    CONSUMERS = {
+      file:    "Termplot::Consumers::MultiSourceConsumer",
+      command: "Termplot::Consumers::CommandConsumer",
+      stdin:   "Termplot::Consumers::StdinConsumer",
+    }
+    def self.run_consumer(options)
+      consumer = Object.const_get(CONSUMERS[options.input_mode])
+      consumer.new(options).run
     end
   end
 end

data/lib/termplot/colors.rb

@@ -35,6 +35,9 @@ module Termplot
         define_method(color) do |str|
           escape_color(color) + str + escape_mode(:default)
         end
+        define_method("#{color}_bg") do |str|
+          escape_bg_color(color) + str + escape_mode(:default)
+        end
       end
 
       def fetch(color, default)
@@ -47,6 +50,10 @@ module Termplot
         "\e[#{COLORS[color] + 30}m"
       end
 
+      def escape_bg_color(color)
+        "\e[#{COLORS[color] + 40}m"
+      end
+
       def escape_mode(mode)
         "\e[#{MODES[mode]}m"
       end

data/lib/termplot/commands.rb

@@ -0,0 +1,27 @@
+module Termplot
+  module Commands
+    def random
+      "echo $RANDOM"
+    end
+
+    def memory
+      "free | awk 'NR==2 { print ($3/$2) * 100 }'"
+    end
+
+    def cpu
+      "top -b -n 1 | awk -F',' 'NR==3{ split($4, arr, \" \"); print 100.0 - arr[1] }'"
+    end
+  end
+
+  module StdinCommands
+    def sin(n)
+      <<-CMD.chomp
+        for i in $(seq #{n});
+        do
+          echo $i | awk '{ print sin($0/10)* 10; fflush("/dev/stdout") }';
+          sleep 0.1;
+        done
+      CMD
+    end
+  end
+end