rsql 0.1.3 → 0.1.4

data/README.txt

@@ -11,7 +11,7 @@ for access to the SQL server.
 
 == SYNOPSIS
 
-See rsql -help for usage.
+Run rsql with no arguments for usage.
 
 Aside from the standard MySQL command syntax, the following
 functionality allows for a little more expressive processing.
@@ -28,10 +28,10 @@ final result of evaluating the command string is another string, it is
 executed as SQL. Any semicolons meant to be processed by Ruby must be
 escaped. Example:
 
- rsql> . puts 'hello world!' \\; 'select * from Account'
+ rsql> . puts 'hello world!' \; 'select * from Account';
 
-Utilizing Canned Methods
-------------------------
+Utilizing Canned Methods (aka "Recipes")
+----------------------------------------
 
 Commands can be stored in the .rsqlrc file in your HOME directory to
 expose methods that may be invoked to generate SQL with variable
@@ -41,23 +41,23 @@ approach. These can then be called in the same way as above. Example:
 In the .rsqlrc file...
 
  register :users_by_email, :email %q{
-   SELECT * FROM Users WHERE email = '\#\{email\}'
+   SELECT * FROM Users WHERE email = '#{email}'
  }
 
 ...then from the prompt:
 
- rsql> . users_by_email 'brad@gigglewax.com'
+ rsql> . users_by_email 'brad@gigglewax.com';
 
 If a block is provided to the registration, it will be called as a
 method. Example:
 
 In the .sqlrc file...
 
- register :dumby, :hello do |*args|
+ register :dummy, :hello do |*args|
    p args
  end
 
- rsql> . dumby :world
+ rsql> . dummy :world;
 
 All registered methods can be listed using the built-in 'list'
 command.
@@ -75,7 +75,7 @@ converting it into a more readable value. A bang indicator (exlamation
 point: !) is used to demarcate a mapping of column names to Ruby
 methods that should be invoked to processes content. Example:
 
- rsql> select IpAddress from Devices ; ! IpAddress => bin_to_str
+ rsql> select IpAddress from Devices ! IpAddress => bin_to_str;
 
 This will call 'bin_to_str' for each 'IpAddress' returned from the
 query. Mulitple mappings are separated by a comma. These mappings can
@@ -87,13 +87,24 @@ Redirection
 -----------
 
 Output from one or more queries may be post-processed dynamically. If
-any set of commands is follwed by a greater-than symbol, all results
-will be stored in a global $results array (with field information
-stored in $fields) and the final Ruby code will be evaluated with
-access to them. Any result of the evaluation that is a string is then
-executed as SQL. Example:
+any set of commands is follwed by a pipe symbol, results from the
+previous command will be available in a member variable as
+@results. The results can be used through any of the MySQLResults
+class' public methods (e.g. each_hash) and the final Ruby code will be
+evaluated with access to them. Any result of the evaluation that is a
+string is then executed as SQL. Example:
 
- rsql> select * from Account; select * from Users; > $results.each {|r| p r}
+ rsql> select * from Users | @results.each_hash{|r| p r};
+
+And again, it's most useful to encapsulate the processing logic within
+a registered ruby block that can be called after the pipe as a single
+command.
+
+Even More!
+----------
+
+For additional examples and functionality, read and try the
+example.rsqlrc file.
 
 == LICENSE
 

data/TODO

@@ -1,5 +1,3 @@
-* Support separation of semicolon content from registered sql.
-
 * Fix multiline dump to be columnar sensitive (i.e. all but the first
   line will need a prefix of previous column length whitespace.
 
@@ -28,3 +26,11 @@
 
 * Move last_command logic into mysql_results and remember last five
   (or so).
+
+* Fix need for SSH password! It never asks.
+
+* Find out if it's easy to point at source from the wiki to point
+  people at the example.rsqlrc.
+
+* Consider adding the option to specify a dispalyer when registering a
+  recipe.

data/bin/rsql

@@ -56,7 +56,7 @@ else
     rc_fn = File.join(ENV['HOME'], ".#{bn}rc")
 end
 
-eval_context.load(rc_fn) if File.exists?(rc_fn)
+eval_context.load(rc_fn, false) if File.exists?(rc_fn)
 
 def get_password(prompt)
     iswin = nil != (RUBY_PLATFORM =~ /(win|w)32$/)
@@ -256,7 +256,7 @@ rescue Mysql::Error => ex
     exit 1
 end
 
-eval_context.call_init_registrations(MySQLResults.conn)
+eval_context.call_init_registrations
 
 history_fn = File.join(ENV['HOME'], ".#{bn}_history")
 if File.exists?(history_fn) && 0 < File.size(history_fn)

data/example.rsqlrc

@@ -0,0 +1,148 @@
+# -*- Mode: ruby -*-
+
+# This file is meant to be a working illustration of how RSQL might be
+# used and to show off various features of the application.
+
+# All examples below will use this temporary table. You will need to
+# "use" a database first before loading this file since it will need
+# to create this temporary table.
+#
+@rsql_table = 'rsql_example'
+
+# To use this file, change directory to the one containing this file,
+# run rsql connecting to your MySQL server (run rsql with no arguments
+# for usage). At the RSQL prompt, type ".load 'example.rsqlrc';"
+# (without the double quotes).
+
+# After it's loaded try out the command ".list;" (without the
+# quotes).
+
+# If you make changes to the example to try out new things (and please
+# do!), you can simply enter ".reload;" (without the double quotes) to
+# have your changes pulled in immediately without exiting your
+# session.
+
+################################################################################
+
+# This type of registration is automatically invoked when this file is
+# loaded. Often, this is useful to run set up routines like setting
+# mysql variables for different read levels (e.g. SET SESSION
+# TRANSACTION ISOLATION LEVEL READ COMMITTED). Any number of these may
+# be defined.
+#
+# Here we are merely setting up the example table.
+#
+register_init :setup_example, %q{
+CREATE TEMPORARY TABLE IF NOT EXISTS #{@rsql_table} (
+  name VARCHAR(100),
+  value INT(11)
+)
+}, :desc => 'Sets up example table for trying out RSQL.'
+
+# This recipe is simply building up a string with a single variable
+# interpolated into it (our table name). The string will then be used
+# as if typed at the command line.
+#
+# In this case, we are simply dropping the table created by our
+# initialization recipe.
+#
+register :cleanup, %q{
+DROP TEMPORARY TABLE IF EXISTS #{@rsql_table}
+}, :desc => 'Cleans up the example table.'
+
+# This is an example of a recipe that utilizes a Ruby block for
+# running code to generate the SQL we eventually return.
+#
+# Here we are just populating the table (if it isn't already).
+#
+# Notice that we are also making use of one of EvalContext's helper
+# methods, "squeeze!" to make the SQL compact.
+#
+register :fill_table, :desc => 'Populate the example table.' do
+    sql = ''
+    10.times do |i|
+        sql << "
+INSERT IGNORE INTO #{@rsql_table}
+   SET  name='fancy#{i}',
+       value=#{i**i};
+"
+    end
+    sqeeze!(sql)
+end
+
+# After you have a table with content in it, you can run queries
+# against it and have the contents changed into something a little
+# more meaningful. For example, what if the values in our table were
+# bytes that we wanted to humanize? Try this command:
+#
+# rsql> select * from rsql_example ! value => humanize_bytes;
+#
+# The humanize_bytes method is a helper in the EvalContext
+# class. There are several others avaialble. Check out the rdoc for
+# details.
+#
+# You can also declare these column mappings in your recipes too,
+# though the syntax is slightly different, using Ruby symbols.
+#
+register :show_values_as_bytes, %q{
+SELECT value FROM #{@rsql_table}
+}, 'value' => :humanize_bytes,
+   :desc => 'Show values as humanized bytes.'
+
+# It is even possible to make up your own column mapping helpers. Just
+# create a Ruby method and reference it as a symbol mapped to whatever
+# column the helper is expecting for content. The return of the helper
+# will be replaced as the column entry's content. Your method is
+# called once for each value in the column from the results.
+#
+# Make sure if your method doesn't understand the content passed to it
+# that it just reflects it back out so you don't lose data when
+# printed.
+#
+def pretty_names(name)
+    if name =~ /^(\w+)(\d+)$/
+        "#{$1} (#{$2})"
+    else
+        name
+    end
+end
+
+register :show_pretty_names, %q{
+SELECT name FROM #{@rsql_table}
+}, 'name' => :pretty_names,
+   :desc => 'Show names separated to be more readable.'
+
+
+# It's also possible to work with the full set of query results in a
+# recipe. This can be useful if there is some coordination necessary
+# across multiple columns to result in some new kind of report. Much
+# like a shell's ability to pipe output from one command to the next,
+# RSQL takes a similar approch. Try this:
+#
+# rsql> select * from rsql_example | p @results;
+#
+# The EvalContext manages the results from a previous query in the
+# @results member variable accessible by any Ruby recipe code. This is
+# an instance of the MySQLResults class. Below we make use of the
+# each_hash method to walk over all rows. There are other helpful
+# routines available as well that are documented in rdoc.
+#
+# Here's an example that writes a simple report of the data we are
+# working with. To try this out, enter the following at the prompt:
+#
+# rsql> select * from rsql_example | to_report;
+#
+register :to_report do
+    small_cnt = 0
+    big_cnt   = 0
+    @results.each_hash do |row|
+        if row['value'].to_i < 10000
+            small_cnt +=1
+        else
+            big_cnt += 1
+        end
+    end
+    puts "There are #{small_cnt} small values and #{big_cnt} big values."
+end
+
+# vi: set filetype=ruby

data/lib/rsql/commands.rb

@@ -118,6 +118,14 @@ module RSQL
             return @cmds.empty?
         end
 
+        def concat(other)
+            @cmds.concat(other)
+        end
+
+        def last
+            @cmds.last
+        end
+
         def run!(eval_context)
             last_results = nil
             while @cmds.any?
@@ -150,9 +158,6 @@ module RSQL
                 when ?.
                     content.slice!(0)
                     declarator = :ruby
-                when ?@
-                    content.slice!(0)
-                    declarator = :iterator
                 else
                     declarator = is_ruby ? :ruby : nil
                 end
@@ -176,39 +181,42 @@ module RSQL
             end
 
             def run_command(cmd, last_results, eval_context)
-                ctx = EvalContext::CommandContext.new
-
-                # set up to allow an iterator to run up to 100,000 times
-                100000.times do |i|
-                    eval_context.bangs = cmd.bangs
-
-                    if cmd.declarator
-                        ctx.index = i
-                        ctx.last_results = last_results
-                        stdout = cmd.displayer == :pipe ? StringIO.new : nil
-                        value = eval_context.safe_eval(cmd.content, ctx, stdout)
-                    else
-                        value = cmd.content
-                    end
-
-                    return :done if value == 'exit' || value == 'quit'
+                eval_context.bangs = cmd.bangs
 
+                if cmd.declarator
+                    stdout = cmd.displayer == :pipe ? StringIO.new : nil
+                    value = eval_context.safe_eval(cmd.content, last_results, stdout)
                     if String === value
-                        begin
-                            last_results = MySQLResults.query(value, eval_context)
-                        rescue MySQLResults::MaxRowsException => ex
-                            $stderr.puts "refusing to process #{ex.rows} rows (max: #{ex.max})"
-                        rescue MysqlError => ex
-                            $stderr.puts ex.message
-                        rescue Exception => ex
-                            $stderr.puts ex.inspect
-                            raise
+                        cmds = Commands.new(value, @default_displayer)
+                        unless cmds.empty?
+                            # need to carry along the bangs into the
+                            # last command so we don't lose them
+                            if cmds.last.bangs.empty? && cmd.bangs.any?
+                                cmds.last.bangs = cmd.bangs
+                            end
+                            @cmds = cmds.concat(@cmds)
                         end
-                    else
-                        last_results = EvalResults.new(value, stdout)
+                        return
                     end
+                else
+                    value = cmd.content
+                end
 
-                    break unless ctx.incomplete
+                return :done if value == 'exit' || value == 'quit'
+
+                if String === value
+                    begin
+                        last_results = MySQLResults.query(value, eval_context)
+                    rescue MySQLResults::MaxRowsException => ex
+                        $stderr.puts "refusing to process #{ex.rows} rows (max: #{ex.max})"
+                    rescue MysqlError => ex
+                        $stderr.puts ex.message
+                    rescue Exception => ex
+                        $stderr.puts ex.inspect
+                        raise
+                    end
+                else
+                    last_results = EvalResults.new(value, stdout)
                 end
 
                 return last_results

data/lib/rsql/eval_context.rb

@@ -28,13 +28,12 @@ module RSQL
 
         Registration = Struct.new(:name, :args, :bangs, :block, :usage, :desc)
 
-        CommandContext = Struct.new(:index, :incomplete, :last_results, :state)
-
         HEXSTR_LIMIT = 32
 
         def initialize
             @hexstr_limit = HEXSTR_LIMIT
             @last_cmd = nil
+            @results = nil
 
             @loaded_fns = []
             @init_registrations = []
@@ -66,15 +65,15 @@ module RSQL
 
         attr_accessor :bangs
 
-        def call_init_registrations(mysql)
+        def call_init_registrations
             @init_registrations.each do |sym|
                 reg = @registrations[sym]
                 sql = reg.block.call(*reg.args)
-                mysql.query(sql) if String === sql
+                query(sql) if String === sql
             end
         end
 
-        def load(fn)
+        def load(fn, init=true)
             ret = Thread.new {
                 begin
                     eval(File.read(fn), binding, fn)
@@ -89,11 +88,12 @@ module RSQL
                 $stderr.puts("#{ret.class}: #{ret.message}", bt, '')
             else
                 @loaded_fns << fn unless @loaded_fns.include?(fn)
+                call_init_registrations if init
             end
         end
 
         def reload
-            @loaded_fns.each{|fn| self.load(fn)}
+            @loaded_fns.each{|fn| self.load(fn, false)}
             puts "loaded: #{@loaded_fns.inspect}"
         end
 
@@ -111,8 +111,8 @@ module RSQL
 
         # safely evaluate Ruby content within our context
         #
-        def safe_eval(content, context, stdout)
-            @command_context = context
+        def safe_eval(content, results, stdout)
+            @results = results
 
             # allow a simple reload to be called directly as it requires a
             # little looser safety valve...

data/lib/rsql.rb

@@ -1,5 +1,5 @@
 module RSQL
-    VERSION = '0.1.3'
+    VERSION = '0.1.4'
 
     require 'rsql/mysql'
     require 'rsql/mysql_results'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rsql
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 19
   prerelease: 
   segments: 
   - 0
   - 1
-  - 3
-  version: 0.1.3
+  - 4
+  version: 0.1.4
 platform: ruby
 authors: 
 - Brad Robel-Forrest
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-13 00:00:00 Z
+date: 2011-05-15 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: net-ssh
@@ -39,8 +39,8 @@ description: |
   connection to an intermediary host for access to the MySQL server.
 
 email: brad+rsql@gigglewax.com
-executables: []
-
+executables: 
+- rsql
 extensions: []
 
 extra_rdoc_files: []
@@ -50,6 +50,7 @@ files:
 - README.txt
 - TODO
 - bin/rsql
+- example.rsqlrc
 - lib/rsql.rb
 - lib/rsql/commands.rb
 - lib/rsql/eval_context.rb
@@ -86,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.7.2
+rubygems_version: 1.8.2
 signing_key: 
 specification_version: 3
 summary: Ruby based MySQL command line with recipes.