Use Dima's @debian.org email address for Uploaders

Maybe github fixed their bug already? I should check

Changes

@@ -1,3 +1,91 @@
+feedgnuplot (1.52)
+
+  * Added --squarexy and --square-xy as synonyms to --square_xy
+
+ -- Dima Kogan <dima@secretsauce.net>  Sun, 25 Aug 2019 15:32:37 -0700
+
+feedgnuplot (1.51)
+
+  * Added .gp "terminal" to create self-plotting gnuplot files
+
+ -- Dima Kogan <dima@secretsauce.net>  Sat, 29 Sep 2018 10:56:30 -0700
+
+feedgnuplot (1.50)
+
+  * Script waits for the plot window to close before exiting
+      Instead of sleeping forever. This is really nice! I no longer need
+      to quit the plot window AND then C-c. Quitting the plot window is
+      now sufficient
+  * by default --image sets range noextend
+  * tab-completion knows about the fnormal distribution
+
+ -- Dima Kogan <dkogan@debian.org>  Fri, 24 Aug 2018 13:11:05 -0700
+
+feedgnuplot (1.49)
+
+  * --vnl now works with plots that have rangesize > 1
+  * zsh completion: --xlen argument isn't optional
+
+ -- Dima Kogan <dima@secretsauce.net>  Fri, 16 Mar 2018 13:52:28 -0700
+
+feedgnuplot (1.48)
+
+  * --vnlog works properly with --domain
+
+ -- Dima Kogan <dima@secretsauce.net>  Sat, 24 Feb 2018 12:33:50 -0800
+
+feedgnuplot (1.47)
+
+  * Fixed typo. Everything is un-broken now
+
+ -- Dima Kogan <dima@secretsauce.net>  Fri, 23 Feb 2018 10:21:13 -0800
+
+feedgnuplot (1.46)
+
+  * Added --tuplesize and --tuplesizeall as alternatives to --rangesize
+    and --rangesizeall. Both forms are supported.
+  * Vnlog integration
+
+ -- Dima Kogan <dima@secretsauce.net>  Thu, 22 Feb 2018 23:37:54 -0800
+
+feedgnuplot (1.45)
+
+  * zsh completion: --hardcopy, --image  suggest filenames
+  * --image now produces a nicer legend: just the filename
+  * --curvestyle now overrides --curvestyleall
+    - This is a bug fix
+  * The version is now treated as a string not as a number
+    - So "1.40" is distinct from "1.4"
+
+ -- Dima Kogan <dima@secretsauce.net>  Sun, 29 Oct 2017 13:56:28 -0700
+
+feedgnuplot (1.44)
+
+  * --image draws its output beneath everything else
+
+ -- Dima Kogan <dima@secretsauce.net>  Tue, 20 Jun 2017 16:44:30 -0700
+
+feedgnuplot (1.43)
+
+  * Added --image
+
+ -- Dima Kogan <dima@secretsauce.net>  Mon, 19 Jun 2017 13:12:38 -0700
+
+feedgnuplot (1.42)
+
+  * Data can now come from STDIN or files on the cmdline.
+    This fixes a regression. Self-plotting data files work again
+
+ -- Dima Kogan <dima@secretsauce.net>  Fri, 31 Mar 2017 15:38:47 -0700
+
+feedgnuplot (1.41)
+
+  * Histograms: --xlen can coexist with --xmin/--xmax
+  * Histograms: work as expected with --xlen and --monotonic
+  * Histograms: better sanity checking of options
+
+ -- Dima Kogan <dima@secretsauce.net>  Fri, 24 Feb 2017 23:42:28 -0800
+
 feedgnuplot (1.40)
 
   * If the options couldn't be parsed I don't dump the whole manpage
@@ -16,8 +104,8 @@ feedgnuplot (1.39)
 feedgnuplot (1.38)
 
   * hardcopy defaults:
-   - no enhanced text mode
-   - larger font size
+    - no enhanced text mode
+    - larger font size
 
  -- Dima Kogan <dima@secretsauce.net>  Wed, 27 Jul 2016 22:15:11 -0700
 

INSTALL

@@ -10,4 +10,11 @@ Without a package, an installation can be done with
          make
          make install
 
-This installs feedgnuplot to /usr/local. Adjust the paths as required
+This installs feedgnuplot to /usr/local. Adjust the paths as required.
+
+Also, note that this is a self-contained utility. Usually running from the tree
+works just fine:
+
+         git clone https://github.com/dkogan/feedgnuplot.git
+         cd feedgnuplot/bin
+         ./feedgnuplot ...

Makefile.PL

@@ -20,9 +20,9 @@ sub parseversion
 
   while(<PL>)
   {
-    if( /VERSION = ([0-9\.]+)/ )
+    if( /VERSION = '([0-9\.]+)'/ )
     {
-      if ( $1 != $version )
+      if ( $1 ne $version )
       {
         die "Version mismatch. Changes says version is '$version', but 'bin/feedgnuplot' says it is '$1'";
       }

README.pod

@@ -1 +0,0 @@
-bin/feedgnuplot

README.pod

@@ -0,0 +1,987 @@
+=head1 TALK
+
+I just gave a talk about this at L<SCaLE
+17x|https://www.socallinuxexpo.org/scale/17x>. Presentation lives
+L<here|https://github.com/dkogan/talk-feedgnuplot-vnlog/blob/master/feedgnuplot-vnlog.org>.
+
+=head1 NAME
+
+feedgnuplot - General purpose pipe-oriented plotting tool
+
+=head1 SYNOPSIS
+
+Simple plotting of piped data:
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}'
+ 2 1
+ 4 4
+ 6 9
+ 8 16
+ 10 25
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}' |
+   feedgnuplot --lines --points --legend 0 "data 0" --title "Test plot" --y2 1
+               --unset grid --terminal 'dumb 80,40' --exit
+
+                                  Test plot
+
+  10 +-----------------------------------------------------------------+ 25
+     |       +        +       +       +       +        +       +    *##|
+     |                                                  data 0 ***A*#* |
+     |                                                          ** #   |
+   9 |-+                                                      ** ##    |
+     |                                                      **  #      |
+     |                                                    **   #       |
+     |                                                  **   ##      +-| 20
+   8 |-+                                               A    #          |
+     |                                               **    #           |
+     |                                             **    ##            |
+     |                                           **     #              |
+     |                                         **      B               |
+   7 |-+                                     **      ##                |
+     |                                     **      ##                +-| 15
+     |                                   **       #                    |
+     |                                 **       ##                     |
+   6 |-+                             *A       ##                       |
+     |                             **       ##                         |
+     |                           **        #                           |
+     |                         **        ##                          +-| 10
+   5 |-+                     **        ##                              |
+     |                     **        #B                                |
+     |                   **        ##                                  |
+     |                 **        ##                                    |
+   4 |-+              A       ###                                      |
+     |              **      ##                                         |
+     |            **      ##                                         +-| 5
+     |          **      ##                                             |
+     |        **    ##B#                                               |
+   3 |-+    **  ####                                                   |
+     |    **####                                                       |
+     |  ####                                                           |
+     |##     +        +       +       +       +        +       +       |
+   2 +-----------------------------------------------------------------+ 0
+     1      1.5       2      2.5      3      3.5       4      4.5      5
+
+
+Simple real-time plotting example: plot how much data is received on the wlan0
+network interface in bytes/second (uses bash, awk and Linux):
+
+ $ while true; do sleep 1; cat /proc/net/dev; done |
+   gawk '/wlan0/ {if(b) {print $2-b; fflush()} b=$2}' |
+   feedgnuplot --lines --stream --xlen 10 --ylabel 'Bytes/sec' --xlabel seconds
+
+=head1 DESCRIPTION
+
+This is a flexible, command-line-oriented frontend to Gnuplot. It creates
+plots from data coming in on STDIN or given in a filename passed on the
+commandline. Various data representations are supported, as is hardcopy
+output and streaming display of live data. A simple example:
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}' | feedgnuplot
+
+You should see a plot with two curves. The C<awk> command generates some data to
+plot and the C<feedgnuplot> reads it in from STDIN and generates the plot. The
+C<awk> invocation is just an example; more interesting things would be plotted
+in normal usage. No commandline-options are required for the most basic
+plotting. Input parsing is flexible; every line need not have the same number of
+points. New curves will be created as needed.
+
+The most commonly used functionality of gnuplot is supported directly by the
+script. Anything not directly supported can still be done with options such as
+C<--set>, C<--extracmds> C<--style>, etc. Arbitrary gnuplot commands can be
+passed in with C<--extracmds>. For example, to turn off the grid, you can pass
+in C<--extracmds 'unset grid'>. Commands C<--set> and C<--unset> exists to
+provide nicer syntax, so this is equivalent to passing C<--unset grid>. As many
+of these options as needed can be passed in. To add arbitrary curve styles, use
+C<--style curveID extrastyle>. Pass these more than once to affect more than one
+curve.
+
+To apply an extra style to I<all> the curves that lack an explicit C<--style>,
+pass in C<--styleall extrastyle>. In the most common case, the extra style is
+C<with something>. To support this more simply, you can pass in C<--with
+something> instead of C<--styleall 'with something'>. C<--styleall> and
+C<--with> are mutually exclusive. Furthermore any curve-specific C<--style>
+overrides the global C<--styleall> or C<--with> setting.
+
+=head2 Data formats
+
+By default, each value present in the incoming data represents a distinct data
+point, as demonstrated in the original example above (we had 10 numbers in the
+input and 10 points in the plot). If requested, the script supports more
+sophisticated interpretation of input data
+
+=head3 Domain selection
+
+If C<--domain> is passed in, the first value on each line of input is
+interpreted as the I<X>-value for the rest of the data on that line. Without
+C<--domain> the I<X>-value is the line number, and the first value on a line is
+a plain data point like the others. Default is C<--nodomain>. Thus the original
+example above produces 2 curves, with B<1,2,3,4,5> as the I<X>-values. If we run
+the same command with C<--domain>:
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}' | feedgnuplot --domain
+
+we get only 1 curve, with B<2,4,6,8,10> as the I<X>-values. As many points as
+desired can appear on a single line, but all points on a line are associated
+with the I<X>-value at the start of that line.
+
+=head3 Curve indexing
+
+We index the curves in one of 3 ways: sequentially, explicitly with a
+C<--dataid> or by C<--vnlog> headers.
+
+By default, each column represents a separate curve. The first column (after any
+domain) is curve C<0>. The next one is curve C<1> and so on. This is fine unless
+sparse data is to be plotted. With the C<--dataid> option, each point is
+represented by 2 values: a string identifying the curve, and the value itself.
+If we add C<--dataid> to the original example:
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}' | feedgnuplot --dataid --autolegend
+
+we get 5 different curves with one point in each. The first column, as produced
+by C<awk>, is B<2,4,6,8,10>. These are interpreted as the IDs of the curves to
+be plotted.
+
+If we're plotting C<vnlog> data (L<https://www.github.com/dkogan/vnlog>) then we
+can get the curve IDs from the vnlog header. Vnlog is a trivial data format
+where lines starting with C<#> are comments and the first comment contains
+column labels. If we have such data, C<feedgnuplot --vnlog> can interpret these
+column labels if the C<vnlog> perl modules are available.
+
+The C<--autolegend> option adds a legend using the given IDs to
+label the curves. The IDs need not be numbers; generic strings are accepted. As
+many points as desired can appear on a single line. C<--domain> can be used in
+conjunction with C<--dataid> or C<--vnlog>.
+
+=head3 Multi-value style support
+
+Depending on how gnuplot is plotting the data, more than one value may be needed
+to represent the range of a single point. Basic 2D plots have 2 numbers
+representing each point: 1 domain and 1 range. But if plotting with
+C<--circles>, for instance, then there's an extra range value: the radius. Many
+other gnuplot styles require more data: errorbars, variable colors (C<with
+points palette>), variable sizes (C<with points ps variable>), labels and so on.
+The feedgnuplot tool itself does not know about all these intricacies, but they
+can still be used, by specifying the specific style with C<--style>, and
+specifying how many values are needed for each point with any of
+C<--rangesizeall>, C<--tuplesizeall>, C<--rangesize>, C<--tuplesize>. These
+options are required I<only> for styles not explicitly supported by feedgnuplot;
+supported styles do the right thing automatically.
+
+Specific example: if making a 2d plot of y error bars, the exact format can be
+queried by running C<gnuplot> and invoking C<help yerrorbars>. This tells us
+that there's a 3-column form: C<x y ydelta> and a 4-column form: C<x y ylow
+yhigh>. With 2d plots feedgnuplot will always output the 1-value domain C<x>, so
+the rangesize is 2 and 3 respectively. Thus the following are equivalent:
+
+ $ echo '1 2 0.3
+         2 3 0.4
+         3 4 0.5' | feedgnuplot --domain --rangesizeall 2 --with 'yerrorbars'
+
+ $ echo '1 2 0.3
+         2 3 0.4
+         3 4 0.5' | feedgnuplot --domain --tuplesizeall 3 --with 'yerrorbars'
+
+ $ echo '1 2 1.7 2.3
+         2 3 2.6 3.4
+         3 4 3.5 4.5' | feedgnuplot --domain --rangesizeall 3 --with 'yerrorbars'
+
+=head3 3D data
+
+To plot 3D data, pass in C<--3d>. C<--domain> MUST be given when plotting 3D
+data to avoid domain ambiguity. If 3D data is being plotted, there are by
+definition 2 domain values instead of one (I<Z> as a function of I<X> and I<Y>
+instead of I<Y> as a function of I<X>). Thus the first 2 values on each line are
+interpreted as the domain instead of just 1. The rest of the processing happens
+the same way as before.
+
+=head3 Time/date data
+
+If the input data domain is a time/date, this can be interpreted with
+C<--timefmt>. This option takes a single argument: the format to use to parse
+the data. The format is documented in 'set timefmt' in gnuplot, although the
+common flags that C<strftime> understands are generally supported. The backslash
+sequences in the format are I<not> supported, so if you want a tab, put in a tab
+instead of \t. Whitespace in the format I<is> supported. When this flag is
+given, some other options act a little bit differently:
+
+=over
+
+=item
+
+C<--xlen> is an I<integer> in seconds
+
+=item
+
+C<--xmin> and C<--xmax> I<must> use the format passed in to C<--timefmt>
+
+=back
+
+Using this option changes both the way the input is parsed I<and> the way the
+x-axis tics are labelled. Gnuplot tries to be intelligent in this labelling, but
+it doesn't always do what the user wants. The labelling can be controlled with
+the gnuplot C<set format> command, which takes the same type of format string as
+C<--timefmt>. Example:
+
+ $ sar 1 -1 |
+   awk '$1 ~ /..:..:../ && $8 ~/^[0-9\.]*$/ {print $1,$8; fflush()}' |
+   feedgnuplot --stream --domain
+                --lines --timefmt '%H:%M:%S'
+                --set 'format x "%H:%M:%S"'
+
+This plots the 'idle' CPU consumption against time.
+
+Note that while gnuplot supports the time/date on any axis, I<feedgnuplot>
+currently supports it I<only> as the x-axis domain. This may change in the
+future.
+
+=head2 Real-time streaming data
+
+To plot real-time data, pass in the C<--stream [refreshperiod]> option. Data
+will then be plotted as it is received. The plot will be updated every
+C<refreshperiod> seconds. If the period isn't specified, a 1Hz refresh rate is
+used. To refresh at specific intervals indicated by the data, set the
+refreshperiod to 0 or to 'trigger'. The plot will then I<only> be refreshed when
+a data line 'replot' is received. This 'replot' command works in both triggered
+and timed modes, but in triggered mode, it's the only way to replot. Look in
+L</"Special data commands"> for more information.
+
+To plot only the most recent data (instead of I<all> the data), C<--xlen
+windowsize> can be given. This will create an constantly-updating, scrolling
+view of the recent past. C<windowsize> should be replaced by the desired length
+of the domain window to plot, in domain units (passed-in values if C<--domain>
+or line numbers otherwise). If the domain is a time/date via C<--timefmt>, then
+C<windowsize> is and I<integer> in seconds. If we're plotting a histogram, then
+C<--xlen> causes a histogram over a moving window to be computed. The subtlely
+here is that with a histogram you don't actually I<see> the domain since only
+the range is analyzed. But the domain is still there, and can be utilized with
+C<--xlen>. With C<--xlen> we can plot I<only> histograms or I<only>
+I<non>-histograms.
+
+=head3 Special data commands
+
+If we are reading streaming data, the input stream can contain special commands
+in addition to the raw data. Feedgnuplot looks for these at the start of every
+input line. If a command is detected, the rest of the line is discarded. These
+commands are
+
+=over
+
+=item C<replot>
+
+This command refreshes the plot right now, instead of waiting for the next
+refresh time indicated by the timer. This command works in addition to the timed
+refresh, as indicated by C<--stream [refreshperiod]>.
+
+=item C<clear>
+
+This command clears out the current data in the plot. The plotting process
+continues, however, to any data following the C<clear>.
+
+=item C<exit>
+
+This command causes feedgnuplot to exit.
+
+=back
+
+=head2 Hardcopy output
+
+The script is able to produce hardcopy output with C<--hardcopy outputfile>. The
+output type can be inferred from the filename, if B<.ps>, B<.eps>, B<.pdf>,
+B<.svg>, B<.png> or B<.gp> is requested. If any other file type is requested,
+C<--terminal> I<must> be passed in to tell gnuplot how to make the plot. If
+C<--terminal> is passed in, then the C<--hardcopy> argument only provides the
+output filename.
+
+The B<.gp> output is special. Instead of asking gnuplot to plot to a particular
+terminal, writing to a B<.gp> simply dumps a self-executable gnuplot script into
+the given file. This is similar to what C<--dump> does, but writes to a file,
+and makes sure that the file can be self-executing.
+
+=head2 Self-plotting data files
+
+This script can be used to enable self-plotting data files. There are several
+ways of doing this: with a shebang (#!) or with inline perl data.
+
+=head3 Self-plotting data with a #!
+
+A self-plotting, executable data file C<data> is formatted as
+
+ $ cat data
+ #!/usr/bin/feedgnuplot --lines --points
+ 2 1
+ 4 4
+ 6 9
+ 8 16
+ 10 25
+ 12 36
+ 14 49
+ 16 64
+ 18 81
+ 20 100
+ 22 121
+ 24 144
+ 26 169
+ 28 196
+ 30 225
+
+This is the shebang (#!) line followed by the data, formatted as before. The
+data file can be plotted simply with
+
+ $ ./data
+
+The caveats here are that on Linux the whole #! line is limited to 127
+characters and that the full path to feedgnuplot must be given. The 127
+character limit is a serious limitation, but this can likely be resolved with a
+kernel patch. I have only tried on Linux 2.6.
+
+=head3 Self-plotting data with gnuplot
+
+Running C<feedgnuplot --hardcopy plotdata.gp ....> will create a self-executable
+gnuplot script in C<plotdata.gp>
+
+=head3 Self-plotting data with perl inline data
+
+Perl supports storing data and code in the same file. This can also be used to
+create self-plotting files:
+
+ $ cat plotdata.pl
+ #!/usr/bin/perl
+ use strict;
+ use warnings;
+
+ open PLOT, "| feedgnuplot --lines --points" or die "Couldn't open plotting pipe";
+ while( <DATA> )
+ {
+   my @xy = split;
+   print PLOT "@xy\n";
+ }
+ __DATA__
+ 2 1
+ 4 4
+ 6 9
+ 8 16
+ 10 25
+ 12 36
+ 14 49
+ 16 64
+ 18 81
+ 20 100
+ 22 121
+ 24 144
+ 26 169
+ 28 196
+ 30 225
+
+This is especially useful if the logged data is not in a format directly
+supported by feedgnuplot. Raw data can be stored after the __DATA__ directive,
+with a small perl script to manipulate the data into a useable format and send
+it to the plotter.
+
+=head1 ARGUMENTS
+
+=over
+
+=item
+
+--C<[no]domain>
+
+If enabled, the first element of each line is the domain variable. If not, the
+point index is used
+
+=item
+
+--C<[no]dataid>
+
+If enabled, each data point is preceded by the ID of the data set that point
+corresponds to. This ID is interpreted as a string, NOT as just a number. If not
+enabled, the order of the point is used.
+
+As an example, if line 3 of the input is "0 9 1 20" then
+
+=over
+
+=item
+
+C<--nodomain --nodataid> would parse the 4 numbers as points in 4 different
+curves at x=3
+
+=item
+
+C<--domain --nodataid> would parse the 4 numbers as points in 3 different
+curves at x=0. Here, 0 is the x-variable and 9,1,20 are the data values
+
+=item
+
+C<--nodomain --dataid> would parse the 4 numbers as points in 2 different
+curves at x=3. Here 0 and 1 are the data IDs and 9 and 20 are the
+data values
+
+=item
+
+C<--domain --dataid> would parse the 4 numbers as a single point at
+x=0. Here 9 is the data ID and 1 is the data value. 20 is an extra
+value, so it is ignored. If another value followed 20, we'd get another
+point in curve ID 20
+
+=back
+
+=item
+
+C<--vnlog>
+
+Vnlog is a trivial data format where lines starting with C<#> are comments and
+the first comment contains column labels. Some tools for working with such data
+are available from the C<vnlog> project: L<https://www.github.com/dkogan/vnlog>.
+With the C<vnlog> perl modules installed, we can read the vnlog column headers
+with C<feedgnuplot --vnlog>. This replaces C<--dataid>, and we can do all the
+normal things with these headers. For instance C<feedgnuplot --vnlog
+--autolegend> will generate plot legends for each column in the vnlog, using the
+vnlog column label in the legend.
+
+=item
+
+C<--[no]3d>
+
+Do [not] plot in 3D. This only makes sense with C<--domain>. Each domain here is
+an (x,y) tuple
+
+=item
+
+--C<timefmt [format]>
+
+Interpret the X data as a time/date, parsed with the given format
+
+=item
+
+C<--colormap>
+
+Show a colormapped xy plot. Requires extra data for the color. zmin/zmax can be
+used to set the extents of the colors. Automatically sets the
+C<--rangesize>/C<--tuplesize>.
+
+=item
+
+C<--stream [period]>
+
+Plot the data as it comes in, in realtime. If period is given, replot every
+period seconds. If no period is given, replot at 1Hz. If the period is given as
+0 or 'trigger', replot I<only> when the incoming data dictates this. See the
+L</"Real-time streaming data"> section of the man page.
+
+=item
+
+C<--[no]lines>
+
+Do [not] draw lines to connect consecutive points
+
+=item
+
+C<--[no]points>
+
+Do [not] draw points
+
+=item
+
+C<--circles>
+
+Plot with circles. This requires a radius be specified for each point.
+Automatically sets the C<--rangesize>/C<--tuplesize>. C<Not> supported for 3d
+plots.
+
+=item
+
+C<--title xxx>
+
+Set the title of the plot
+
+=item
+
+C<--legend curveID legend>
+
+Set the label for a curve plot. Use this option multiple times for multiple
+curves. With C<--dataid>, curveID is the ID. Otherwise, it's the index of the
+curve, starting at 0
+
+=item
+
+C<--autolegend>
+
+Use the curve IDs for the legend. Titles given with C<--legend> override these
+
+=item
+
+C<--xlen xxx>
+
+When using C<--stream>, sets the size of the x-window to plot. Omit this or set
+it to 0 to plot ALL the data. Does not make sense with 3d plots. Implies
+C<--monotonic>. If we're plotting a histogram, then C<--xlen> causes a histogram
+over a moving window to be computed. The subtlely here is that with a histogram
+you don't actually I<see> the domain since only the range is analyzed. But the
+domain is still there, and can be utilized with C<--xlen>. With C<--xlen> we can
+plot I<only> histograms or I<only> I<non>-histograms.
+
+
+=item
+
+C<--xmin/xmax/ymin/ymax/y2min/y2max/zmin/zmax xxx>
+
+Set the range for the given axis. These x-axis bounds are ignored in a streaming
+plot. The y2-axis bound do not apply in 3d plots. The z-axis bounds apply
+I<only> to 3d plots or colormaps. Note that there is no C<--xrange> to set both
+sides at once or C<--xinv> to flip the axis around: anything more than the
+basics supported in this option is clearly obtainable by talking to gnuplot, for
+instance C<--set 'xrange [20:10]'> to set the given inverted bounds.
+
+=item
+
+C<--xlabel/ylabel/y2label/zlabel xxx>
+
+Label the given axis. The y2-axis label does not apply to 3d plots while the
+z-axis label applies I<only> to 3d plots.
+
+=item
+
+C<--y2 xxx>
+
+Plot the data specified by this curve ID on the y2 axis. Without C<--dataid>,
+the ID is just an ordered 0-based index. Does not apply to 3d plots. Can be
+passed multiple times, or passed a comma-separated list. By default the y2-axis
+curves look the same as the y-axis ones. I.e. the viewer of the resulting plot
+has to be told which is which via an axes label, legend, etc. Prior to version
+1.25 of feedgnuplot the curves plotted on the y2 axis were drawn with a thicker
+line. This is no longer the case, but that behavior can be brought back by
+passing something like
+
+ --y2 curveid --style curveid 'linewidth 3'
+
+=item
+
+C<--histogram curveID>
+
+Set up a this specific curve to plot a histogram. The bin width is given with
+the C<--binwidth> option (assumed 1.0 if omitted). If a drawing style is not
+specified for this curve (C<--curvestyle>) or all curves (C<--with>,
+C<--curvestyleall>) then the default histogram style is set: filled boxes with
+borders. This is what the user generally wants. This works with C<--domain>
+and/or C<--stream>, but in those cases the x-value is used I<only> to cull old
+data because of C<--xlen> or C<--monotonic>. I.e. the domain values are I<not>
+drawn in any way. Can be passed multiple times, or passed a comma- separated
+list
+
+=item
+
+C<--binwidth width>
+
+The width of bins when making histograms. This setting applies to ALL histograms
+in the plot. Defaults to 1.0 if not given.
+
+=item
+
+C<--histstyle style>
+
+Normally, histograms are generated with the 'smooth frequency' gnuplot style.
+C<--histstyle> can be used to select different C<smooth> settings (see the
+gnuplot C<help smooth> page for more info). Allowed values are 'frequency' (the
+default), 'fnormal' (available in very recent gnuplots), 'unique', 'cumulative'
+and 'cnormal'. 'fnormal' is a normalized histogram. 'unique' indicates whether a
+bin has at least one item in it: instead of counting the items, it'll always
+report 0 or 1. 'cumulative' is the integral of the 'frequency' histogram.
+'cnormal' is like 'cumulative', but rescaled to end up at 1.0.
+
+=item
+
+C<--style curveID style>
+
+Additional styles per curve. With C<--dataid>, curveID is the ID. Otherwise,
+it's the index of the curve, starting at 0. curveID can be a comma-separated
+list of IDs to which the given style should apply. Use this option multiple
+times for multiple curves. C<--styleall> does I<not> apply to curves that have a
+C<--style>.
+
+=item
+
+C<--curvestyle curveID>
+
+Synonym for C<--style>
+
+=item
+
+C<--styleall xxx>
+
+Additional styles for all curves that have no C<--style>. This is overridden by
+any applicable C<--style>. Exclusive with C<--with>.
+
+=item
+
+C<--curvestyleall xxx>
+
+Synonym for C<--styleall>
+
+=item
+
+C<--with xxx>
+
+Same as C<--styleall>, but prefixed with "with". Thus
+
+ --with boxes
+
+is equivalent to
+
+ --styleall 'with boxes'
+
+Exclusive with C<--styleall>.
+
+=item
+
+C<--extracmds xxx>
+
+Additional commands to pass on to gnuplot verbatim. These could contain extra
+global styles for instance. Can be passed multiple times.
+
+=item
+
+C<--set xxx>
+
+Additional 'set' commands to pass on to gnuplot verbatim. C<--set 'a b c'> will
+result in gnuplot seeing a C<set a b c> command. Can be passed multiple times.
+
+=item
+
+C<--unset xxx>
+
+Additional 'unset' commands to pass on to gnuplot verbatim. C<--unset 'a b c'>
+will result in gnuplot seeing a C<unset a b c> command. Can be passed multiple
+times.
+
+=item
+
+C<--image filename>
+
+Overlays the data on top of a raster image given in C<filename>. This is passed
+through to gnuplot via C<--equation>, and is not interpreted by C<feedgnuplot>
+other than checking for existence. Usually images have their origin at the
+top-left corner, while plots have it in the bottom-left corner instead. Thus if
+the y-axis extents are not specified (C<--ymin>, C<--ymax>, C<--set 'yrange
+...'>) this option will also flip around the y axis to make the image appear
+properly. Since this option is just a passthrough to gnuplot, finer control can
+be achieved by passing in C<--equation> and C<--set yrange ...> directly.
+
+C<--equation xxx>
+
+Gnuplot can plot both data and symbolic equations. C<feedgnuplot> generally
+plots data, but with this option can plot symbolic equations I<also>. This is
+generally intended to augment data plots, since for equation-only plots you
+don't need C<feedgnuplot>. C<--equation> can be passed multiple times for
+multiple equations. The given strings are passed to gnuplot directly without
+anything added or removed, so styling and such should be applied in the string.
+A basic example:
+
+ seq 100 | awk '{print $1/10, $1/100}' |
+   feedgnuplot --with 'lines lw 3' --domain --ymax 1
+               --equation 'sin(x)/x' --equation 'cos(x)/x with lines lw 4'
+
+Here I plot the incoming data (points along a line) with the given style (a line
+with thickness 3), I<and> I plot two damped sinusoids on the same plot. The
+sinusoids are not affected by C<feedgnuplot> styling, so their styles are set
+separately, as in this example. More complicated example:
+
+ seq 360 | perl -nE '$th=$_/360 * 3.14*2; $c=cos($th); $s=sin($th); say "$c $s"' |
+   feedgnuplot --domain --square
+               --set parametric --set "trange [0:2*3.14]" --equation "sin(t),cos(t)"
+
+Here the data I generate is points along the unit circle. I plot these as
+points, and I I<also> plot a true circle as a parametric equation.
+
+=item
+
+C<--square>
+
+Plot data with aspect ratio 1. For 3D plots, this controls the aspect ratio for
+all 3 axes
+
+=item
+
+C<--square-xy>
+
+For 3D plots, set square aspect ratio for ONLY the x,y axes
+
+=item
+
+C<--hardcopy xxx>
+
+If not streaming, output to a file specified here. Format inferred from
+filename, unless specified by C<--terminal>. If C<--terminal> is given,
+C<--hardcopy> sets I<only> the output filename.
+
+=item
+
+C<--terminal xxx>
+
+String passed to 'set terminal'. No attempts are made to validate this.
+C<--hardcopy> sets this to some sensible defaults if C<--hardcopy> is set to a
+filename ending in C<.png>, C<.pdf>, C<.ps>, C<.eps> or C<.svg>. If any other
+file type is desired, use both C<--hardcopy> and C<--terminal>
+
+=item
+
+C<--maxcurves N>
+
+The maximum allowed number of curves. This is 100 by default, but can be reset
+with this option. This exists purely to prevent perl from allocating all of the
+system's memory when reading bogus data
+
+=item
+
+C<--monotonic>
+
+If C<--domain> is given, checks to make sure that the x-coordinate in the input
+data is monotonically increasing. If a given x-variable is in the past, all data
+currently cached for this curve is purged. Without C<--monotonic>, all data is
+kept. Does not make sense with 3d plots. No C<--monotonic> by default. The data
+is replotted before being purged. This is useful in streaming plots where the
+incoming data represents multiple iterations of the same process (repeated
+simulations of the same period in time, for instance).
+
+=item
+
+C<--rangesize curveID N>
+
+The options C<--rangesizeall> and C<--rangesize> set the number of values are
+needed to represent each point being plotted (see L</"Multi-value style
+support"> above). These options are I<only> needed if unknown styles are used,
+with C<--styleall> or C<--with> for instance.
+
+C<--rangesize> is used to set how many values are needed to represent the range
+of a point for a particular curve. This overrides any defaults that may exist
+for this curve only.
+
+With C<--dataid>, curveID is the ID. Otherwise, it's the index of the curve,
+starting at 0. curveID can be a comma-separated list of IDs to which the given
+rangesize should apply.
+
+=item
+
+C<--tuplesize curveID N>
+
+Very similar to C<--rangesize>, but instead of specifying the I<range> only,
+this specifies the whole tuple. For instance if we're plotting circles, the
+tuplesize is 3: C<x,y,radius>. In a 2D plot there's a 1-dimensional domain:
+C<x>, so the rangesize is 2: C<y,radius>. This dimensionality can be given
+either way.
+
+=item
+
+C<--rangesizeall N>
+
+Like C<--rangesize>, but applies to I<all> the curves.
+
+=item
+
+C<--tuplesizeall N>
+
+Like C<--tuplesize>, but applies to I<all> the curves.
+
+=item
+
+C<--dump>
+
+Instead of printing to gnuplot, print to STDOUT. Very useful for debugging. It
+is possible to send the output produced this way to gnuplot directly.
+
+=item
+
+C<--exit>
+
+This controls what happens when the input data is exhausted, or when some part
+of the C<feedgnuplot> pipeline is killed. This option does different things
+depending on whether C<--stream> is active, so read this closely.
+
+With interactive gnuplot terminals (qt, x11, wxt), the plot windows live in a
+separate process from the main C<gnuplot> process. It is thus possible for the
+main C<gnuplot> process to exit, while leaving the plot windows up (a caveat is
+that such decapitated windows aren't interactive). There are 3 possible states
+of the polotting pipeline:
+
+=over
+
+=item Alive: C<feedgnuplot>, C<gnuplot> alive, plot window process alive, no
+shell prompt (shell busy with C<feedgnuplot>)
+
+=item Half-alive: C<feedgnuplot>, C<gnuplot> dead, plot window process alive
+(but non-interactive), shell prompt available
+
+=item Dead: C<feedgnuplot>, C<gnuplot> dead, plot window process dead, shell
+prompt available
+
+=back
+
+The possibilities are:
+
+=over
+
+=item No C<--stream>, all data read in
+
+=over
+
+=item no C<--exit> (default)
+
+Alive. Need to Ctrl-C to get back into the shell
+
+=item C<--exit>
+
+Half-alive. Non-interactive prompt up, and the shell accepts new commands.
+Without C<--stream> the goal is to show a plot, so a Dead state would not be
+useful.
+
+=back
+
+=item C<--stream>, all data read in or the C<feedgnuplot> process terminated
+
+=over
+
+=item no C<--exit> (default)
+
+Alive. Need to Ctrl-C to get back into the shell. This means that when making
+live plots, the first Ctrl-C kills the data feeding process, but leaves the
+final plot up for inspection. A second Ctrl-C kills feedgnuplot as well.
+
+=item C<--exit>
+
+Dead. No plot is shown, and the shell accepts new commands. With C<--stream> the
+goal is to show a plot as the data comes in, which we have been doing. Now that
+we're done, we can clean up everything.
+
+=back
+
+=back
+
+Note that one usually invokes C<feedgnuplot> as a part of a shell pipeline:
+
+ $ write_data | feedgnuplot
+
+If the user terminates this pipeline with ^C, then I<all> the processes in the
+pipeline receive SIGINT. This normally kills C<feedgnuplot> and all its
+C<gnuplot> children, and we let this happen unless C<--stream> and no C<--exit>.
+If C<--stream> and no C<--exit>, then we ignore the first ^C. The data feeder
+dies, and we behave as if the input data was exhausted. A second ^C kills us
+also.
+
+=item
+
+C<--geometry>
+
+If using X11, specifies the size, position of the plot window
+
+=item
+
+C<--version>
+
+Print the version and exit
+
+=back
+
+=head1 RECIPES
+
+=head2 Basic plotting of piped data
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}'
+ 2 1
+ 4 4
+ 6 9
+ 8 16
+ 10 25
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}' |
+   feedgnuplot --lines --points --legend 0 "data 0" --title "Test plot" --y2 1
+
+=head2 Realtime plot of network throughput
+
+Looks at wlan0 on Linux.
+
+ $ while true; do sleep 1; cat /proc/net/dev; done |
+   gawk '/wlan0/ {if(b) {print $2-b; fflush()} b=$2}' |
+   feedgnuplot --lines --stream --xlen 10 --ylabel 'Bytes/sec' --xlabel seconds
+
+=head2 Realtime plot of battery charge in respect to time
+
+Uses the result of the C<acpi> command.
+
+ $ while true; do acpi; sleep 15; done |
+   perl -nE 'BEGIN{ $| = 1; } /([0-9]*)%/; say join(" ", time(), $1);' |
+   feedgnuplot --stream --ymin 0 --ymax 100 --lines --domain --xlabel 'Time' --timefmt '%s' --ylabel "Battery charge (%)"
+
+=head2 Realtime plot of temperatures in an IBM Thinkpad
+
+Uses C</proc/acpi/ibm/thermal>, which reports temperatures at various locations
+in a Thinkpad.
+
+ $ while true; do cat /proc/acpi/ibm/thermal | awk '{$1=""; print}' ; sleep 1; done |
+   feedgnuplot --stream --xlen 100 --lines --autolegend --ymax 100 --ymin 20 --ylabel 'Temperature (deg C)'
+
+=head2 Plotting a histogram of file sizes in a directory, granular to 10MB
+
+ $ ls -l | awk '{print $5/1e6}' |
+   feedgnuplot --histogram 0
+     --binwidth 10
+     --ymin 0 --xlabel 'File size (MB)' --ylabel Frequency
+
+=head2 Plotting a live histogram of the ping round-trip times for the past 20 seconds
+
+ $ ping -A -D 8.8.8.8 |
+   perl -anE 'BEGIN { $| = 1; }
+              $F[0] =~ s/[\[\]]//g or next;
+              $F[7] =~ s/.*=//g    or next;
+              say "$F[0] $F[7]"' |
+   feedgnuplot --stream --domain --histogram 0 --binwidth 10 \
+               --xlabel 'Ping round-trip time (s)'  \
+               --ylabel Frequency --xlen 20
+
+=head2 Plotting points on top of an existing image
+
+This can be done with C<--image>:
+
+ $ < features_xy.data
+   feedgnuplot --points --domain --image "image.png"
+
+or with C<--equation>:
+
+ $ < features_xy.data
+   feedgnuplot --points --domain
+     --equation '"image.png" binary filetype=auto flipy with rgbimage'
+     --set 'yrange [:] reverse'
+
+The C<--image> invocation is a convenience wrapper for the C<--equation>
+version. Finer control is available with C<--equation>.
+
+
+Here an existing image is given to gnuplot verbatim, and data to plot on top of
+it is interpreted by feedgnuplot as usual. C<flipy> is useful here because
+usually the y axis points up, but when looking at images, this is usually
+reversed: the origin is the top-left pixel.
+
+=head1 ACKNOWLEDGEMENT
+
+This program is originally based on the driveGnuPlots.pl script from
+Thanassis Tsiodras. It is available from his site at
+L<http://users.softlab.ece.ntua.gr/~ttsiod/gnuplotStreaming.html>
+
+=head1 REPOSITORY
+
+L<https://github.com/dkogan/feedgnuplot>
+
+=head1 AUTHOR
+
+Dima Kogan, C<< <dima@secretsauce.net> >>
+
+=head1 LICENSE AND COPYRIGHT
+
+Copyright 2011-2012 Dima Kogan.
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of either: the GNU General Public License as published
+by the Free Software Foundation; or the Artistic License.
+
+See http://dev.perl.org/licenses/ for more information.
+
+=cut

completions/bash/feedgnuplot

@@ -21,6 +21,7 @@ complete -W               \
     --set                 \
     --unset               \
     --equation            \
+    --image               \
     --geometry            \
     --hardcopy            \
     --help                \
@@ -32,7 +33,7 @@ complete -W               \
     --monotonic           \
     --points              \
     --square              \
-    --square_xy           \
+    --square-xy           \
     --stream              \
     --terminal            \
     --timefmt             \

completions/zsh/_feedgnuplot

@@ -16,7 +16,7 @@ _arguments -S
     '--zlabel:Z-axis label:'                                                      \
     '--title:Plot title:'                                                         \
     '--autolegend[Label each plot with its data ID]'                              \
-    '(--3d)--xlen[the size of the x-window to plot]::window size:'                \
+    '(--3d)--xlen[the size of the x-window to plot]:window size:'                 \
     '(--xlen)--xmin:min X:'                                                       \
     '(--xlen)--xmax:max X:'                                                       \
     '--ymin:min Y:'                                                               \
@@ -33,9 +33,10 @@ _arguments -S
     '*--set[Additional 'set' gnuplot commands]:set-option'                        \
     '*--unset[Additional 'unset' gnuplot commands]:unset-option'                  \
     '*--equation[Raw symbolic equation]:equation'                                 \
+    '--image[Image file to render beneath the data]:image:_files -g "(#i)*.(jpg|jpeg|png|gif)"' \
     '--square[Plot data with square aspect ratio]'                                \
-    '--square_xy[For 3D plots, set square aspect ratio for ONLY the x,y axes]'    \
-    '--hardcopy[Plot to a file]:filename'                                         \
+    '--square-xy[For 3D plots, set square aspect ratio for ONLY the x,y axes]'    \
+    '--hardcopy[Plot to a file]:new image filename:_files -g "(#i)*.(jpg|jpeg|png|gif)"' \
     '--maxcurves[The maximum allowed number of curves]:number of curves'          \
     '(--3d)--monotonic[Resets plot if an X in the past is seen]'                  \
     '(--rangesizeall)--extraValuesPerPoint[How many extra values are given for each data range]:N'\
@@ -47,7 +48,7 @@ _arguments -S
     '*--style[Additional styles for a curve]:curve id: :style:'                   \
     '(--3d)*--histogram:plot to treat as a histogram:'                            \
     '--binwidth:Histogram bin width:'                                             \
-    '--histstyle:Style of histogram:(frequency unique cumulative cnormal)'        \
+    '--histstyle:Style of histogram:(frequency fnormal unique cumulative cnormal)' \
     '--terminal:Terminal options to set with "set terminal":'                     \
     '*--legend[Legend for a curve]:curve id: :legend:'                            \
     '--exit[Exit gnuplot after making the plot]'                                  \

debian/changelog

@@ -1,3 +1,93 @@
+feedgnuplot (1.52-1) unstable; urgency=medium
+
+  [ Jelmer Vernooij ]
+  * Use secure copyright file specification URI.
+  * Trim trailing whitespace.
+
+  [ Dima Kogan ]
+  * New upstream release
+    - --square-xy and --squarexy as synonyms for --square_xy
+
+ -- Dima Kogan <dkogan@debian.org>  Sun, 25 Aug 2019 15:34:56 -0700
+
+feedgnuplot (1.51-1) unstable; urgency=medium
+
+  * Added .gp "terminal" to create self-plotting gnuplot files
+
+ -- Dima Kogan <dkogan@debian.org>  Sat, 29 Sep 2018 11:00:40 -0700
+
+feedgnuplot (1.50-1) unstable; urgency=medium
+
+  * Script waits for the plot window to close before exiting
+      Instead of sleeping forever. This is really nice! I no longer need
+      to quit the plot window AND then C-c. Quitting the plot window is
+      now sufficient
+  * by default --image sets range noextend
+  * tab-completion knows about the fnormal distribution
+
+ -- Dima Kogan <dkogan@debian.org>  Fri, 24 Aug 2018 13:16:35 -0700
+
+feedgnuplot (1.49-2) unstable; urgency=medium
+
+  * Updated Vcs-... tags to salsa
+
+ -- Dima Kogan <dkogan@debian.org>  Sun, 17 Jun 2018 22:18:18 -0700
+
+feedgnuplot (1.49-1) unstable; urgency=medium
+
+  * --vnl now works with plots that have rangesize > 1
+  * zsh completion: --xlen argument isn't optional
+
+ -- Dima Kogan <dkogan@debian.org>  Fri, 16 Mar 2018 13:56:27 -0700
+
+feedgnuplot (1.48-1) unstable; urgency=medium
+
+  * Added --tuplesize and --tuplesizeall
+  * vnlog integration
+
+ -- Dima Kogan <dkogan@debian.org>  Sat, 24 Feb 2018 12:56:05 -0800
+
+feedgnuplot (1.45-1) unstable; urgency=medium
+
+  * zsh completion: --hardcopy, --image  suggest filenames
+  * --image now produces a nicer legend: just the filename
+  * --curvestyle now overrides --curvestyleall
+    - This is a bug fix
+  * The version is now treated as a string not as a number
+    - So "1.40" is distinct from "1.4"
+
+ -- Dima Kogan <dkogan@debian.org>  Sun, 29 Oct 2017 14:06:26 -0700
+
+feedgnuplot (1.44-1) unstable; urgency=medium
+
+  * --image always goes on the FRONT of the equation list
+
+ -- Dima Kogan <dkogan@debian.org>  Tue, 20 Jun 2017 16:45:42 -0700
+
+feedgnuplot (1.43-1) unstable; urgency=medium
+
+  * added --image as a convenience wrapper for --equation
+
+ -- Dima Kogan <dkogan@debian.org>  Mon, 19 Jun 2017 13:16:18 -0700
+
+feedgnuplot (1.42-1) unstable; urgency=medium
+
+  * Upstream update:
+    - Fixed regression: data can now come from STDIN or files on the
+      cmdline
+    - reworded manpage of --exit
+
+ -- Dima Kogan <dkogan@debian.org>  Tue, 25 Apr 2017 11:02:18 -0700
+
+feedgnuplot (1.41-1) unstable; urgency=medium
+
+  * Upstream update:
+    - Histograms: --xlen can coexist with --xmin/--xmax
+    - Histograms: work as expected with --xlen and --monotonic
+    - Histograms: better sanity checking of options
+
+ -- Dima Kogan <dkogan@debian.org>  Fri, 24 Feb 2017 23:53:27 -0800
+
 feedgnuplot (1.40-1) unstable; urgency=medium
 
   * Upstream update:

debian/control

@@ -3,17 +3,18 @@ Section: science
 Priority: optional
 Build-Depends: debhelper (>= 9), libstring-shellquote-perl, perl, gawk, gnuplot, libipc-run-perl
 Maintainer: Debian Science Maintainers <debian-science-maintainers@lists.alioth.debian.org>
-Uploaders: Dima Kogan <dima@secretsauce.net>
+Uploaders: Dima Kogan <dkogan@debian.org>
 Standards-Version: 3.9.4
 Homepage: https://github.com/dkogan/feedgnuplot
-Vcs-Git: git://anonscm.debian.org/debian-science/packages/feedgnuplot.git
-Vcs-Browser: http://anonscm.debian.org/gitweb/?p=debian-science/packages/feedgnuplot.git
+Vcs-Browser: https://salsa.debian.org/science-team/feedgnuplot
+Vcs-Git: https://salsa.debian.org/science-team/feedgnuplot.git
 
 Package: feedgnuplot
 Architecture: all
 Depends: ${misc:Depends}, ${perl:Depends},
          liblist-moreutils-perl,
          gnuplot-qt | gnuplot-x11 | gnuplot-nox | gnuplot5-qt | gnuplot5-x11 | gnuplot5-nox | gnuplot
+Suggests: vnlog
 Description: Pipe-oriented frontend to Gnuplot
  Flexible, command-line-oriented frontend to Gnuplot. Creates plots from data
  coming in on STDIN or given in a filename passed on the commandline. Various

debian/copyright

@@ -1,4 +1,4 @@
-Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Source: https://github.com/dkogan/feedgnuplot
 Upstream-Contact: Dima Kogan, <dima@secretsauce.net>
 Upstream-Name: feedgnuplot

debian/feedgnuplot.install

@@ -1,2 +1,2 @@
-completions/bash/feedgnuplot /etc/bash_completion.d/
+completions/bash/feedgnuplot /usr/share/bash-completion/completions/
 completions/zsh/_feedgnuplot /usr/share/zsh/vendor-completions