rawk 0.1.1 → 0.1.2

data/.gitignore

@@ -0,0 +1 @@
+*.gem

data/README.rdoc

@@ -0,0 +1,195 @@
+= Rawk 
+
+An awk-inspired ruby DSL
+
+Last week, after years of ignoring awk, I ran into a shell script problem where it was the only viable solution (we didn't have ruby on the server) and I was forced to learn a bit more about it.  
+
+Once, I had awk figured out, I thought it would be fun to write an awk DSL using ruby.  It's turned out to be quite an interesting little project for the daily train ride to work and back.
+
+Obviously, you can use ruby -e and {other magic}[http://code.joejag.com/2009/using-ruby-as-an-awk-replacement/] to execute snippets of ruby, but I like the way awk provides a bit more structure and a richer environment for more complex command line mangling.
+
+== Install
+
+Clone the git repo or download the file as a .tar or .zip.  The bin directory contains the rawk executable.  Does not require any gems (except rspec if you want to run the tests)
+
+I will package rawk as a gem when I find a spare moment.
+
+== Example
+
+A simple awk program
+
+  $ ls -ltr | awk '
+    BEGIN {print "Starting..."}
+    {print $9, $1}
+    END {print "done"} '
+
+Creates the following output
+
+  Starting...
+   total
+  spec drwxr-xr-x
+  lib drwxr-xr-x
+  bin drwxr-xr-x
+  README -rw-r--r--
+  done
+
+This can be written using rawk as
+
+  $ ls -ltr | bin/rawk '
+    start {puts "Starting..."}
+    every {|record| puts "#{record.cols[8]} #{record.cols[0]}"}
+    finish {puts "done"} '
+
+And it also creates the same output
+
+  Starting...
+   total
+  spec drwxr-xr-x
+  lib drwxr-xr-x
+  bin drwxr-xr-x
+  README -rw-r--r--
+  done
+
+Notice that the structure and semantics of an awk program is preserved and you use normal ruby code to process the input stream.  I've had to bend the knee to the ruby interpreter and change the syntax slightly but I think it actually makes rawk programs a bit clearer than awk.  
+
+Details descriptions are shown below.  I'm assuming you have a working knowledge of awk.  Wikipedia provides an {easy primer}[http://en.wikipedia.org/wiki/AWK] if you need to brush up.
+
+== Conditions and blocks
+
+rawk provides 3 built-in conditions.  
+
+  start {<code>}
+
+Runs before any lines are read from the input stream.  Equivalent to a BEGIN condition in awk
+
+  every {|record| <code>}
+
+Runs once for each line of input data.  Yields an object of type Line (see below)
+Equivalent to an anonymous block such as awk '{print $1}'
+
+  finish {<code>}
+
+Runs after the end of the input stream
+Equivalent to an END condition in awk
+
+You can provide multiple blocks of code for each condition.
+
+  ls -ltr | head -2 | bin/rawk '
+    every {|record| puts 1}
+    every {|record| puts 2} '
+    
+prints
+
+  1
+  2
+  1
+  2
+
+=== Not supported (yet)
+
+* Conditional blocks 
+
+== Lines
+
+every yields an object of type Line which is subclass of String that adds a cols method to access columns.  The cols method returns an array of column values.
+
+  echo "hello world" | bin/rawk 'every do |record| 
+    puts "#{record.cols.length} columns: #{record.cols.join(",")}"
+  end'
+  
+  -> 2 columns: hello,world
+
+Note that cols is aliased to c for convenience
+
+    echo "hello world" | bin/rawk 'every do |record| 
+      puts record.c[0]
+    end'
+    
+    -> hello
+
+== Functions, classes and other ruby stuff
+
+You can use ruby as normal before specifying any blocks.  For example...
+
+Functions
+
+  echo hello world | bin/rawk '
+    def print_first_column(record)
+      puts record.cols.first
+    end
+    every {|record| print_first_column(record)}'
+  
+Classes
+
+  echo hello world | bin/rawk '
+    class Printer
+      def self.print_first(record)
+        puts record.cols.first
+      end
+    end
+    every {|record| Printer.print_first(record)} '
+
+Requires and gems
+
+require works as you would expect although rubygems is not required by default.
+
+  echo "ruby" | bin/rawk '
+    require "rubygems"
+    require "active_support/all"
+    every {|record| puts record.cols.first.pluralize} '
+  
+  -> rubies
+
+== Builtins
+
+rawk provides builtins as member variables.  You can change them as you see fit.
+
+@nr holds the current record number 
+  ls -ltr | head -2 | bin/rawk 'every {puts @nr}'
+    
+@fs specifies the field separator applied to each record
+  
+  echo "foo.bar" | bin/rawk ' 
+    start {@fs="."}
+    every {|record| puts "1: #{record.cols[0]} 2: #{record.cols[1]}"} '
+  
+  -> 1: foo 2: bar
+  
+=== Not supported (yet)
+
+I'm working on support for the following awk built-ins 
+
+FILENAME: 
+Contains the name of the current input-file.
+* Reading input data is not supported yet
+* When I add it, I'll add @filename as a member
+
+RS: 
+Stores the current "record separator" character. Since, by default, an input line is the input record, the default record separator character is a "newline".
+* Will be @rs
+* Currently, records are delimited by newline
+
+
+=== Redundant
+
+The following awk built-ins are redundant in ruby
+
+NF: 
+Keeps a count of the number of fields in an input record. The last field in the input record can be designated by $NF.
+* NF can be coded as 'every {|record| record.cols.size}'
+* $NF can be coded as 'every {|record| record.cols.last}'
+
+OFS: 
+Stores the "output field separator", which separates the fields when Awk prints them. The default is a "space" character.
+* Ruby's string handling is far superior to awk's so there is no point in implementing a print routine
+
+ORS: 
+Stores the "output record separator", which separates the output records when Awk prints them. The default is a "newline" character.
+* You already have complete control of the output stream.  If you don't want newlines, use print or printf instead of puts
+
+OFMT: Stores the format for numeric output. The default format is "%.6g".
+* Ruby's string and number handing gives you much better control over this sort of thing
+
+== Using rawk inside a ruby program
+
+Technically, you can require rawk and use it's classes directly.  However, it will be messy until I add gem packaging so I'll wait until you can install rawk as a gem before I go ahead an document it.

data/rawk.gemspec

@@ -0,0 +1,20 @@
+require 'rubygems'
+
+SPEC = Gem::Specification.new do |s|
+  s.name = "rawk"
+  s.version = '0.1.2'
+  s.author = "Adrian Mowat"
+  s.homepage = "https://github.com/mowat27/rawk"
+  s.summary = "An awk-inspired ruby DSL"
+  s.description = <<EOS
+An awk-inspired ruby DSL
+Provides an awk-like ruby interface for stream procesing
+EOS
+  s.has_rdoc = false
+  
+  s.files            = `git ls-files`.split("\n")
+  s.test_files       = `git ls-files -- {spec,features}/*`.split("\n")
+  s.executables     = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+
+  s.require_paths = ["lib/rawk"]
+end

metadata

@@ -1,24 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: rawk
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
 - Adrian Mowat
-autorequire: rawk/rawk
+autorequire: 
 bindir: bin
 cert_chain: []
 date: 2011-08-14 00:00:00.000000000Z
 dependencies: []
-description: 
+description: ! 'An awk-inspired ruby DSL
+
+  Provides an awk-like ruby interface for stream procesing
+
+'
 email: 
-executables: []
+executables:
+- rawk
 extensions: []
 extra_rdoc_files: []
 files:
+- .gitignore
+- README.rdoc
 - bin/rawk
 - lib/rawk/rawk.rb
+- rawk.gemspec
 - spec/rawk/line_spec.rb
 - spec/rawk/rawk_spec.rb
 - spec/spec_helper.rb
@@ -27,7 +35,7 @@ licenses: []
 post_install_message: 
 rdoc_options: []
 require_paths:
-- - lib
+- lib/rawk
 required_ruby_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -46,4 +54,7 @@ rubygems_version: 1.8.8
 signing_key: 
 specification_version: 3
 summary: An awk-inspired ruby DSL
-test_files: []
+test_files:
+- spec/rawk/line_spec.rb
+- spec/rawk/rawk_spec.rb
+- spec/spec_helper.rb