rsql 0.1.4 → 0.1.5

data/README.rdoc

@@ -0,0 +1,86 @@
+= RSQL
+
+Homepage:: https://github.com/bradrf/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.
+
+=== Installation
+
+  gem install rsql
+
+== USAGE
+
+RSQL is invoked from the comamnd line using:
+
+  rsql [<options>] <mysql_host> [<database>] [-e [<query>]]
+
+=== Options
+
+-version::
+  Display the version of RSQL that is installed.
+
+-rc _rcfile_::
+  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 specifed (e.g. a /t will
+  separate fields with a tab character).
+
+-ssh _ssh_host_::
+  Establish an SSH connection before connecting to the MySQL host.
+
+-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.
+
+The _ssh_host_ and _mysql_host_ values may also provide _user_ and
+_password_ values using the following syntax:
+
+  [<user>[:<password>]@]<host>
+
+It is possible to provide empty passwords by simply having nothing
+listed between demarcation points:
+
+  root:@127.0.0.1
+
+Once at the +rsql+ prompt, normal MySQL queries can be entered as
+expected, ending each with a semicolon (;).
+
+== EXAMPLE
+
+Try walking through link:../example.rsqlrc.
+
+== LICENSE
+
+Copyright (C) 2011 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.

data/TODO

@@ -24,9 +24,6 @@
 
 * Consider using mysql's ping to determine if we need to reconnect.
 
-* 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
@@ -34,3 +31,7 @@
 
 * Consider adding the option to specify a dispalyer when registering a
   recipe.
+
+* Move everything in here into github issues.
+
+* Consder renaming "register" to "recipe"

data/bin/rsql

@@ -96,11 +96,6 @@ def split_login(str)
     end
 end
 
-if ARGV.delete('-help')
-    eval_context.help
-    exit
-end
-
 if ARGV.delete('-version')
     puts "#{bn} v#{RSQL::VERSION}"
     exit

data/example.rsqlrc

@@ -11,22 +11,30 @@
 
 # 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).
+# for usage).
+#
+#   rsql> .load 'example.rsqlrc';
 
-# After it's loaded try out the command ".list;" (without the
-# quotes).
+# 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 enter ".reload;" (without the double quotes) to
-# have your changes pulled in immediately without exiting your
-# session.
+# 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.
 
 ################################################################################
 
 # 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
+# MySQL variables for different read levels (e.g. SET SESSION
 # TRANSACTION ISOLATION LEVEL READ COMMITTED). Any number of these may
 # be defined.
 #
@@ -35,7 +43,8 @@
 register_init :setup_example, %q{
 CREATE TEMPORARY TABLE IF NOT EXISTS #{@rsql_table} (
   name VARCHAR(100),
-  value INT(11)
+  value INT(11),
+  stuff BLOB
 )
 }, :desc => 'Sets up example table for trying out RSQL.'
 
@@ -43,10 +52,15 @@ CREATE TEMPORARY TABLE IF NOT EXISTS #{@rsql_table} (
 # interpolated into it (our table name). 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.
+# initialization recipe. If you do this, you'll need to call the
+# setup_example initialization recipe again before moving on.
+#
+#   rsql> .setup_example;
 #
-register :cleanup, %q{
+register :cleanup_example, %q{
 DROP TEMPORARY TABLE IF EXISTS #{@rsql_table}
 }, :desc => 'Cleans up the example table.'
 
@@ -55,8 +69,10 @@ DROP TEMPORARY TABLE IF EXISTS #{@rsql_table}
 #
 # 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.
+#   rsql> .fill_table;
+#
+# Notice the use of hexify and squeeze! methods available from
+# EvalContext.
 #
 register :fill_table, :desc => 'Populate the example table.' do
     sql = ''
@@ -64,25 +80,65 @@ register :fill_table, :desc => 'Populate the example table.' do
         sql << "
 INSERT IGNORE INTO #{@rsql_table}
    SET  name='fancy#{i}',
-       value=#{i**i};
+       value=#{i**i},
+       stuff=#{hexify(rand((i+1)**100))};
 "
     end
     sqeeze!(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).
+#
+# This call will simply return results only for those bigger than some
+# value passed in.
+#
+#   rsql> .get_big_values 80000;
+#
+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.
+#
+# 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:
+#
+#   rsql> .last_query;
+#
+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:
 #
-# rsql> select * from rsql_example ! value => humanize_bytes;
+#   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 avaialble. Check out the rdoc for
+# class. There are several others available. 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.
+# 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.
+#
+#   rsql> .show_values_as_bytes;
 #
 register :show_values_as_bytes, %q{
 SELECT value FROM #{@rsql_table}
@@ -95,13 +151,15 @@ SELECT value FROM #{@rsql_table}
 # 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.
 #
 def pretty_names(name)
-    if name =~ /^(\w+)(\d+)$/
-        "#{$1} (#{$2})"
+    if m = name.match(/^(\w+)(\d+)$/)
+        "#{m[1]} (#{m[2]})"
     else
         name
     end
@@ -112,14 +170,13 @@ 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 takes a similar approach. Try this:
 #
-# rsql> select * from rsql_example | p @results;
+#   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
@@ -130,9 +187,9 @@ SELECT name FROM #{@rsql_table}
 # 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;
+#   rsql> select name, value from rsql_example | to_report;
 #
-register :to_report do
+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|
@@ -145,4 +202,78 @@ register :to_report 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.
+#
+#   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.
+#
+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.
+#
+#   rsql> .find_names 'fancy3', 'fancy8'
+#
+# 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
+# EvalContext's query helper comes in handy.
+#
+# The intention here is to just create a series of sentences out of
+# two separate queries.
+#
+#   rsql> .show_sentences;
+#
+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 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.
+#
+# RSQL makes querying for hex strings from within a recipe easy too.
+#
+#   rsql> .find_stuff 0x346950d3c051c8ac51092a3a2eff7503ef7f571c
+#
+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 rdoc for EvalContext and MySQLResults would be
+# an excellent start.
+
 # vi: set filetype=ruby

data/lib/rsql.rb

@@ -1,5 +1,8 @@
+# A module encapsulating classes to manage MySQLResults and process
+# Commands using an EvalContext for handling recipes.
+#
 module RSQL
-    VERSION = '0.1.4'
+    VERSION = '0.1.5'
 
     require 'rsql/mysql'
     require 'rsql/mysql_results'

data/lib/rsql/commands.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright (C) 2011 by Brad Robel-Forrest <brad+rsql@gigglewax.com>
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -33,9 +34,11 @@ module RSQL
 
         ########################################
 
-        # split on separators, allowing for escaping
-        #
+        # Split commands on these characters.
         SEPARATORS = ';|!'
+
+        # Split on separators, allowing for escaping;
+        #
         def initialize(input, default_displayer)
             @default_displayer = default_displayer
             @cmds = []

data/lib/rsql/eval_context.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright (C) 2011 by Brad Robel-Forrest <brad+rsql@gigglewax.com>
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -22,7 +23,7 @@ module RSQL
 
     ################################################################################
     # This class wraps all dynamic evaluation and serves as the reflection
-    # class for adding new methods dynamically.
+    # class for adding methods dynamically.
     #
     class EvalContext
 
@@ -32,8 +33,8 @@ module RSQL
 
         def initialize
             @hexstr_limit = HEXSTR_LIMIT
-            @last_cmd = nil
             @results = nil
+            @last_query = nil
 
             @loaded_fns = []
             @init_registrations = []
@@ -48,10 +49,10 @@ module RSQL
                                             method(:reload),
                                             'reload',
                                             'Reload the rsqlrc file.'),
-                :last_cmd => Registration.new('last_cmd', [], {},
-                                              Proc.new{puts @last_cmd},
-                                              'last_cmd',
-                                              'Print the last command generated.'),
+                :last_query => Registration.new('last_query', [], {},
+                                                Proc.new{puts(@last_query)},
+                                                'last_query',
+                                                'Print the last query made from generated results.'),
                 :set_max_rows => Registration.new('set_max_rows', [], {},
                                                   Proc.new{|r| MySQLResults.max_rows = r},
                                                   'set_max_rows',
@@ -109,7 +110,7 @@ module RSQL
             return val
         end
 
-        # safely evaluate Ruby content within our context
+        # Safely evaluate Ruby content within our context.
         #
         def safe_eval(content, results, stdout)
             @results = results
@@ -141,12 +142,12 @@ module RSQL
                 $stdout = orig_stdout if stdout
             end
 
-            @last_cmd = value if String === value
+            @last_query = value if String === value
 
             return value
         end
 
-        # provide a list of tab completions given the prompted value
+        # Provide a list of tab completions given the prompted value.
         #
         def complete(str)
             if str[0] == ?.
@@ -170,13 +171,13 @@ module RSQL
             ret
         end
 
-        # reset the hexstr limit back to the default value
+        # Reset the hexstr limit back to the default value.
         #
         def reset_hexstr_limit
             @hexstr_limit = HEXSTR_LIMIT
         end
 
-        # convert a binary string value into a hexadecimal string
+        # Convert a binary string value into a hexadecimal string.
         #
         def to_hexstr(bin, limit=@hexstr_limit, prefix='0x')
             cnt = 0
@@ -201,9 +202,9 @@ module RSQL
         ########################################
         private
 
-            # display a listing of all registered helpers
+            # Display a listing of all registered helpers.
             #
-            def list
+            def list            # :doc:
                 usagelen = 0
                 desclen  = 0
 
@@ -226,35 +227,35 @@ module RSQL
                 return nil
             end
 
-            # show all the pertinent version data we have about our
-            # software and the mysql connection
+            # Show all the pertinent version data we have about our
+            # software and the mysql connection.
             #
-            def version
+            def version         # :doc:
                 puts "rsql:v#{RSQL::VERSION} client:v#{MySQLResults.conn.client_info} " \
                      "server:v#{MySQLResults.conn.server_info}"
             end
 
-            # provide a helper utility in the event a registered
-            # method would like to make its own queries
+            # Provide a helper utility in the event a registered
+            # method would like to make its own queries.
             #
-            def query(content, *args)
+            def query(content, *args) # :doc:
                 MySQLResults.query(content, self, *args)
             end
 
-            # exactly like register below except in addition to registering as
+            # Exactly like register below except in addition to registering as
             # a usable call for later, we will also use these as soon as we
             # have a connection to MySQL.
             #
-            def register_init(sym, *args, &block)
+            def register_init(sym, *args, &block) # :doc:
                 register(sym, *args, &block)
                 @init_registrations << sym
             end
 
-            # if given a block, allow the block to be called later, otherwise,
+            # If given a block, allow the block to be called later, otherwise,
             # create a method whose sole purpose is to dynmaically generate
-            # sql with variable interpolation
+            # sql with variable interpolation.
             #
-            def register(sym, *args, &block)
+            def register(sym, *args, &block) # :doc:
                 name = usage = sym.to_s
 
                 if Hash === args.last
@@ -282,9 +283,9 @@ module RSQL
                 @registrations[sym] = Registration.new(name, args, bangs, block, usage, desc)
             end
 
-            # convert a collection of values into to hexadecimal strings
+            # Convert a collection of values into hexadecimal strings.
             #
-            def hexify(*ids)
+            def hexify(*ids)    # :doc:
                 ids.collect do |id|
                     case id
                     when String
@@ -301,7 +302,7 @@ module RSQL
                 end.join(',')
             end
 
-            # convert a number of bytes into a human readable string
+            # Convert a number of bytes into a human readable string.
             #
             def humanize_bytes(bytes)
                 abbrev = ['B','KB','MB','GB','TB','PB','EB','ZB','YB']
@@ -322,9 +323,9 @@ module RSQL
                 return bytes.to_s
             end
 
-            # convert a human readable string of bytes into an integer
+            # Convert a human readable string of bytes into an integer.
             #
-            def dehumanize_bytes(str)
+            def dehumanize_bytes(str) # :doc:
                 abbrev = ['B','KB','MB','GB','TB','PB','EB','ZB','YB']
 
                 if str =~ /(\d+(\.\d+)?)\s*(\w+)?/
@@ -340,9 +341,9 @@ module RSQL
                 raise "unable to parse '#{str}'"
             end
 
-            # convert a time into a relative string from now
+            # Convert a time into a relative string from now.
             #
-            def relative_time(dt)
+            def relative_time(dt) # :doc:
                 return dt unless String === dt
 
                 now = Time.now.utc
@@ -372,19 +373,19 @@ module RSQL
                 return "#{fmt % diff} seconds #{postfix}"
             end
 
-            # squeeze out any spaces
+            # Squeeze out any spaces.
             #
-            def sqeeze!(sql)
+            def sqeeze!(sql)    # :doc:
                 sql.gsub!(/\s+/,' ')
                 sql.strip!
                 sql << ';' unless sql[-1] == ?;
                 sql
             end
 
-            # safely store an object into a file keeping at most one
-            # backup if the file already exists
+            # Safely store an object into a file keeping at most one
+            # backup if the file already exists.
             #
-            def safe_save(obj, name)
+            def safe_save(obj, name) # :doc:
                 name += '.yml' unless File.extname(name) == '.yml'
                 tn = "#{name}.tmp"
                 File.open(tn, 'w'){|f| YAML.dump(obj, f)}

data/lib/rsql/mysql_results.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright (C) 2011 by Brad Robel-Forrest <brad+rsql@gigglewax.com>
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -21,7 +22,7 @@
 module RSQL
 
     ########################################
-    # A wrapper to make it easier to work with MySQL results (and prettier)
+    # A wrapper to make it easier to work with MySQL results (and prettier).
     #
     class MySQLResults
 
@@ -51,20 +52,21 @@ module RSQL
             def max_rows; @@max_rows; end
             def max_rows=(cnt); @@max_rows = cnt; end
 
-            # get the name of the current database in use
+            # Get the name of the current database in use.
             #
             def database_name; @@database_name; end
 
-            # get the list of databases available
+            # Get the list of databases available.
             #
             def databases
                 @@databases ||= @@conn.list_dbs.sort if @@conn
             end
 
-            # get the list of tables available (if a database is
-            # selected) at most once every ten seconds
-            #
             @@last_table_list = Hash.new{|h,k| h[k] = [Time.at(0), []]}
+
+            # Get the list of tables available (if a database is
+            # selected) at most once every ten seconds.
+            #
             def tables(database = nil)
                 now = Time.now
                 (last, tables) = @@last_table_list[database]
@@ -85,8 +87,8 @@ module RSQL
                 tables
             end
 
-            # provide a list of tab completions given the prompted
-            # value
+            # Provide a list of tab completions given the prompted
+            # value.
             #
             def complete(str)
                 return [] unless @@conn
@@ -116,7 +118,7 @@ module RSQL
                 return ret
             end
 
-            # get results from a query
+            # Get results from a query.
             #
             def query(sql, eval_context, raw=false, max_rows=@@max_rows)
                 start   = Time.now.to_f
@@ -199,31 +201,35 @@ module RSQL
             end
         end
 
-        # get the number of rows that were affected by the query
+        # Get the query associated with these results.
         #
-        attr_reader :sql, :affected_rows
+        attr_reader :sql
 
-        # determine if there are any results
+        # Get the number of rows that were affected by the query.
+        #
+        attr_reader :affected_rows
+
+        # Determine if there are any results.
         #
         def any?
             !@table.nil?
         end
 
-        # determine if there are no results
+        # Determine if there are no results.
         #
         def empty?
             @table.nil?
         end
 
-        # get the number of rows available in the results
+        # Get the number of rows available in the results.
         #
         def num_rows
             @table ? @table.size : 0
         end
 
-        # get a row from the table hashed with the field names
+        # Get a row from the table hashed with the field names.
         #
-        def row_hash(index)
+        def [](index)
             hash = {}
             if @fields && @table
                 row = @table[index]
@@ -232,8 +238,8 @@ module RSQL
             return hash
         end
 
-        # iterate through each row of the table hashed with the field
-        # names
+        # Iterate through each row of the table hashed with the field
+        # names.
         #
         def each_hash(&block)
             if @table
@@ -245,7 +251,7 @@ module RSQL
             end
         end
 
-        # show a set of results in a decent fashion
+        # Show a set of results in a decent fashion.
         #
         def display_by_column(io=$stdout)
             if @fields && @table
@@ -268,7 +274,7 @@ module RSQL
             end
         end
 
-        # show a set of results with a single character separation
+        # Show a set of results with a single character separation.
         #
         def display_by_batch(io=$stdout)
             if @fields && @table
@@ -277,7 +283,7 @@ module RSQL
             end
         end
 
-        # show a set of results line separated
+        # Show a set of results line separated.
         #
         def display_by_line(io=$stdout)
             if @fields && @table
@@ -297,6 +303,8 @@ module RSQL
             display_stats(io)
         end
 
+        # Show a summary line of the results.
+        #
         def display_stats(io=$stdout, hdr='')
             if @table
                 if @database_changed

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rsql
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: 
   segments: 
   - 0
   - 1
-  - 4
-  version: 0.1.4
+  - 5
+  version: 0.1.5
 platform: ruby
 authors: 
 - Brad Robel-Forrest
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-15 00:00:00 Z
+date: 2011-05-16 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: net-ssh
@@ -34,7 +34,7 @@ dependencies:
   type: :runtime
   version_requirements: *id001
 description: |
-  Rsql makes working with a MySQL command line more convenient through
+  RSQL makes working with a MySQL command line more convenient through
   the use of recipes and embedding the common operation of using a SSH
   connection to an intermediary host for access to the MySQL server.
 
@@ -43,11 +43,11 @@ executables:
 - rsql
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- README.rdoc
 files: 
 - LICENSE
-- README.txt
+- README.rdoc
 - TODO
 - bin/rsql
 - example.rsqlrc
@@ -60,8 +60,11 @@ homepage: https://github.com/bradrf/rsql
 licenses: []
 
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --title
+- RSQL Documentation
+- --main
+- README.rdoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 

data/README.txt

@@ -1,130 +0,0 @@
-= rsql
-
-https://github.com/bradrf/rsql
-
-== DESCRIPTION
-
-This is an application to make working with a SQL command line more
-convenient by allowing interaction with Ruby in addition to embedding
-the common operation of using a SSH connection to an intermediary host
-for access to the SQL server.
-
-== SYNOPSIS
-
-Run rsql with no arguments for usage.
-
-Aside from the standard MySQL command syntax, the following
-functionality allows for a little more expressive processing.
-
-Multiple commands can be issued in one set by separation with
-semicolons.
-
-Generating SQL
---------------
-
-Ruby code may be called to generate the SQL that is to be executed.
-This is done by starting any command string with a period. If the
-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';
-
-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
-interpolation. Use of the 'register' helper is recommended for this
-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}'
- }
-
-...then from the prompt:
-
- 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 :dummy, :hello do |*args|
-   p args
- end
-
- rsql> . dummy :world;
-
-All registered methods can be listed using the built-in 'list'
-command.
-
-Changes to a sourced file can be reloaded using the built-in 'reload'
-command.
-
-Processing Column Data
-----------------------
-
-Ruby can be called to process any data on a per-column basis before a
-displayer is used to render the output. In this way, one can write
-Ruby to act like MySQL functions on all the data for a given column,
-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;
-
-This will call 'bin_to_str' for each 'IpAddress' returned from the
-query. Mulitple mappings are separated by a comma. These mappings can
-also be utilized in a canned method. Example:
-
- register :all_ips, 'select IpAddress from Devices', 'IpAddress' => :bin_to_str
-
-Redirection
------------
-
-Output from one or more queries may be post-processed dynamically. If
-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 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
-
-Copyright (C) 2011 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.