sqlite-ruby 2.1.0-mswin32

data/lib/sqlite/parsed_statement.rb

@@ -0,0 +1,233 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+# 
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+# 
+#     * The names of its contributors may not be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# =============================================================================
+#++
+
+require 'strscan'
+
+module SQLite
+
+  # A ParsedStatement instance represents a tokenized version of an SQL
+  # statement. This makes it possible to do bind variable replacements multiple
+  # times, fairly efficiently.
+  #
+  # Within the SQLite interfaces, this is used only by the Statement class.
+  # However, it could be reused by other SQL-reliant classes easily.
+  class ParsedStatement
+
+    # This represents a textual token in an SQL statement. It is only used by
+    # ParsedStatement.
+    class Token # :nodoc:
+
+      # Create a new Token that encapsulates the given text.
+      def initialize( text )
+        @text = text
+      end
+
+      # Append the given text onto the the contents of this Token.
+      def <<( text )
+        @text << text.to_s
+      end
+
+      # Convert this Token into a string. The +vars+ parameter is ignored.
+      def to_s( vars=nil )
+        @text
+      end
+
+    end
+
+    # This represents a bind variable in a tokenized SQL stream. It is used
+    # only by ParsedStatement.
+    class BindVariable # :nodoc:
+
+      # Create a new BindVariable token encapsulating the given name. The
+      # name is used when looking up a bind variable to bind to the place
+      # holder represented by this token. The name may be either a Fixnum
+      # (in which case it represents an positional placeholder) or a
+      # a String (in which case it represents a named placeholder).
+      def initialize( name )
+        @name = name
+      end
+
+      # Convert the token to a string. If the +vars+ parameter is +nil+, then
+      # the string will be in the format <tt>?nnn</tt> (where _nnn_ is the
+      # index that was used to initialize this token). Otherwise, the +vars+
+      # parameter must be a hash, and the value bound to this token is the
+      # element with the key given to this token when it was created. If that
+      # element is +nil+, this will return the string "NULL". If the element
+      # is a String, then it will be quoted and escaped and returned.
+      # Otherwise, the "to_s" method of the element will be called and the
+      # result returned.
+      def to_s( vars=nil )
+        if vars.nil?
+          ":#{@name}"
+        else
+          var = vars[ @name ]
+          case var
+            when nil
+              "NULL"
+            when String
+              "'#{var.gsub(/'/,"''")}'"
+            else
+              var.to_s
+          end
+        end
+      end
+
+    end
+
+    # The text trailing the first recognized SQL statement that was parsed from
+    # the buffer given to this object. If there was no trailing SQL statement,
+    # this property will be the empty string.
+    attr_reader :trailing
+
+    # Create a new ParsedStatement. This will tokenize the given buffer. As an
+    # optimization, the tokenization is only performed if the string matches
+    # /[?:;]/, otherwise the string is used as-is.
+    def initialize( sql )
+      @bind_values = Hash.new
+
+      if sql.index( /[?:;]/ )
+        @tokens, @trailing = tokenize( sql )
+      else
+        @tokens, @trailing = [ Token.new(sql) ], ""
+      end
+    end
+
+    # Returns an array of the placeholders known to this statement. This will
+    # either be empty (if the statement has no placeholders), or will contain
+    # numbers (indexes) and strings (names).
+    def placeholders
+      @bind_values.keys
+    end
+
+    # Returns the SQL that was given to this parsed statement when it was
+    # created, with bind placeholders intact.
+    def sql
+      @tokens.inject( "" ) { |sql,tok| sql << tok.to_s }
+    end
+
+    # Returns the statement as an SQL string, with all placeholders bound to
+    # their corresponding values.
+    def to_s
+      @tokens.inject( "" ) { |sql,tok| sql << tok.to_s( @bind_values ) }
+    end
+
+    alias :to_str :to_s
+
+    # Binds the given parameters to the placeholders in the statement. It does
+    # this by iterating over each argument and calling #bind_param with the
+    # corresponding index (starting at 1). However, if any element is a hash,
+    # the hash is iterated through and #bind_param called for each key/value
+    # pair. Hash's do not increment the index.
+    def bind_params( *bind_vars )
+      index = 1
+      bind_vars.each do |value|
+        if value.is_a?( Hash )
+          value.each_pair { |key, value| bind_param( key, value ) }
+        else
+          bind_param index, value
+          index += 1
+        end
+      end
+      self
+    end
+
+    # Binds the given value to the placeholder indicated by +param+, which may
+    # be either a Fixnum or a String. If the indicated placeholder does not
+    # exist in the statement, this method does nothing.
+    def bind_param( param, value )
+      return unless @bind_values.has_key?( param )
+      @bind_values[ param ] = value
+    end
+
+    # Tokenizes the given SQL string, returning a tuple containing the array of
+    # tokens (optimized so that each text token contains the longest run of
+    # text possible), and any trailing text that follows the statement.
+    def tokenize( sql )
+      tokens = []
+
+      scanner = StringScanner.new( sql )
+      variable_index = 0
+
+      until scanner.eos?
+        tokens << " " unless tokens.empty? if scanner.scan( /\s+/ )
+        break if scanner.eos?
+
+        if scanner.scan( /;/ )
+          break
+        elsif scanner.scan( /---.*$/ ) || scanner.scan( %r{/\*.*?\*/}m )
+          # comments
+          next
+        elsif scanner.scan( /[-+*\/\w=<>!(),.]+/ )
+          tokens << Token.new( scanner.matched )
+        elsif scanner.scan( /['"]/ )
+          delim = scanner.matched
+          token = delim.dup
+          loop do
+            token << scanner.scan_until( /#{delim}/ )
+            match = scanner.matched
+            break if match.length % 2 == 1
+          end
+          tokens << Token.new( token )
+        elsif scanner.scan( /\?(\d+)?/ )
+          variable_index = ( scanner[1] ? scanner[1].to_i : variable_index+1 )
+          tokens << BindVariable.new( variable_index )
+          @bind_values[variable_index] = nil
+        elsif scanner.scan( /:(\w+):?/ )
+          name = scanner[1]
+          variable_index = name = name.to_i if name !~ /\D/
+          tokens << BindVariable.new( name )
+          @bind_values[name] = nil
+        else
+          raise "unknown token #{scanner.rest.inspect}"
+        end
+      end
+
+      # optimize the parsed list
+      tokens.pop while tokens.last == " "
+      optimized = []
+      tokens.each do |tok|
+        last = optimized.last
+        if tok.is_a?( BindVariable ) || last.nil? || last.is_a?( BindVariable )
+          tok = Token.new(tok) if tok == " "
+          optimized << tok
+        else
+          last << tok
+        end
+      end
+
+      return optimized, scanner.rest
+    end
+    private :tokenize
+
+  end
+
+end

data/lib/sqlite/pragmas.rb

@@ -0,0 +1,236 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+# 
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+# 
+#     * The names of its contributors may not be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# =============================================================================
+#++
+
+module SQLite
+
+  # This module is intended for inclusion solely by the Database class. It
+  # defines convenience methods for the various pragmas supported by SQLite.
+  #
+  # Two pragmas that have been intentionally excluded are SHOW_DATATYPES
+  # and EMPTY_RESULT_SETS, since these apply only to queries that use the
+  # SQLite "exec" function. The SQLite API does not employ that function,
+  # preferring instead the compile/step/finalize interface.
+  #
+  # However, if you really must have those pragmas, you can always execute
+  # a pragma as if it were an SQL statement.
+  #
+  # For a detailed description of these pragmas, see the SQLite documentation
+  # at http://sqlite.org/lang.html#pragma.
+  module Pragmas
+
+    # Returns +true+ or +false+ depending on the value of the named pragma.
+    def get_boolean_pragma( name )
+      get_first_value( "PRAGMA #{name}" ) != "0"
+    end
+    private :get_boolean_pragma
+
+    # Sets the given pragma to the given boolean value. The value itself
+    # may be +true+ or +false+, or any other commonly used string or
+    # integer that represents truth.
+    def set_boolean_pragma( name, mode )
+      case mode
+        when String
+          case mode.downcase
+            when "on", "yes", "true", "y", "t": mode = "'ON'"
+            when "off", "no", "false", "n", "f": mode = "'OFF'"
+            else
+              raise Exceptions::DatabaseException,
+                "unrecognized pragma parameter #{mode.inspect}"
+          end
+        when true, 1
+          mode = "ON"
+        when false, 0, nil
+          mode = "OFF"
+        else
+          raise Exceptions::DatabaseException,
+            "unrecognized pragma parameter #{mode.inspect}"
+      end
+
+      execute( "PRAGMA #{name}=#{mode}" )
+    end
+    private :set_boolean_pragma
+
+    # Requests the given pragma (and parameters), and if the block is given,
+    # each row of the result set will be yielded to it. Otherwise, the results
+    # are returned as an array.
+    def get_query_pragma( name, *parms, &block ) # :yields: row
+      if parms.empty?
+        execute( "PRAGMA #{name}", &block )
+      else
+        args = "'" + parms.join("','") + "'"
+        execute( "PRAGMA #{name}( #{args} )", &block )
+      end
+    end
+    private :get_query_pragma
+
+    # Return the value of the given pragma.
+    def get_enum_pragma( name )
+      get_first_value( "PRAGMA #{name}" )
+    end
+    private :get_enum_pragma
+
+    # Set the value of the given pragma to +mode+. The +mode+ parameter must
+    # conform to one of the values in the given +enum+ array. Each entry in
+    # the array is another array comprised of elements in the enumeration that
+    # have duplicate values. See #synchronous, #default_synchronous,
+    # #temp_store, and #default_temp_store for usage examples.
+    def set_enum_pragma( name, mode, enums )
+      match = enums.find { |p| p.find { |i| i.to_s.downcase == mode.to_s.downcase } }
+      raise Exceptions::DatabaseException,
+        "unrecognized #{name} #{mode.inspect}" unless match
+      execute( "PRAGMA #{name}='#{match.first.upcase}'" )
+    end
+    private :set_enum_pragma
+
+    # Returns the value of the given pragma as an integer.
+    def get_int_pragma( name )
+      get_first_value( "PRAGMA #{name}" ).to_i
+    end
+    private :get_int_pragma
+
+    # Set the value of the given pragma to the integer value of the +value+
+    # parameter.
+    def set_int_pragma( name, value )
+      execute( "PRAGMA #{name}=#{value.to_i}" )
+    end
+    private :set_int_pragma
+
+    # The enumeration of valid synchronous modes.
+    SYNCHRONOUS_MODES = [ [ 'full', 2 ], [ 'normal', 1 ], [ 'off', 0 ] ]
+
+    # The enumeration of valid temp store modes.
+    TEMP_STORE_MODES  = [ [ 'default', 0 ], [ 'file', 1 ], [ 'memory', 2 ] ]
+
+    # Does an integrity check on the database. If the check fails, a
+    # SQLite::Exceptions::DatabaseException will be raised. Otherwise it
+    # returns silently.
+    def integrity_check
+      execute( "PRAGMA integrity_check" ) do |row|
+        raise Exceptions::DatabaseException, row[0] if row[0] != "ok"
+      end
+    end
+
+    def cache_size
+      get_int_pragma "cache_size"
+    end
+
+    def cache_size=( size )
+      set_int_pragma "cache_size", size
+    end
+
+    def default_cache_size
+      get_int_pragma "default_cache_size"
+    end
+
+    def default_cache_size=( size )
+      set_int_pragma "default_cache_size", size
+    end
+
+    def default_synchronous
+      get_enum_pragma "default_synchronous"
+    end
+
+    def default_synchronous=( mode )
+      set_enum_pragma "default_synchronous", mode, SYNCHRONOUS_MODES
+    end
+
+    def synchronous
+      get_enum_pragma "synchronous"
+    end
+
+    def synchronous=( mode )
+      set_enum_pragma "synchronous", mode, SYNCHRONOUS_MODES
+    end
+
+    def default_temp_store
+      get_enum_pragma "default_temp_store"
+    end
+
+    def default_temp_store=( mode )
+      set_enum_pragma "default_temp_store", mode, TEMP_STORE_MODES
+    end
+  
+    def temp_store
+      get_enum_pragma "temp_store"
+    end
+
+    def temp_store=( mode )
+      set_enum_pragma "temp_store", mode, TEMP_STORE_MODES
+    end
+
+    def full_column_names
+      get_boolean_pragma "full_column_names"
+    end
+
+    def full_column_names=( mode )
+      set_boolean_pragma "full_column_names", mode
+    end
+  
+    def parser_trace
+      get_boolean_pragma "parser_trace"
+    end
+
+    def parser_trace=( mode )
+      set_boolean_pragma "parser_trace", mode
+    end
+  
+    def vdbe_trace
+      get_boolean_pragma "vdbe_trace"
+    end
+
+    def vdbe_trace=( mode )
+      set_boolean_pragma "vdbe_trace", mode
+    end
+
+    def database_list( &block ) # :yields: row
+      get_query_pragma "database_list", &block
+    end
+
+    def foreign_key_list( table, &block ) # :yields: row
+      get_query_pragma "foreign_key_list", table, &block
+    end
+
+    def index_info( index, &block ) # :yields: row
+      get_query_pragma "index_info", index, &block
+    end
+
+    def index_list( table, &block ) # :yields: row
+      get_query_pragma "index_list", table, &block
+    end
+
+    def table_info( table, &block ) # :yields: row
+      get_query_pragma "table_info", table, &block
+    end
+  
+  end
+
+end