rsql 0.2.8 → 0.2.9

data/README.rdoc

@@ -4,19 +4,20 @@ Homepage:: https://rubygems.org/gems/rsql
 
 == DESCRIPTION
 
-This is an application to make working with a SQL command line more
-convenient by allowing interaction with recipes and Ruby code in
-addition to embedding the common operation of using a SSH connection
-to an intermediary host for access to the SQL server.
+This is an application to make working with a SQL command line more convenient
+by allowing interaction with recipes and Ruby code in addition to embedding the
+common operation of using a SSH connection to an intermediary host for access to
+the SQL server.
 
 === Installation
 
   gem install rsql
 
-Alternatively, RSQL can be downloaded as a tar.gz or zip and run
-directly from within the unpacked source directory as long as the
-MySQL Ruby library is available. SSH functionality will be disabled
-unless the Net::SSH Ruby library is also installed and available.
+Alternatively, RSQL can be downloaded as a tar.gz or zip and run directly from
+within the unpacked source directory as long as the {MySQL Ruby
+library}[https://rubygems.org/gems/mysqlplus] is available. SSH functionality
+will be disabled unless the {Net::SSH Ruby
+library}[https://rubygems.org/gems/net-ssh] is also installed and available.
 
 == USAGE
 
@@ -33,68 +34,67 @@ RSQL is invoked from the command line using:
   Display details on SSH connections and evaluation stack traces.
 
 -rc _rcfile_::
-  Override loading the .rsqlrc file from the HOME directory for one in
-  a different location.
+  Override loading the .rsqlrc file from the HOME directory for one in a
+  different location.
 
 -maxrows _max_::
   Override the maximum number of rows to process.
 
 -batch _field_separator_::
-  Run in batch mode using the separator specified (e.g. a /t will
-  separate fields with a tab character).
+  Run in batch mode using the separator specified (e.g. a /t will separate
+  fields with a tab character).
 
 -ssh _ssh_host_::
   Establish a SSH connection before connecting to the MySQL host.
 
 -sshconfig _ssh_config_::
-  Use a specific SSH configuration file instead of the default files
-  loaded at runtime by Net::SSH.
+  Use a specific SSH configuration file instead of the default files loaded at
+  runtime by Net::SSH.
 
 -e [_query_]::
-  Run a query from the command line (i.e. not interactive). If a
-  _query_ is not provided, STDIN will be read. Multiple commands can
-  be issued in one set by separation with semicolons just as if they
-  had been provided at the RSQL prompt interactively. This option
-  *must* be the last option specified.
+  Run a query from the command line (i.e. not interactive). If a _query_ is not
+  provided, STDIN will be read. Multiple commands can be issued in one set by
+  separation with semicolons just as if they had been provided at the RSQL
+  prompt interactively. This option *must* be the last option specified.
 
-The _ssh_host_ and _mysql_host_ arguments may optionally include
-_user_, _password_, or _port_ values using the following syntax:
+The _ssh_host_ and _mysql_host_ arguments may optionally include _user_,
+_password_, or _port_ values using the following syntax:
 
   [<user>[:<password>]@]<host>[:<port>]
 
-Once at the +rsql+ prompt, normal MySQL queries can be entered as
-expected, ending each with a semicolon (;) for columnar output or \\G
-for line-by-line output formatting.
+Once at the +rsql+ prompt, normal MySQL queries can be entered as expected,
+ending each with a semicolon (;) for columnar output or \\G for line-by-line
+output formatting.
 
-Ruby commands will be evaluated for any content entered at the RSQL
-prompt beginning with a period.
+Ruby commands will be evaluated for any content entered at the RSQL prompt
+beginning with a period.
 
 ==== Command Line Examples
 
-Connect as the "root" user to a MySQL server running on the local
-host, with no password (because there are no characters listed between
-the colon and the at sign):
+Connect as the "root" user to a MySQL server running on the local host, with no
+password (because there are no characters listed between the colon and the at
+sign):
 
   rsql root:@127.0.0.1
 
-Connect as the "readonly" user to the "internal.database.acme.com"
-host's MySQL server after establishing a SSH tunnel to the
-"external.acme.com" gateway. In this case, we are expecting that our
-SSH configuration is set up with the right user name. Because we did
-not provide a password for MySQL, one will be obtained directly from
-the console (without echoing the characters typed):
+Connect as the "readonly" user to the "internal.database.acme.com" host's MySQL
+server after establishing a SSH tunnel to the "external.acme.com" gateway. In
+this case, we are expecting that our SSH configuration is set up with the right
+user name. Because we did not provide a password for MySQL, one will be obtained
+directly from the console (without echoing the characters typed):
 
   rsql -ssh external.acme.com readonly@internal.database.acme.com
 
 == GETTING STARTED
 
-This example walks through many features of RSQL including how to
-build up recipes:
+This example walks through many features of RSQL including how to build up
+recipes:
 
-https://github.com/bradrf/rsql/raw/master/example.rsqlrc
+Try out the simple examples in rdoc-ref:example.rsqlrc.rdoc for a painless
+introduciton for how to leverage RSQL.
 
-The file is available as example.rsqlrc installed with the gem or
-downloaded with the source.
+The file is available as example.rsqlrc installed with the gem or downloaded
+with the source.
 
 == LICENSE
 
@@ -102,21 +102,19 @@ RSQL is licensed under the MIT License:
 
 Copyright (C) 2011-2012 by Brad Robel-Forrest <brad+rsql@gigglewax.com>
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/bin/rsql

@@ -179,14 +179,14 @@ end
 
 if i = ARGV.index('-e')
     ARGV.delete_at(i)
-    batch_input = ''
+    opts.batch_input = ''
     ARGV.delete_if do |arg|
         arg_i = ARGV.index(arg)
         if i <= arg_i
-            batch_input << ' ' << arg
+            opts.batch_input << ' ' << arg
         end
     end
-    batch_input.strip!
+    opts.batch_input.strip!
 end
 
 show_usage = false
@@ -235,9 +235,9 @@ end
 
 MySQLResults.database_name = ARGV.shift
 
-if !$stdin.tty? && batch_input.nil?
+if !$stdin.tty? && opts.batch_input.nil?
     # accept commands from stdin
-    batch_input = $stdin.read.gsub(/\r?\n/,';')
+    opts.batch_input = $stdin.read.gsub(/\r?\n/,';')
 end
 
 # make sure we remove any duplicates when we add to the history to
@@ -277,7 +277,7 @@ if opts.ssh_host
 
     password_retry_cnt = 0
 
-    unless batch_input
+    unless opts.batch_input
         print "SSH #{opts.ssh_user}#{opts.ssh_user ? '@' : ''}#{opts.ssh_host}..."
         $stdout.flush
     end
@@ -297,7 +297,7 @@ if opts.ssh_host
         ssh_enabled = false
         Signal.trap('INT', 'IGNORE')
         Signal.trap('TERM') do
-            $stderr.puts 'Closing SSH connection...' unless batch_input
+            $stderr.puts 'Closing SSH connection...' unless opts.batch_input
             ssh_enabled = false
         end
         ssh_opts = {:timeout => 15}
@@ -313,7 +313,7 @@ if opts.ssh_host
             ssh = Net::SSH.start(opts.ssh_host, opts.ssh_user, ssh_opts)
             ssh_opts.delete(:password)
             ssh_enabled = true
-            printf "connected (#{$$})..." unless batch_input
+            printf "connected (#{$$})..." unless opts.batch_input
             $stdout.flush
         rescue Net::SSH::AuthenticationFailed
             if 2 < password_retry_cnt
@@ -337,7 +337,7 @@ if opts.ssh_host
         ensure
             if ssh_enabled
                 ssh.forward.local(opts.mysql_port, opts.mysql_host, opts.remote_mysql_port)
-                unless batch_input
+                unless opts.batch_input
                     puts(opts.verbose ? "ready (#{opts.mysql_port} => #{opts.remote_mysql_port})" : 'ready')
                 end
                 File.open(ipc_fn,'w'){|f| f.puts('ready')}
@@ -393,7 +393,7 @@ if opts.ssh_host
     opts.mysql_host = '127.0.0.1'
 end
 
-unless batch_input
+unless opts.batch_input
     print "MySQL #{opts.mysql_user}@#{opts.remote_mysql_host}..."
     $stdout.flush
 end
@@ -403,7 +403,7 @@ begin
     MySQLResults.conn = Mysql.new(opts.mysql_host, opts.mysql_user, opts.mysql_password,
                                   MySQLResults.database_name, opts.mysql_port)
     MySQLResults.conn.reconnect = true
-    puts 'connected' unless batch_input
+    puts 'connected' unless opts.batch_input
 rescue Mysql::Error => ex
     if ex.message.include?('Client does not support authentication')
         $stderr.puts "failed to connect to #{mysql_conn} mysql server: unknown credentials?"
@@ -440,10 +440,10 @@ cmd_thread = Thread.new do
     me[:shutdown] = false
     until me[:shutdown] do
         default_displayer = :display_by_column
-        if batch_input
+        if opts.batch_input
             default_displayer = :display_by_batch if opts.batch_output
             me[:shutdown] = true         # only run once
-            input = batch_input
+            input = opts.batch_input
         else
             puts '',"[#{opts.mysql_user}@#{opts.ssh_host||opts.mysql_host}:#{MySQLResults.database_name}]"
             input = ''

data/example.rsqlrc

@@ -1,42 +1,44 @@
 # -*- 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.
+# = Getting Starting with RSQL
 
-# 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.
+# 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 the following 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).
+# To use this file, change directory to the one containing this file and run
+# RSQL connecting to your MySQL server (run rsql with no arguments for
+# usage--see rdoc-ref:README.rdoc for more details on command line parameters).
 #
 #   rsql> .load 'example.rsqlrc';
 
-# After it's loaded try listing out all the registered recipes (along
-# with parameter notes and descriptions).
+# After it's loaded try listing out all the registered recipes (along with
+# parameter notes and descriptions).
 #
 #   rsql> .list;
 
-# If you make changes to the example to try out new things (and please
-# do!), you can simply have the recipe file reloaded to have your
-# changes pulled in immediately without exiting your session.
+# If you make changes to the example to try out new things (and please do!), you
+# can simply have the recipe file reloaded to have your changes pulled in
+# immediately without exiting your session.
 #
 #   rsql> .reload;
 
 # Notice that any command issued starting with a period (.) results in
-# evaluation of Ruby. Thus, any valid Ruby syntax is applicable
-# following a period on a command.
+# evaluation of Ruby. Thus, any valid Ruby syntax is applicable following a
+# period on a command.
 
 ################################################################################
 
-# 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.
+# Use of RSQL::EvalContext#register_init allows a block to be 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. <b><tt>SET
+# SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED</tt></b>). Any number of
+# these may be defined.
 #
 # Here we are merely setting up the example table.
 #
@@ -48,15 +50,15 @@ CREATE TEMPORARY TABLE IF NOT EXISTS #{@rsql_table} (
 )
 }, :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.
+# This next recipe is building up a string with a single variable interpolated
+# into it (our table name) through RSQL::EvalContext#register. The string will
+# then be used as if typed at the command line.
 #
 #   rsql> .cleanup_example;
 #
-# In this case, we are simply dropping the table created by our
-# initialization recipe. If you do this, you'll need to call the
-# setup_example initialization recipe again before moving on.
+# In this case, we are simply dropping the table created by our initialization
+# recipe. If you do this, you'll need to call the <b><tt>setup_example</tt></b>
+# initialization recipe again before moving on.
 #
 #   rsql> .setup_example;
 #
@@ -64,15 +66,15 @@ register :cleanup_example, %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.
+# 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).
 #
 #   rsql> .fill_table;
 #
-# Notice the use of hexify and squeeze! methods available from
-# EvalContext.
+# Notice the use of the RSQL::EvalContext#hexify and RSQL::EvalContext#squeeze!
+# helper methods.
 #
 register :fill_table, :desc => 'Populate the example table.' do
     sql = ''
@@ -84,9 +86,8 @@ INSERT IGNORE INTO #{@rsql_table}
        stuff=#{hexify(rand((i+1)**100))};
 }
     end
-    # one more that isn't randomly generated so we can reference it
-    # later
-        sql << %{
+    # one more that isn't randomly generated so we can reference it later
+    sql << %{
 INSERT IGNORE INTO #{@rsql_table}
    SET  name='fancy9',
        value=#{9**9},
@@ -95,14 +96,13 @@ INSERT IGNORE INTO #{@rsql_table}
     squeeze!(sql)
 end
 
-# A very common reason for recipes is simply to add parameters to be
-# dropped in to our query. To facilitate this, simply declare one or
-# more variables immediately following the name of the recipe. Then
-# these values can be listed by embedded interpolation points into the
-# string (just as you would with any Ruby string).
+# A very common reason for recipes is simply to add parameters to be dropped in
+# to our query. To facilitate this, declare one or more variables immediately
+# following the name of the recipe. These values can be listed by embedded
+# interpolation points into the string (just as you would with any Ruby string).
 #
-# This call will simply return results only for those bigger than some
-# value passed in.
+# This call will simply return results only for those bigger than some value
+# passed in.
 #
 #   rsql> .get_big_values 80000;
 #
@@ -110,19 +110,19 @@ register :get_big_values, :val, %q{
 SELECT name, value FROM #{@rsql_table} WHERE #{val} <= value
 }, :desc => 'Get values bigger than the one provided as an argument.'
 
-# Sometimes we make mistakes (never!). Normally, the command history
-# kept in RSQL only stores the last thing entered at the prompt--not
-# any query that the previous command may have generated and invoked.
-# When writing a recipe that generates a query that has an error
-# reported by MySQL, it is really handy to see the query.
+# Sometimes we make mistakes (never!). Normally, the command history kept in
+# RSQL only stores the last thing entered at the prompt--not any query that the
+# previous command may have generated and invoked.  When writing a recipe that
+# generates a query that has an error reported by MySQL, it is really handy to
+# see the generated SQL.
 #
-# Here's an example of a recipe that will fail. Run it and then hit the
-# "up arrow" key to see the previous command.
+# Here's an example of a recipe that will fail. Run it and then hit the "up
+# arrow" key to see the previous command.
 #
 #   rsql> .bad_query;
 #
-# So the command in our history is the recipe and not the query. To
-# see the query the EvalContext has a recipe ready for us:
+# So the command in our history is the recipe and not the query. To see the
+# query the RSQL::EvalContext#history has a helper method ready for us:
 #
 #   rsql> .history;
 #
@@ -130,21 +130,20 @@ register :bad_query, %q{
 SELECT name, value FROM #{@rsql_table} WHERE valu < 10000
 }, :desc => 'Make a query that will result in an error.'
 
-# 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:
+# 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 name, value from rsql_example ! value => humanize_bytes;
 #
-# The humanize_bytes method is a helper in the EvalContext
-# class. There are several others available. Check out the rdoc for
-# details.
+# The RSQL::EvalContext#humanize_bytes is another helper method. There are
+# several others available. Check out the RSQL::EvalContext class for details.
 #
 # Additional mappings can be added, separated by commas.
 #
-# You can also declare these column mappings in your recipes, though
-# the syntax is slightly different, using Ruby symbols.
+# You can also declare these column mappings in your recipes, though the syntax
+# is slightly different, using Ruby symbols.
 #
 #   rsql> .show_values_as_bytes;
 #
@@ -153,17 +152,16 @@ 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.
+# 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.
 #
 #   rsql> .show_pretty_names;
 #
-# 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.
+# 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 m = name.match(/^(\w+)(\d+)$/)
@@ -178,22 +176,22 @@ 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 approach. Try this:
+# 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 approach. Try
+# this:
 #
 #   rsql> select name, value 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.
+# The RSQL::EvalContext class manages the results from a previous query in the
+# <b><tt>@results</tt></b> member variable accessible by any Ruby recipe
+# code. This is an instance of the RSQL::MySQLResults class. Below we make use
+# of the RSQL::MySQLResults#each_hash method to walk over all rows. There are
+# other helpful routines available.
 #
-# 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:
+# 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 name, value from rsql_example | to_report;
 #
@@ -210,19 +208,17 @@ register :to_report, :desc => 'Report on a count of small and big values.' do
     puts "There are #{small_cnt} small values and #{big_cnt} big values."
 end
 
-# There may be other moments where it's necessary to take arguments,
-# say if we want to process results and keep our data around in a
-# file.
+# There may be other moments where it's necessary to take arguments, say if we
+# want to process results and keep our data around in a file.
 #
 #   rsql> select name, value from rsql_example | save_values 'myobj';
 #
-# After running this, a myobj.yml file should be created in the local
-# directory containing all the content from the query. To accomplish
-# this, the use of EvalContext's safe_save method is invoked which
-# serializes our object so that we may later decided to run some post
-# processing on the content.
+# After running this, a <b><tt>myobj.yml</tt></b> file should be created in the
+# local directory containing all the content from the query. To accomplish this,
+# the RSQL::EvalContext#safe_save method is invoked which serializes our object
+# so that we may later decided to run some post processing on the content.
 #
-# Inspect the YAML content written out:
+# Inspect the YAML[http://www.yaml.org/] content written out:
 #
 #   rsql> .puts IO.read('myobj.yml');
 #
@@ -234,8 +230,8 @@ register :save_values, :desc => 'Save results from a query into a file.' do |fn|
     safe_save(myobj, fn)
 end
 
-# Dealing with variable arguments is pretty straightforward as well,
-# but with a little syntactic twist.
+# Dealing with variable arguments is pretty straightforward as well, but with a
+# little syntactic twist.
 #
 #   rsql> .find_names 'fancy3', 'fancy8';
 #
@@ -247,14 +243,14 @@ SELECT name, value
  WHERE name IN (#{names.collect{|n| "'#{n}'"}.join(',')})
 }, :desc => 'Find names from example table.'
 
-# Sometimes it just isn't enough to be able to rely on generating SQL
-# queries and piping into handlers. Sometimes we just need to roll up
-# our sleeves and run queries directly so we can start processing
-# results and dealing with presentation all on our own. That's where
-# EvalContext's query helper comes in handy.
+# Sometimes it just isn't enough to be able to rely on generating SQL queries
+# and piping into handlers. Sometimes we just need to roll up our sleeves and
+# run queries directly so we can start processing results and dealing with
+# presentation all on our own. That's where the RSQL::EvalContext#query helper
+# comes in handy.
 #
-# The intention here is to just create a series of sentences out of
-# two separate queries.
+# The intention here is to just create a series of sentences out of two separate
+# queries.
 #
 #   rsql> .show_sentences;
 #
@@ -266,15 +262,14 @@ register :show_sentences, :desc => 'Show results as sentences.' do
     end
 end
 
-# The MySQLResults class built in to RSQL handles binary content
-# gracefully, automatically converting it to something a little nicer
-# to our consoles than just dumping it. It converts it into a
-# hexadecimal string.
+# The RSQL::MySQLResults class built in to RSQL handles binary content
+# gracefully, automatically converting it to something a little nicer to our
+# consoles than just dumping it. It converts it into a hexadecimal string.
 #
 #   rsql> SELECT stuff FROM rsql_example;
 #
-# The default is to limit the hex strings to 32 "bytes" reported. This
-# can be configured any time by setting the @hexstr_limit.
+# The default is to limit the hex strings to 32 "bytes" reported. This can be
+# configured any time by setting the <b><tt>@hexstr_limit</tt></b>.
 #
 # RSQL makes querying for hex strings from within a recipe easy too.
 #
@@ -285,7 +280,7 @@ SELECT * FROM #{@rsql_table} WHERE stuff=#{hexify stuff}
 }, :desc => 'Find some hex stuff.'
 
 # There are many other things to try out left as an "exercise for the
-# reader". Browsing the rdoc for EvalContext and MySQLResults would be
-# an excellent start.
+# reader". Browsing the RSQL::EvalContext and RSQL::MySQLResults classes would
+# be an excellent start.
 
 # vi: set filetype=ruby

data/example.rsqlrc.rdoc

@@ -0,0 +1,286 @@
+
+ 
+= Getting Starting with RSQL
+ 
+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 the following 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 and run
+RSQL connecting to your MySQL server (run rsql with no arguments for
+usage--see rdoc-ref:README.rdoc for more details on command line parameters).
+
+<tt>rsql> .load 'example.rsqlrc';</tt>
+ 
+After it's loaded try listing out all the registered recipes (along with
+parameter notes and descriptions).
+
+<tt>rsql> .list;</tt>
+ 
+If you make changes to the example to try out new things (and please do!), you
+can simply have the recipe file reloaded to have your changes pulled in
+immediately without exiting your session.
+
+<tt>rsql> .reload;</tt>
+ 
+Notice that any command issued starting with a period (.) results in
+evaluation of Ruby. Thus, any valid Ruby syntax is applicable following a
+period on a command.
+ 
+---
+ 
+Use of RSQL::EvalContext#register_init allows a block to be 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. <b><tt>SET
+SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED</tt></b>). 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),
+   stuff BLOB
+ )
+ }, :desc => 'Sets up example table for trying out RSQL.'
+ 
+This next recipe is building up a string with a single variable interpolated
+into it (our table name) through RSQL::EvalContext#register. The string will
+then be used as if typed at the command line.
+
+<tt>rsql> .cleanup_example;</tt>
+
+In this case, we are simply dropping the table created by our initialization
+recipe. If you do this, you'll need to call the <b><tt>setup_example</tt></b>
+initialization recipe again before moving on.
+
+<tt>rsql> .setup_example;</tt>
+
+ register :cleanup_example, %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).
+
+<tt>rsql> .fill_table;</tt>
+
+Notice the use of the RSQL::EvalContext#hexify and RSQL::EvalContext#squeeze!
+helper methods.
+
+ register :fill_table, :desc => 'Populate the example table.' do
+     sql = ''
+     9.times do |i|
+         sql << %{
+ INSERT IGNORE INTO #{@rsql_table}
+    SET  name='fancy#{i}',
+        value=#{i**i},
+        stuff=#{hexify(rand((i+1)**100))};
+ }
+     end
+     # one more that isn't randomly generated so we can reference it later
+     sql << %{
+ INSERT IGNORE INTO #{@rsql_table}
+    SET  name='fancy9',
+        value=#{9**9},
+        stuff=0x1234567891234567891234567890;
+ }
+     squeeze!(sql)
+ end
+ 
+A very common reason for recipes is simply to add parameters to be dropped in
+to our query. To facilitate this, declare one or more variables immediately
+following the name of the recipe. These values can be listed by embedded
+interpolation points into the string (just as you would with any Ruby string).
+
+This call will simply return results only for those bigger than some value
+passed in.
+
+<tt>rsql> .get_big_values 80000;</tt>
+
+ register :get_big_values, :val, %q{
+ SELECT name, value FROM #{@rsql_table} WHERE #{val} <= value
+ }, :desc => 'Get values bigger than the one provided as an argument.'
+ 
+Sometimes we make mistakes (never!). Normally, the command history kept in
+RSQL only stores the last thing entered at the prompt--not any query that the
+previous command may have generated and invoked.  When writing a recipe that
+generates a query that has an error reported by MySQL, it is really handy to
+see the generated SQL.
+
+Here's an example of a recipe that will fail. Run it and then hit the "up
+arrow" key to see the previous command.
+
+<tt>rsql> .bad_query;</tt>
+
+So the command in our history is the recipe and not the query. To see the
+query the RSQL::EvalContext#history has a helper method ready for us:
+
+<tt>rsql> .history;</tt>
+
+ register :bad_query, %q{
+ SELECT name, value FROM #{@rsql_table} WHERE valu < 10000
+ }, :desc => 'Make a query that will result in an error.'
+ 
+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:
+
+<tt>rsql> select name, value from rsql_example ! value => humanize_bytes;</tt>
+
+The RSQL::EvalContext#humanize_bytes is another helper method. There are
+several others available. Check out the RSQL::EvalContext class for details.
+
+Additional mappings can be added, separated by commas.
+
+You can also declare these column mappings in your recipes, though the syntax
+is slightly different, using Ruby symbols.
+
+<tt>rsql> .show_values_as_bytes;</tt>
+
+ 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.
+
+<tt>rsql> .show_pretty_names;</tt>
+
+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 m = name.match(/^(\w+)(\d+)$/)
+         "#{m[1]} (#{m[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 approach. Try
+this:
+
+<tt>rsql> select name, value from rsql_example | p @results;</tt>
+
+The RSQL::EvalContext class manages the results from a previous query in the
+<b><tt>@results</tt></b> member variable accessible by any Ruby recipe
+code. This is an instance of the RSQL::MySQLResults class. Below we make use
+of the RSQL::MySQLResults#each_hash method to walk over all rows. There are
+other helpful routines available.
+
+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:
+
+<tt>rsql> select name, value from rsql_example | to_report;</tt>
+
+ register :to_report, :desc => 'Report on a count of small and big values.' 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
+ 
+There may be other moments where it's necessary to take arguments, say if we
+want to process results and keep our data around in a file.
+
+<tt>rsql> select name, value from rsql_example | save_values 'myobj';</tt>
+
+After running this, a <b><tt>myobj.yml</tt></b> file should be created in the
+local directory containing all the content from the query. To accomplish this,
+the RSQL::EvalContext#safe_save method is invoked which serializes our object
+so that we may later decided to run some post processing on the content.
+
+Inspect the YAML[http://www.yaml.org/] content written out:
+
+<tt>rsql> .puts IO.read('myobj.yml');</tt>
+
+ register :save_values, :desc => 'Save results from a query into a file.' do |fn|
+     myobj = {}
+     @results.each_hash do |row|
+         myobj[row['name']] = row['value']
+     end
+     safe_save(myobj, fn)
+ end
+ 
+Dealing with variable arguments is pretty straightforward as well, but with a
+little syntactic twist.
+
+<tt>rsql> .find_names 'fancy3', 'fancy8';</tt>
+
+Here we simply expand the arguments.
+
+ register :find_names, :'*names', %q{
+ SELECT name, value
+   FROM #{@rsql_table}
+  WHERE name IN (#{names.collect{|n| "'#{n}'"}.join(',')})
+ }, :desc => 'Find names from example table.'
+ 
+Sometimes it just isn't enough to be able to rely on generating SQL queries
+and piping into handlers. Sometimes we just need to roll up our sleeves and
+run queries directly so we can start processing results and dealing with
+presentation all on our own. That's where the RSQL::EvalContext#query helper
+comes in handy.
+
+The intention here is to just create a series of sentences out of two separate
+queries.
+
+<tt>rsql> .show_sentences;</tt>
+
+ register :show_sentences, :desc => 'Show results as sentences.' do
+     query("SELECT name FROM #{@rsql_table}").each_hash do |nrow|
+         name = nrow['name']
+         vals = query("SELECT value FROM #{@rsql_table} WHERE name='#{name}'")
+         puts "The #{name} has #{vals[0]['value']} fanciness levels."
+     end
+ end
+ 
+The RSQL::MySQLResults class built in to RSQL handles binary content
+gracefully, automatically converting it to something a little nicer to our
+consoles than just dumping it. It converts it into a hexadecimal string.
+
+<tt>rsql> SELECT stuff FROM rsql_example;</tt>
+
+The default is to limit the hex strings to 32 "bytes" reported. This can be
+configured any time by setting the <b><tt>@hexstr_limit</tt></b>.
+
+RSQL makes querying for hex strings from within a recipe easy too.
+
+<tt>rsql> .find_stuff 0x1234567891234567891234567890;</tt>
+
+ register :find_stuff, :stuff, %q{
+ SELECT * FROM #{@rsql_table} WHERE stuff=#{hexify stuff}
+ }, :desc => 'Find some hex stuff.'
+ 
+There are many other things to try out left as an "exercise for the
+reader". Browsing the RSQL::EvalContext and RSQL::MySQLResults classes would
+be an excellent start.
+ 
+

data/lib/rsql.rb

@@ -1,8 +1,11 @@
 # A module encapsulating classes to manage MySQLResults and process
 # Commands using an EvalContext for handling recipes.
 #
+# See the rdoc-ref:example.rsqlrc.rdoc file for a simple tutorial and usage
+# information.
+#
 module RSQL
-    VERSION = '0.2.8'
+    VERSION = '0.2.9'
 
     require 'rsql/mysql_results'
     require 'rsql/eval_context'

data/lib/rsql/eval_context.rb

@@ -63,7 +63,7 @@ module RSQL
                     'Show short syntax help.'),
                 :grep => Registration.new('grep', [], {},
                     method(:grep),
-                    'grep',
+                    'grep(string_or_regexp, *options)',
                     'Show results when regular expression matches any part of the content.'),
                 :reload => Registration.new('reload', [], {},
                     method(:reload),
@@ -71,7 +71,7 @@ module RSQL
                     'Reload the rsqlrc file.'),
                 :desc => Registration.new('desc', [], {},
                     method(:desc),
-                    'desc',
+                    'desc(name)',
                     'Describe the content of a recipe.'),
                 :history => Registration.new('history', [], {},
                     method(:history),
@@ -79,7 +79,7 @@ module RSQL
                     'Print recent queries made (request a count or use :all for entire list).'),
                 :set_max_rows => Registration.new('set_max_rows', [], {},
                     Proc.new{|r| MySQLResults.max_rows = r},
-                    'set_max_rows',
+                    'set_max_rows(max)',
                     'Set the maximum number of rows to process.'),
                 :max_rows => Registration.new('max_rows', [], {},
                     Proc.new{MySQLResults.max_rows},
@@ -334,59 +334,62 @@ module RSQL
                 return nil
             end
 
+            # Used by params() and desc() to find where a block begins.
+            #
+            def locate_block_start(name, io, lineno, ending=nil, source=nil)
+                i = 0
+                param_line = ''
+                params = nil
+
+                while line = io.gets
+                    i += 1
+                    next if i < lineno
+                    source << line if source
+
+                    # give up if no start found within 20 lines
+                    break if lineno + 20 < i
+                    if m = line.match(/(\{|do\b)(.*)$/)
+                        if ending
+                            ending << (m[1] == '{' ? '\}' : 'end')
+                        end
+                        # adjust line to be the remainder after the start
+                        param_line = m[2]
+                        break
+                    end
+                end
+
+                if m = param_line.match(/^\s*\|([^\|]*)\|/)
+                    return "(#{m[1]})"
+                else
+                    return nil
+                end
+            end
+
             # Attempt to locate the parameters of a given block by
             # searching its source.
             #
             def params(name, block)
-                params = ''
+                params = nil
 
-                if block.arity != 0 && block.arity != -1 &&
-                        block.inspect.match(/@(.+):(\d+)>$/)
+                if block.arity != 0 && block.inspect.match(/@(.+):(\d+)>$/)
                     fn = $1
                     lineno = $2.to_i
 
                     if fn == '(eval)'
                         $stderr.puts "refusing to search an eval block for :#{name}"
-                        return params
+                        return ''
                     end
 
                     File.open(fn) do |f|
-                        i = 0
-                        found = false
-                        while line = f.gets
-                            i += 1
-                            next if i < lineno
-
-                            unless found
-                                # give up if no start found within 20
-                                # lines
-                                break if lineno + 20 < i
-                                if m = line.match(/(\{|do\b)(.*)$/)
-                                    # adjust line to be the remainder
-                                    # after the start
-                                    line = m[2]
-                                    found = true
-                                else
-                                    next
-                                end
-                            end
-
-                            if m = line.match(/^\s*\|([^\|]*)\|/)
-                                params = "(#{m[1]})"
-                                break
-                            end
-
-                            # if the params aren't here then we'd
-                            # better only have whitespace otherwise
-                            # this block doesn't have params...even
-                            # though arity says it should
-                            next if line.match(/^\s*$/)
-                            $stderr.puts "unable to locate params for :#{name}"
-                            break
-                        end
+                        params = locate_block_start(name, f, lineno)
                     end
                 end
 
+                if params.nil?
+                    $stderr.puts "unable to locate params for :#{name}" if @verbose
+                    return ''
+                end
+
                 return params
             end
 
@@ -428,23 +431,13 @@ module RSQL
 
                     File.open(fn) do |f|
                         source = ''
-                        i = 0
-                        ending = nil
-                        found = false
+                        ending = ''
+
+                        locate_block_start(sym, f, lineno, ending, source)
+                        break if ending.empty?
 
                         while line = f.gets
-                            i += 1
-                            next unless ending || i == lineno
                             source << line
-                            unless ending
-                                unless m = line.match(/\{|do\b/)
-                                    $stderr.puts "unable to locate block beginning at #{fn}:#{lineno}"
-                                    return
-                                end
-                                ending = m[0] == '{' ? '\}' : 'end'
-                                next
-                            end
-
                             if m = line.match(/^#{ending}/)
                                 found = true
                                 break
@@ -503,7 +496,8 @@ EOF
             end
 
             # Provide a helper utility in the event a registered method would
-            # like to make its own queries.
+            # like to make its own queries. See MySQLResults.query for more
+            # details regarding the other arguments available.
             #
             def query(content, *args) # :doc:
                 MySQLResults.query(content, self, *args)
@@ -512,17 +506,17 @@ EOF
             # Show the most recent queries made to the MySQL server in this
             # session. Default is to show the last one.
             #
-            def history(cnt=1)
+            def history(cnt=1) # :doc:
                 if h = MySQLResults.history(cnt)
                     h.each{|q| puts '', q}
                 end
                 nil
             end
 
-            # Call MySQLResults' grep to remove (or show) only those lines that
+            # Call MySQLResults#grep to remove (or show) only those lines that
             # have content matching the patterrn.
             #
-            def grep(*args)
+            def grep(*args) # :doc:
                 if @results.grep(*args)
                     @results
                 else

data/lib/rsql/mysql_results.rb

@@ -24,7 +24,7 @@
 #
 require 'mysqlplus'
 
-class Mysql
+class Mysql # :nodoc:
     alias :query :async_query
 end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rsql
 version: !ruby/object:Gem::Version 
-  hash: 7
+  hash: 5
   prerelease: 
   segments: 
   - 0
   - 2
-  - 8
-  version: 0.2.8
+  - 9
+  version: 0.2.9
 platform: ruby
 authors: 
 - Brad Robel-Forrest
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-02-13 00:00:00 Z
+date: 2012-02-15 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: net-ssh
@@ -116,6 +116,7 @@ extensions: []
 extra_rdoc_files: 
 - README.rdoc
 - LICENSE
+- example.rsqlrc.rdoc
 files: 
 - LICENSE
 - README.rdoc
@@ -129,6 +130,7 @@ files:
 - test/test_commands.rb
 - test/test_eval_context.rb
 - test/test_mysql_results.rb
+- example.rsqlrc.rdoc
 homepage: https://rubygems.org/gems/rsql
 licenses: []
 
@@ -167,5 +169,7 @@ rubygems_version: 1.8.16
 signing_key: 
 specification_version: 3
 summary: Ruby-based MySQL command line with recipes.
-test_files: []
-
+test_files: 
+- test/test_commands.rb
+- test/test_eval_context.rb
+- test/test_mysql_results.rb