rsql 0.2.7 → 0.2.8

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2011-2012 by 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/example.rsqlrc

@@ -0,0 +1,291 @@
+# -*- 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).
+#
+#   rsql> .load 'example.rsqlrc';
+
+# 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.
+#
+#   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
+# 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),
+  stuff BLOB
+)
+}, :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.
+#
+#   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.
+#
+#   rsql> .setup_example;
+#
+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).
+#
+#   rsql> .fill_table;
+#
+# Notice the use of hexify and squeeze! methods available from
+# EvalContext.
+#
+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, 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> .history;
+#
+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 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.
+#
+# 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}
+}, '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.
+#
+#   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 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:
+#
+#   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.
+#
+# 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;
+#
+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.
+#
+#   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.
+#
+# Inspect the YAML content written out:
+#
+#   rsql> .puts IO.read('myobj.yml');
+#
+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 0x1234567891234567891234567890;
+#
+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

@@ -0,0 +1,10 @@
+# A module encapsulating classes to manage MySQLResults and process
+# Commands using an EvalContext for handling recipes.
+#
+module RSQL
+    VERSION = '0.2.8'
+
+    require 'rsql/mysql_results'
+    require 'rsql/eval_context'
+    require 'rsql/commands'
+end

data/lib/rsql/commands.rb

@@ -0,0 +1,243 @@
+#--
+# 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.
+
+module RSQL
+
+    require 'stringio'
+
+    EvalResults = Struct.new(:value, :stdout)
+
+    ########################################
+    # A wrapper to parse and handle commands
+    #
+    class Commands
+
+        Command = Struct.new(:content, :bangs, :declarator, :displayer)
+
+        ########################################
+
+        # Split commands on these characters.
+        SEPARATORS = ';|!'
+
+        # Split on separators, allowing for escaping;
+        #
+        def initialize(input, default_displayer)
+            @default_displayer = default_displayer
+            @cmds = []
+            esc = ''
+            bangs = {}
+            match_before_bang = nil
+            in_pipe_arg = false
+            next_is_ruby = false
+
+            input.scan(/[^#{SEPARATORS}]+.?/) do |match|
+                orig_match = match
+
+                if i = SEPARATORS.index(match[-1])
+                    sep = SEPARATORS[i]
+                    match.chop!
+
+                    if match[-1] == ?\\
+                        # unescape the separator and save the content away
+                        esc << match[0..-2] << sep
+                        next
+                    end
+                else
+                    sep = nil
+                end
+
+                unless esc.empty?
+                    esc << match
+                    match = esc
+                    esc = ''
+                end
+
+                if match_before_bang
+                    new_bangs = {}
+                    match.split(/\s*,\s*/).each do |ent|
+                        (key,val) = ent.split(/\s*=>\s*/)
+                        unless key && val
+                            # they are using a bang but have no maps
+                            # so we assume this is a != or something
+                            # similar and let it go through unmapped
+                            esc = match_before_bang + '!' + match
+                            match_before_bang = nil
+                            break
+                        end
+                        if val.strip == 'nil'
+                            new_bangs[key.strip] = nil
+                        else
+                            new_bangs[key.strip] = val.to_sym
+                        end
+                    end
+                    next unless match_before_bang
+                    match = match_before_bang
+                    match_before_bang = nil
+                    bangs.merge!(new_bangs)
+                end
+
+                if sep == ?!
+                    match_before_bang = match
+                    next
+                end
+
+                if sep == ?|
+                    # we've split on a pipe so we need to handle the
+                    # case where ruby code is declaring a block with
+                    # arguments (e.g. {|x| p x} or do |x| p x end)
+                    if in_pipe_arg
+                        in_pipe_arg = false
+                        esc << match << '|'
+                        next
+                    elsif orig_match =~ /\{\s*|do\s*/
+                        in_pipe_arg = true
+                        esc << match << '|'
+                        next
+                    end
+                end
+
+                add_command(match, bangs, next_is_ruby, sep)
+
+                bangs = {}
+                next_is_ruby = sep == ?|
+            end
+
+            add_command(esc, bangs, next_is_ruby)
+        end
+
+        def empty?
+            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?
+                cmd = @cmds.shift
+                results = run_command(cmd, last_results, eval_context)
+                return :done if results == :done
+
+                if cmd.displayer == :pipe
+                    last_results = results
+                elsif MySQLResults === results
+                    last_results = nil
+                    results.send(cmd.displayer)
+                elsif EvalResults === results
+                    last_results = nil
+                    if MySQLResults === results.value
+                        # This happens if their recipe returns MySQL
+                        # results...just display it like above.
+                        results.value.send(cmd.displayer)
+                    else
+                        if results.stdout && 0 < results.stdout.size
+                            puts results.stdout.string
+                        end
+                        puts "=> #{results.value.inspect}" if results.value
+                    end
+                end
+            end
+        end
+
+        ########################################
+        private
+
+            def add_command(content, bangs, is_ruby, separator=nil)
+                content.strip!
+
+                case content[0]
+                when ?.
+                    content.slice!(0)
+                    declarator = :ruby
+                else
+                    declarator = is_ruby ? :ruby : nil
+                end
+
+                if content.end_with?('\G')
+                    # emulate mysql's \G output
+                    content.slice!(-2,2)
+                    displayer = :display_by_line
+                elsif separator == ?|
+                    displayer = :pipe
+                else
+                    displayer = @default_displayer
+                end
+
+                unless content.empty?
+                    @cmds << Command.new(content, bangs, declarator, displayer)
+                    return true
+                end
+
+                return false
+            end
+
+            def run_command(cmd, last_results, eval_context)
+                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
+                        cmds = Commands.new(value, cmd.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
+                        return
+                    end
+                else
+                    value = cmd.content
+                end
+
+                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})--" <<
+                            "consider raising this via set_max_rows"
+                    rescue Mysql::Error => 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
+            end
+
+    end # class Commands
+
+end # module RSQL