termplot 0.1.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1e3e2ddb262dda39fcc498fb8fed6bd84c1023c97a21d1a2aa2a7bb2ba22c59
-  data.tar.gz: 87012dbfb94747ecc1d90530d7a199a74cd118a59e4ea8d2396b283519b1d628
+  metadata.gz: '068a1b08253b8e5993572546e7b73409b0ff5750a1aaa671d3d6c907b621128f'
+  data.tar.gz: a6ce340dac417d5999e7fd6018efd931731ecabcc2d894ff8430a5bd6c9d6bb3
 SHA512:
-  metadata.gz: fd4bdb6d311d03c7987fc3efcb0c6773d2abd40af2a13a5e7d9743ad4b6af0fce70ccd10414dded74bad0451f742ad50582cbc3e95813f8dfe1cfec115f322d5
-  data.tar.gz: bcc75b035ea812d163c5fb4bdbd7d35f387cce9d9d0b38938ce86acdd7005d2effb4f2b865344c7a6ce03c5de835a1a7a41535c444e4017eae9954105f755be2
+  metadata.gz: fe102cf42e2e1017ca2f3327c65847dbece92aeeea5de3c05b72e384bf3cfc6eb0dd602c7fa03585282ea747e88c167e8259e724ecbd30b64618c4dbce9ddc53
+  data.tar.gz: 13967f3be92508cc0fcc8dcc65eb9f0625ac359e30853ceaeed30e778863a7298eef38b55efe64d615ca61e9e37bcd781247c98b5e64967a46af9208deacf80c

data/.gitignore

@@ -8,3 +8,6 @@
 
 squiggles.txt
 Gemfile.lock
+README.md.html
+
+.ruby-version

data/README.md

@@ -1,16 +1,16 @@
 # Termplot
 
-Termplot is a simple terminal plotting tool for visualising streaming data.
+[![Gem Version](https://badge.fury.io/rb/termplot.svg)](https://badge.fury.io/rb/termplot)
 
-See the demo on Asciinema:
+Termplot is a simple terminal plotting tool for visualising streaming data.
 
-[![Termplot Demo Asciicast](https://asciinema.org/a/3rzeUSXp2fRjnErX0p3SptP5e.png)](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,83 +20,158 @@ 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` 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):
 ```
-{command} | 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: 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
 ```
 
-`{command}` is any command that will periodically output numbers to standard out
-delimited by a newline. Options and examples are given below. All command line
-options are optional.
+#### Examples
 
-Options:
+##### Plot a sine wave from standard in:
 
 ```
-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)
-  -t, --title TITLE       Title of the series (default: Series)
+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)
 
-      --line-style STYLE  Line style. Options are:
-                            line [default], heavy-line, dot, star, x
+##### 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)
+
+##### 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)
 
-      --color COLOR       Series color, specified as ansi 16-bit color name:
-                            (i.e. black, red [default], green, yellow, blue,
-                            magenta, cyan, white). Light versions are specified
-                            as light_{color}
 
-  -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]
 ```
 
-## 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](http://localhost:8080/doc/sin.png)
+![TCP Connections Plot](doc/tcp.png)
+
+##### Plot memory usage of process with PID 4396:
 
-Total % memory usage:
 ```
-while true; do \
-  free | awk 'NR==2 { print ($3/$2) * 100 }'; \
-  sleep 0.5; \
-  done | termplot -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
+```
+![Process Memory Plot](doc/memory.png)
+
+### Specify a multi-chart configuration 
+You can configure termplot to set up a multi-chart dashboard using a ruby
+configuration file:
+
+```
+termplot [--file/-f] FILE
 ```
-![Free Memory % Chart](http://localhost:8080/doc/memory.png)
 
-% CPU usage of a "puma" process:
+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
 ```
-while true; do \
-  ps au | grep puma | awk 'NR==1{ print $3 }'; \
-  sleep 0.5; \
-  done | termplot -t "Ruby CPU(%)" --color yellow --line-style dot -r10 -c 120
+Run it with:
 ```
-![CPU % Chart](http://localhost:8080/doc/cpu.png)
+termplot -f sample.rb --cols 150 --rows 20
+```
+
+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.
-- The `while true; do {...}; sleep INTERVAL` is pretty typical, I would like to
-  sometime soon implement a `--command "{...}" --interval INTERVAL` which would
-  reduce some of the boilerplate of calling some command at an interval and make
-  it easy to watch and plot.
+- 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
@@ -107,12 +182,13 @@ ruby.
 Now with termplot, it's as easy as:
 
 ```
-while true; do \
-  ss -s | head -n1 | cut -d ' ' -f2; sleep 1; \
-  done | termplot -t "TCP Connections"
+termplot --command 'ss -s | head -n1 | cut -d" " -f2' --interval 500 -t "TCP Connections"
 ```
 
-![TCP Connections](http://localhost:8080/doc/tcp.png)
+![TCP Connections](doc/tcp.png)
+
+In the end termplot turned out to be useful for all sorts of command line
+visualisation tasks.
 
 ## Development
 

data/Rakefile

@@ -1,18 +1,33 @@
+require_relative "./lib/termplot/commands"
 require "bundler/gem_tasks"
 
-task :bin do
-  Bundler.require(:default)
-  exec "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
 
+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,59 +1,25 @@
-require "optparse"
-require "termplot/consumer"
+# frozen_string_literal: true
+require "termplot/options"
+require "termplot/consumers"
 
 module Termplot
   class CLI
     def self.run
-      opts = self.parse_options
-      Consumer.new(**opts).run
+      options = Termplot::Options.new
+      options.parse_options!
+      run_consumer(options)
     end
 
     private
-    def self.parse_options
-      options = {
-        rows: 19,
-        cols: 80,
-        title: "Series",
-        line_style: "line",
-        color: "red",
-        debug: false
-      }
-      OptionParser.new do |opts|
-        opts.banner = "Usage: termplot [OPTIONS]"
 
-        opts.on("-rROWS", "--rows ROWS", "Number of rows in the chart window (default: 19)") do |v|
-          options[:rows] = v.to_i
-        end
-
-        opts.on("-cCOLS", "--cols COLS", "Number of cols in the chart window (default: 80)") do |v|
-          options[:cols] = v.to_i
-        end
-
-        opts.on("-tTITLE", "--title TITLE", "Title of the series (default: Series)") do |v|
-          options[:title] = v
-        end
-
-        opts.on("--line-style STYLE", "Line style. Options are: line [default], heavy-line, dot, star, x") do |v|
-          options[:line_style] = v.downcase
-        end
-
-        opts.on("--color COLOR", "Series color, specified as ansi 16-bit color name",
-                "(i.e. black, red [default], green, yellow, blue, magenta, cyan, white)",
-                "with light versions specified as light_{color}") do |v|
-          options[:color] = v.downcase
-        end
-
-        opts.on("-d", "--debug", "Enable debug mode, Logs window data to stdout instead of rendering") do |v|
-          options[:debug] = v
-        end
-
-        opts.on("-h", "--help", "Display this help message") do
-          puts opts
-          exit(0)
-        end
-
-      end.parse!
-      options
+    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

@@ -1,40 +1,43 @@
 module Termplot
   class Colors
-    class << self
-      COLORS = {
-        black:         0,
-        light_black:   60,
-        red:           1,
-        light_red:     61,
-        green:         2,
-        light_green:   62,
-        yellow:        3,
-        light_yellow:  63,
-        blue:          4,
-        light_blue:    64,
-        magenta:       5,
-        light_magenta: 65,
-        cyan:          6,
-        light_cyan:    66,
-        white:         7,
-        light_white:   67,
-        default:       9
-      }
+    COLORS = {
+      black:         0,
+      light_black:   60,
+      red:           1,
+      light_red:     61,
+      green:         2,
+      light_green:   62,
+      yellow:        3,
+      light_yellow:  63,
+      blue:          4,
+      light_blue:    64,
+      magenta:       5,
+      light_magenta: 65,
+      cyan:          6,
+      light_cyan:    66,
+      white:         7,
+      light_white:   67,
+      default:       9
+    }
 
-      MODES = {
-        default:   0,
-        bold:      1,
-        italic:    3,
-        underline: 4,
-        blink:     5,
-        swap:      7,
-        hide:      8
-      }
+    MODES = {
+      default:   0,
+      bold:      1,
+      italic:    3,
+      underline: 4,
+      blink:     5,
+      swap:      7,
+      hide:      8
+    }
 
+    class << self
       COLORS.each do |(color, code)|
         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