version bump

Changes

@@ -1,3 +1,20 @@
+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
+  * --style and --rangesize can now take a comma-separated list of IDs
+  * 'any' is from List::MoreUtils, not List::Util
+  * the sleep-forever delay at end is now > 1000 days
+
+ -- Dima Kogan <dima@secretsauce.net>  Fri, 25 Nov 2016 14:45:06 -0800
+
 feedgnuplot (1.39)
 
   * by default, histograms are plotted in expected ways

Makefile.PL

@@ -64,6 +64,7 @@ WriteMakefile
    PL_FILES                   => {},
    EXE_FILES                  => [ 'bin/feedgnuplot' ],
    BUILD_REQUIRES             => { 'String::ShellQuote' => 0,
+                                   'List::MoreUtils'    => 0,
                                    'IPC::Run'           => 0},
    dist                       => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
    clean                      => { FILES => 'feedgnuplot-*' },

bin/feedgnuplot

@@ -8,13 +8,14 @@ use Getopt::Long;
 use Time::HiRes qw( usleep gettimeofday tv_interval );
 use IO::Handle;
 use IO::Select;
-use List::Util qw( first any );
+use List::Util qw( first );
+use List::MoreUtils 'any';
 use Scalar::Util qw( looks_like_number );
 use Text::ParseWords; # for shellwords
 use Pod::Usage;
 use Time::Piece;
 
-my $VERSION = 1.39;
+my $VERSION = 1.41;
 
 my %options;
 interpretCommandline();
@@ -56,6 +57,17 @@ mainThread();
 
 
 
+sub getRangeSize
+{
+    my ($id) = @_;
+
+    # I'd like to use //, but I guess some people are still on perl 5.8
+    return
+      exists $options{rangesize_hash}{$id} ?
+      $options{rangesize_hash}{$id} :
+      $options{rangesize_default};
+}
+
 sub interpretCommandline
 {
   # if I'm using a self-plotting data file with a #! line, then $ARGV[0] will contain ALL of the
@@ -108,9 +120,7 @@ sub interpretCommandline
              'terminal=s',
              'rangesize=s{2}', 'rangesizeall=i', 'extraValuesPerPoint=i',
              'help', 'dump', 'exit', 'version',
-             'geometry=s') or pod2usage( -exitval => 1,
+             'geometry=s') or exit 1;
-                                         -verbose => 1, # synopsis and args
-                                         -output  => \*STDERR );
 
 
   # handle various cmdline-option errors
@@ -127,13 +137,6 @@ sub interpretCommandline
     exit 0;
   }
 
-  # expand options that are given as comma-separated lists
-  for my $listkey (qw(histogram y2))
-  {
-    @{$options{$listkey}} = map split('\s*,\s*', $_), @{$options{$listkey}}
-      if defined $options{$listkey};
-  }
-
   # --style and --curvestyle are synonyms, as are --styleall and
   # --curvestyleall, so fill that in
   if( $options{styleall} )
@@ -157,6 +160,33 @@ sub interpretCommandline
     delete $options{with};
   }
 
+
+  # expand options that are given as comma-separated lists
+  for my $listkey (qw(histogram y2))
+  {
+    @{$options{$listkey}} = map split('\s*,\s*', $_), @{$options{$listkey}}
+      if defined $options{$listkey};
+  }
+  for my $listkey (qw(curvestyle rangesize))
+  {
+      next unless defined $options{$listkey};
+      my @in = @{$options{$listkey}};
+      my $N = @in / 2;
+      my @out;
+      for my $i (0..$N-1)
+      {
+          my $key   = $in[2*$i];
+          my $value = $in[2*$i + 1];
+          for my $key_new (split('\s*,\s*', $key))
+          {
+              push @out, $key_new, $value;
+          }
+      }
+
+      @{$options{$listkey}} = @out;
+  }
+
+
   # If we're plotting histograms, then set the default histogram options for
   # each histogram curve
   #
@@ -203,7 +233,10 @@ sub interpretCommandline
 
 
   # I now set up the rangesize to always be
-  #  $options{rangesize_hash}{$id} // $options{rangesize_default}
+  #
+  #   $options{rangesize_hash}{$id} // $options{rangesize_default}
+  #
+  # which is available as getRangeSize($id)
   if ( $options{rangesizeall} )
   {
       $options{rangesize_default} = $options{rangesizeall};
@@ -262,6 +295,13 @@ sub interpretCommandline
     $options{curvestyleall} .= ' palette';
   }
 
+  if ( defined $options{binwidth} && !@{$options{histogram}} )
+  {
+    print STDERR "--binwidth doesn't make sense without any histograms\n";
+    exit -1;
+  }
+
+
   if ( $options{'3d'} )
   {
     if ( !$options{domain} )
@@ -294,7 +334,7 @@ sub interpretCommandline
       exit -1;
     }
 
-    if ( defined $options{binwidth} || @{$options{histogram}} )
+    if ( @{$options{histogram}} )
     {
       print STDERR "--3d does not make sense with histograms\n";
       exit -1;
@@ -328,6 +368,16 @@ sub interpretCommandline
       print STDERR "--square_xy only makes sense with --3d\n";
       exit -1;
     }
+
+    for my $hist_curve(@{$options{histogram}})
+    {
+        my $hist_dim = getRangeSize($hist_curve);
+        if( $hist_dim != 1 )
+        {
+            print STDERR "I only support 1D histograms, but curve '$hist_curve' has '$hist_dim'-D data\n";
+            exit -1;
+        }
+    }
   }
 
   if(defined $options{xlen} && !$options{stream} )
@@ -337,7 +387,8 @@ sub interpretCommandline
   }
 
   if($options{stream} && defined $options{xlen} &&
-     ( defined $options{xmin} || defined $options{xmax}))
+     ( defined $options{xmin} || defined $options{xmax}) &&
+    !defined $options{histogram})
   {
     print STDERR "With --stream and --xlen the X bounds are set, so neither --xmin nor --xmax make sense\n";
     exit -1;
@@ -730,20 +781,10 @@ sub mainThread
 
       while(@fields)
       {
-          if($options{dataid})
+          if($options{dataid}) { $id = shift @fields; }
-          {
+          else                 { $id++;               }
-              $id = shift @fields;
-          }
-          else
-          {
-              $id++;
-          }
-
-          # I'd like to use //, but I guess some people are still on perl 5.8
-          my $rangesize = exists $options{rangesize_hash}{$id} ?
-            $options{rangesize_hash}{$id} :
-            $options{rangesize_default};
 
+          my $rangesize = getRangeSize($id);
           last if @fields < $rangesize;
 
           pushPoint(getCurve($id),
@@ -786,7 +827,7 @@ sub mainThread
     # we persist gnuplot, so we shouldn't need this sleep. However, once
     # gnuplot exits, but the persistent window sticks around, you can no
     # longer interactively zoom the plot. So we still sleep
-    sleep(100000) unless $options{dump} || $options{exit};
+    sleep(100000000) unless $options{dump} || $options{exit};
 }
 
 sub pruneOldData
@@ -867,12 +908,7 @@ sub updateCurveOptions
       # as 1 + rangesize). I also need to start the range at the first column
       # past the timefmt
 
-      # I'd like to use //, but I guess some people are still on perl 5.8
+      my @rest = map {$_ + $options{timefmt_Ncols}} (1..getRangeSize($id));
-      my $rangesize = exists $options{rangesize_hash}{$id} ?
-        $options{rangesize_hash}{$id} :
-        $options{rangesize_default};
-
-      my @rest = map {$_ + $options{timefmt_Ncols}} (1..$rangesize);
 
       $usingoptions = "using 1:" . join(':', @rest);
   }
@@ -903,6 +939,22 @@ sub getCurve
     $curveIndices{$id} =  $#curves;
 
     updateCurveOptions($curves[$#curves], $id);
+
+
+    # --xlen has a meaning if we're not plotting histograms at all or if we're
+    # plotting ONLY histograms. If we're doing both at the same time, there's no
+    # consistent way to assign meaning to xlen
+    if ( defined $options{xlen} &&
+
+         # have at least some histograms
+         @{$options{histogram}} &&
+
+         # there are more curves than histogram curves, i.e. there're some
+         # non-histogram curves
+         @curves > @{$options{histogram}} ) {
+        print STDERR "--xlen only makes sense when plotting ONLY histograms or ONLY NON-histograms\n";
+        exit -1;
+    }
   }
   return $curves[$curveIndices{$id}];
 }
@@ -930,6 +982,10 @@ sub setCurveAsHistogram
   my ($id, $str) = @_;
 
   my $curve = getCurve($id);
+
+  # With histograms I have 2d plots with rangesize=1. I thus give gnuplot two
+  # values for each point: a domain and a range. For histograms I ignore the
+  # domain, so I get the statistics of the 2nd column: $2
   $curve->{histoptions} = 'using (histbin($2)):(1.0) smooth ' . $options{histstyle};
 
   updateCurveOptions($curve, $id);
@@ -997,7 +1053,11 @@ sub replot
         # seconds-since-the-epoch BACK to the timefmt. Sheesh
         ($xmin, $xmax) = map {Time::Piece->strptime( $_, '%s' )->strftime( $options{timefmt} ) } ($xmin, $xmax);
       }
-      sendRangeCommand( "xrange", $xmin, $xmax );
+
+      # if we have any histograms, then I'm not really visualizing the domain at
+      # all, and I don't set the range.
+      sendRangeCommand( "xrange", $xmin, $xmax )
+        unless @{$options{histogram}};
     }
 
     plotStoredData();
@@ -1246,7 +1306,12 @@ 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.
+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
 
@@ -1279,7 +1344,9 @@ This command causes feedgnuplot to exit.
 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> or B<.png> is requested. If any other file type is requested,
-C<--terminal> I<must> be passed in to tell gnuplot how to make the plot.
+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.
 
 =head2 Self-plotting data files
 
@@ -1478,7 +1545,12 @@ 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>
+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
 
@@ -1520,8 +1592,9 @@ 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 x-values are I<not> drawn
+data because of C<--xlen> or C<--monotonic>. I.e. the domain values are I<not>
-in any way. Can be passed multiple times, or passed a comma- separated list
+drawn in any way. Can be passed multiple times, or passed a comma- separated
+list
 
 =item
 
@@ -1548,9 +1621,10 @@ report 0 or 1. 'cumulative' is the integral of the 'frequency' histogram.
 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. Use this option multiple times for
+it's the index of the curve, starting at 0. curveID can be a comma-separated
-multiple curves. C<--styleall> does I<not> apply to curves that have a
+list of IDs to which the given style should apply. Use this option multiple
-C<--style>
+times for multiple curves. C<--styleall> does I<not> apply to curves that have a
+C<--style>.
 
 =item
 
@@ -1653,16 +1727,17 @@ For 3D plots, set square aspect ratio for ONLY the x,y axes
 C<--hardcopy xxx>
 
 If not streaming, output to a file specified here. Format inferred from
-filename, unless specified by C<--terminal>
+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 --hardcopy is given .png,
+C<--hardcopy> sets this to some sensible defaults if C<--hardcopy> is set to a
-.pdf, .ps, .eps or .svg. If any other file type is desired, use both
+filename ending in C<.png>, C<.pdf>, C<.ps>, C<.eps> or C<.svg>. If any other
-C<--hardcopy> and C<--terminal>
+file type is desired, use both C<--hardcopy> and C<--terminal>
 
 =item
 
@@ -1695,6 +1770,10 @@ 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<--rangesizeall xxx>
@@ -1856,6 +1935,30 @@ in a Thinkpad.
      --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 by using C<--equation> to pass arbitrary plot input to gnuplot:
+
+ $ < features_xy.data
+   feedgnuplot --points --domain
+     --equation '"image.png" binary filetype=png flipy with rgbimage'
+
+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