Adding tarball creation scripts and help text

.gitignore

@@ -5,3 +5,4 @@ makedeb/*
 pm_to_blib
 testDb
 App-RecordStream-*.tar.gz
+tarball/*

INSTALLING

@@ -1,3 +1,20 @@
+================================================================================
+==================== Install from tarball ======================================
+================================================================================
+
+Grab the tarbal from github or from technofetish and untar it.
+
+% wget http://technofetish.net/recs.tar.gz
+% tar -xzvf recs.tar.gz
+
+Then run a script!
+
+% RecordStream/bin/recs-fromps
+
+================================================================================
+==================== Install from github =======================================
+================================================================================
+
 Best way to get recent code is use apt-get with git clone from github. (Manual Install below)
 
 1. sudo apt-get install libdbd-sqlite3-perl sqlite3 libxml-simple-perl libproc-processtable-perl libdate-manip-perl libtext-csv-perl gnuplot libnetpacket-perl libnet-pcap-perl libnet-dns-perl libjson-perl libtext-autoformat-perl

INSTALLING.tarball

@@ -0,0 +1,29 @@
+================================================================================
+===========================  Using RecordStream ================================
+================================================================================
+
+You've downloaded the tarball!  You're basically done.  Just add the scripts to
+your path
+
+export PATH=$PATH:`pwd`/bin
+
+And start using the scripts!  See the examples below for how guides to get
+started.
+
+================================================================================
+==================  Getting Started with RecordStream ==========================
+================================================================================
+
+See our lovely documentation via 'perldoc'.  Here are some recommendations:
+
+* A high level over view of recs
+  perldoc README.pod
+
+* A humorous story to help you get started with recs
+  perldoc doc/RecordStreamStory.pod
+
+* Some follow-along examples to show you the power of recs
+  perldoc doc/Examples.pod
+
+* Every script has --help documentation
+  recs-fromsplit --help

debian/changelog

@@ -1,3 +1,9 @@
+libapp-recordstream-perl (3.7-01-ubuntu2) oneiric; urgency=low
+
+  * Update to 3.7.1, with optional modules
+
+ -- Ben Bernard <bernard@bernard-laptop>  Sun, 15 Apr 2012 00:00:26 -0700
+
 libapp-recordstream-perl (3.7-01-ubuntu1) oneiric; urgency=low
 
   * CPAN changes

doc/recs-togdgraph.pod

@@ -0,0 +1,115 @@
+=head1 NAME
+
+recs-togdgraph
+
+=head1 recs-togdgraph --help-all
+
+ Help from: --help-basic:
+ Usage: recs-togdgraph <args> [<files>]
+   Create a bar, scatter, or line graph using GD::Graph.
+
+ Args:
+    --key|-k|--key <keyspec>     Specify keys that correlate to keys in JSON data
+    --option|-o option=val       Specify custom command for GD::Graph
+    --label-x <val>              Specify X-axis label
+    --label-y <val>              Specify Y-axis label
+    --width <val>                Specify width
+    --height <val>               Specify height
+    --graph-title <val>          Specify graph title
+    --type <val>                 Specify different graph type other than scatter (supported: line, bar)
+    --png-file <val>             Specify output PNG filename
+    --dump-use-spec <val>        Dump GD usage (used mainly for testing)
+    --filename-key|fk <keyspec>  Add a key with the source filename (if no filename is applicable will put NONE)
+
+   Help Options:
+       --help-all        Output all help for this script
+       --help            This help screen
+       --help-keygroups  Help on keygroups, a way of specifying multiple keys
+       --help-keys       Help on keygroups and keyspecs
+       --help-keyspecs   Help on keyspecs, a way to index deeply and with regexes
+
+ Examples:
+   for a plain point graph:
+
+   recs-togdgraph --keys uid,ct --png-file login-graph.png --graph-title '# of logins' --label-x user --label-y logins
+
+   togdgraph also accepts any GD::Graph options with the --option command...
+   for a pink background with yellow label text if that really is your thing:
+
+   recs-togdgraph --keys uid,ct --option boxclr=pink --label-y 'logins' --label-x 'user' --option labelclr=yellow
+
+   however, for a different graph type such as line or bar, specify with --type:
+
+   recs-togdgraph --keys uid,ct --type line
+
+ Help from: --help-keygroups:
+ KEY GROUPS
+    SYNTAX: !regex!opt1!opt2... Key groups are a way of specifying multiple fields to a recs command with a single argument or
+    function. They are generally regexes, and have several options to control what fields they match. By default you give a regex,
+    and it will be matched against all first level keys of a record to come up with the record list. For instance, in a record
+    like this:
+
+    { 'zip': 1, 'zap': 2, 'foo': { 'bar': 3 } }
+
+    Key group: !z! would get the keys 'zip' and 'zap'
+
+    You can have a literal '!' in your regex, just escape it with a \.
+
+    Normally, key groups will only match keys whose values are scalars. This can be changed with the 'returnrefs' or rr flag.
+
+    With the above record !f! would match no fields, but !f!rr would match foo (which has a value of a hash ref)
+
+    Options on KeyGroups:
+       returnrefs, rr  - Return keys that have reference values (default:off)
+       full, f         - Regex should match against full keys (recurse fully)
+       depth=NUM,d=NUM - Only match keys at NUM depth (regex will match against
+                         full keyspec)
+       sort, s         - sort keyspecs lexically
+
+ Help from: --help-keyspecs:
+   KEY SPECS
+    A key spec is short way of specifying a field with prefixes or regular expressions, it may also be nested into hashes and
+    arrays. Use a '/' to nest into a hash and a '#NUM' to index into an array (i.e. #2)
+
+    An example is in order, take a record like this:
+
+      {"biz":["a","b","c"],"foo":{"bar 1":1},"zap":"blah1"}
+      {"biz":["a","b","c"],"foo":{"bar 1":2},"zap":"blah2"}
+      {"biz":["a","b","c"],"foo":{"bar 1":3},"zap":"blah3"}
+
+    In this case a key spec of 'foo/bar 1' would have the values 1,2, and 3 in the respective records.
+
+    Similarly, 'biz/#0' would have the value of 'a' for all 3 records
+
+    You can also prefix key specs with '@' to engage the fuzzy matching logic
+
+    Fuzzy matching works like this in order, first key to match wins
+      1. Exact match ( eq )
+      2. Prefix match ( m/^/ )
+      3. Match anywehre in the key (m//)
+
+    So, in the above example '@b/#2', the 'b' portion would expand to 'biz' and 2 would be the index into the array, so all records
+    would have the value of 'c'
+
+    Simiarly, @f/b would have values 1, 2, and 3
+
+    You can escape / with a \. For example, if you have a record:
+    {"foo/bar":2}
+
+    You can address that key with foo\/bar
+
+
+=head1 See Also
+
+=over
+
+=item  L<RecordStream(3)> - Overview of the scripts and the system
+
+=item  L<recs-examples(3)> - A set of simple recs examples
+
+=item  L<recs-story(3)> - A humorous introduction to RecordStream
+
+=item SCRIPT --help - every script has a --help option, like the output above
+
+=back
+

generate_tarball.pl

@@ -0,0 +1,105 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+
+use File::Basename qw(basename);
+use Data::Dumper;
+use Cwd;
+
+my $DIRECTORY = 'tarball/RecordStream';
+my $BIN_DIRECTORY = $DIRECTORY . '/bin';
+
+my @EXTRAS = qw(
+  JSON::Syck
+  JSON::PP
+  GD::Graph::lines
+  GD::Graph::bars
+  GD::Graph::points
+  NetPacket::Ethernet
+  NetPacket::IP
+  NetPacket::TCP
+  NetPacket::UDP
+  NetPacket::ARP
+  Net::Pcap
+  Net::DNS::Packet
+  Proc::ProcessTable
+);
+
+require 'BuildTools.recbuildtool';
+import BuildTools qw(get_pms run_command get_bin_scripts);
+
+$ENV{'PERL5LIB'} .= ':lib';
+
+create_bin_scripts();
+create_copy_files();
+#create_executable();
+#create_tarball();
+
+sub create_executable {
+  my $pp_args = create_pp_args();
+  #run_command('pp', @args);
+}
+
+sub create_tarball {
+  my $tar_file = 'tarball/recs.tar.gz';
+  run_command('tar', 'czf', $tar_file, '-C', 'tarball', 'RecordStream');
+  print "Created $tar_file\n";
+}
+
+sub create_copy_files {
+  print "Updating docs\n";
+  run_command('./generate_pods.pl');
+
+  my @copy_files = qw(LICENSE README.pod doc);
+
+  my $translate_files = {
+    (map { $_ => $_ } @copy_files),
+    'INSTALLING.tarball' => 'INSTALLING',
+  };
+
+  print Dumper $translate_files;
+
+  foreach my $from_file (keys %$translate_files) {
+    my $to_file = $translate_files->{$from_file};
+
+    my @cp_args;
+    if ( -d $from_file ) {
+      push @cp_args, '-r';
+    }
+
+    push @cp_args, $from_file, $DIRECTORY . '/' . $to_file;
+    run_command('cp', @cp_args);
+  }
+}
+
+sub create_pp_args {
+  my @pms = get_pms();
+
+  my @args = qw(-v);
+
+  foreach my $pm (@pms, @EXTRAS) {
+    push @args, '-M', $pm;
+  }
+
+  push @args, '-o', $BIN_DIRECTORY . 'recs-operation', 'bin/recs-operation';
+  return \@args;
+}
+
+sub create_bin_scripts {
+  my @scripts = get_bin_scripts();
+
+  my $pwd = getcwd();
+  chdir $BIN_DIRECTORY;
+
+  foreach my $script (@scripts) {
+    print "Symlinking script: $script\n";
+    if ( -e $script ) {
+      unlink $script;
+    }
+    symlink 'recs-operation', $script;
+  }
+
+  chdir $pwd;
+}
+

ignore.txt

@@ -10,3 +10,4 @@ pm_to_blib*
 cover_db
 pod2htm*.tmp
 App-RecordStream-*
+tarball*