dbagile 0.0.1

data/lib/dbagile/environment/interactions.rb

@@ -0,0 +1,208 @@
+module DbAgile
+  class Environment
+    # 
+    # Environment's interactions contract.
+    #
+    module Interactions
+      
+      # The buffer to use for displaying messages
+      attr_reader :message_buffer
+    
+      # The buffer to use for asking questions
+      attr_reader :asking_buffer
+      
+      ##############################################################################
+      ### Robustness
+      ##############################################################################
+      
+      #
+      # Asserts that the interactive mode is enabled. Raises a 
+      # InteractiveModeRequiredError otherwise.
+      #
+      def interactive!(msg = nil)
+        unless interactive?
+          msg = "The interactive mode is required, but disabled."
+          raise InteractiveModeRequiredError, msg
+        end
+      end
+      
+      ##############################################################################
+      ### Configuration
+      ##############################################################################
+      
+      # 
+      # Returns true if the environment is interactive, false
+      # otherwise
+      #
+      def interactive?
+        @interactive
+      end
+      
+      #
+      # Sets the interactive mode.
+      #
+      # In all cases, the highline instance for interaction is reset
+      # to nil.
+      #
+      def interactive=(value)
+        @interactive = value
+        @interaction_highline = nil
+      end
+      
+      #
+      # Sets the message/output buffer to use for interactions.
+      #
+      # In all cases, the highline instance for interaction is reset
+      # to nil.
+      #
+      def message_buffer=(buffer)
+        @message_buffer = buffer
+        @interaction_highline = nil
+      end
+      
+      #
+      # Sets the asking/input buffer to use for interactions.
+      #
+      # In all cases, the highline instance for interaction is reset
+      # to nil.
+      #
+      def asking_buffer=(buffer)
+        @asking_buffer = buffer
+        @interaction_highline = nil
+      end
+    
+      ##############################################################################
+      ### HighLine delegation
+      ##############################################################################
+      
+      #
+      # Returns an instance of HighLine for interactions, creating it 
+      # if required. 
+      #
+      # This method factors an HighLine instance even if interactive
+      # is set to false. Checking the interactive? flag should be made
+      # upstream.
+      #
+      def interaction_highline
+        if @interaction_highline.nil?
+          in_buffer  = asking_buffer  || input_buffer
+          out_buffer = message_buffer || output_buffer
+          @interaction_highline = HighLine.new(in_buffer, out_buffer)
+        end
+        @interaction_highline
+      end
+      
+      #
+      # Asks something to the user/oracle and returns the result.
+      #
+      # This method is provided when something needs to be asked to the user.
+      # It simply returns non_interactive_value if the interaction flag is set 
+      # to false. Otherwise, it delegates the call to the interaction highline 
+      # instance.
+      #
+      # @param [String] question a prompt for the question
+      # @param [Proc] continuation a optional continuation procedure
+      # @param [...] non_interactive_value value to return in non-interactive
+      #              mode
+      # @return [...] non_interactive_value in non-interactive mode, the result
+      #               of continuation proc otherwise. 
+      #
+      def ask(question, answer_type = String, non_interactive_value = nil, &continuation)
+        if interactive?
+          interaction_highline.ask(question, answer_type, &continuation)
+        else
+          nil
+        end
+      end
+      
+      #
+      # Same specification as ask, but immediately raises an 
+      # InteractiveModeRequiredError if the interactive mode is not set!
+      #
+      def ask!(question, answer_type = String, &continuation)
+        interactive!
+        ask(question, answer_type, nil, &continuation)
+      end
+    
+      # 
+      # Prints an information message on the appropriate buffer. An optional 
+      # color may be provided if the environment supports colors.
+      #
+      # Does nothing when interactive mode is disabled. Delegates the call
+      # to highline otherwise.
+      #
+      # The something argument is expected to be a String. Use display to
+      # show complex objects, Enumerable in particular
+      #
+      # @param [String] something a message to print
+      # @param [Symbol] an optional color
+      # @return [void]
+      #
+      def say(something, color = nil)
+        if interactive?
+          h = interaction_highline
+          color.nil? ? h.say(something) : h.say(h.color(something, color))
+        end
+      end
+    
+      # 
+      # Displays something on the message buffer.
+      #
+      # Does nothing when interactive mode is disabled. Delegates the call
+      # to highline otherwise.
+      #
+      # @param [Object] something to write on environment output
+      # @return [void]
+      #
+      def display(something, color = nil)
+        if interactive?
+          if something.kind_of?(String)
+            say(something, color)
+          elsif something.kind_of?(Enumerable)
+            something.each{|v| display(v, color)}
+          else
+            display(something.to_s, color)
+          end
+        end
+      end
+    
+      ##############################################################################
+      ### Console
+      ##############################################################################
+      
+      #
+      # When interaction mode is set, colorizes a string with highline. 
+      # Simply returns str otherwise.
+      #
+      def color(str, color)
+        interactive? ? interaction_highline.color(str, color) : str
+      end
+      
+      #
+      # Forces the console width. 
+      #
+      # When a width is set, it will always be returned by console_width, bypassing
+      # any attempt to use highline to infer it.
+      #
+      def console_width=(width)
+        @console_width = width
+      end
+      
+      #
+      # Returns width of the console. Width set with console_width= is returned in
+      # priority. Otherwise, return highline's output_cols in interactive mode.
+      # Returns 80 in all other cases.
+      #
+      def console_width
+        @console_width ||= infer_console_width
+      end
+      
+      # Tries to infer the console width
+      def infer_console_width
+        interactive? ? interaction_highline.output_cols-3 : 80
+      end
+
+      private :infer_console_width
+    end # module Interactions
+  end # class Environment
+end # module DbAgile

data/lib/dbagile/environment/on_error.rb

@@ -0,0 +1,47 @@
+module DbAgile
+  class Environment
+    module OnError
+      
+      # Show backtrace on errors?
+      attr_writer :show_backtrace
+      
+      # Shows the backtrace when an error occurs?
+      def show_backtrace?
+        @show_backtrace
+      end
+      
+      #
+      # Handles an error that occured during command execution.
+      #
+      # @param [Exception] error the error that was raised
+      # @return nil to continue execution, an error to raise otherwise
+      #
+      def on_error(command, error)
+        case error
+          when SystemExit
+          when OptionParser::ParseError
+            say(error.message, :red)
+            display(command.options.to_s)
+          when Sequel::Error, IOError
+            say(error.message, :red)
+          when DbAgile::SchemaSemanticsError
+            say(error.message(true), :red)
+          when DbAgile::InternalError
+            say("DbAgile encountered an internal error.\n Please replay with dba --backtrace and report the error!", :red)
+            say(error.message, :red)
+          when DbAgile::Error
+            say(error.message, :red)
+          when Interrupt
+            say("Command interrupted by user", :magenta)
+          else
+            say("ERROR (#{error.class}): #{error.message}", :red)
+        end
+        if show_backtrace?
+          say(error.backtrace.join("\n"))
+        end
+        error
+      end
+
+    end # module OnError
+  end # class Environment
+end # module DbAgile

data/lib/dbagile/environment/repository.rb

@@ -0,0 +1,161 @@
+module DbAgile
+  class Environment
+    module Repository
+      
+      #
+      # Checks if the repository exists or should be created.
+      #
+      # If the repository is currently loaded, this method returns true.
+      # Otherwise it returns true if the repository path exists. Note that
+      # repository consistency itself (index file) is not checked. You have
+      # to load it and catch exception to have a finer grained info.
+      #
+      def repository_exists?
+        return true if @repository
+        File.exists?(repository_path)
+      end
+      
+      #
+      # Returns a friendly path for the repository, to display to the user.
+      # If a repository is loaded, the call is delegated. Otherwise, the 
+      # repository_path is displayed, without attempting to load repository.
+      # 
+      def friendly_repository_path
+        if @repository
+          @repository.friendly_path
+        else
+          DbAgile::FileSystemTools::friendly_path!(repository_path)
+        end
+      end
+      
+      #
+      # Returns path to the repository
+      #
+      def repository_path
+        @repository_path
+      end
+      
+      #
+      # Sets the path to the .dbagile file
+      #
+      def repository_path=(path)
+        @repository = nil
+        @repository_path = path
+      end
+      
+      # 
+      # Ensures that repository is loaded and returns the Repository instance.
+      #
+      # ATTENTION: the Repository instance is kept in cache. It will not be 
+      # synchronized with modifications of the underlying files made by another 
+      # process/thread.
+      #
+      # @raise IOError if the repository does not exists or something goes wrong
+      #        with repository dir/files
+      # @raise CorruptedRepositoryError if something goes wrong when parsing the 
+      #        repository index file
+      # @return [Repository] repository instance
+      # @see DbAgile::Core::Repository::load
+      #
+      def repository
+        @repository ||= DbAgile::Core::Repository::load(repository_path)
+      end
+      
+      #
+      # Yields the block with each database in turn
+      #
+      # As this method is a wrapper on repository, it shares the specification
+      # about exceptions.
+      #
+      # @raise ArgumentError if no block is provided
+      #
+      def each_database(&block)
+        raise ArgumentError, "Missing block" unless block_given?
+        repository.each(&block)
+      end
+      
+      # 
+      # Yields the block with the Repository instance (loaded using repository)
+      #
+      # As this method is a wrapper on repository, it shares the specification
+      # about exceptions.
+      #
+      # @return [...] result of the block execution
+      # @raise ArgumentError if no block is provided
+      #
+      def with_repository
+        raise ArgumentError, "Missing block" unless block_given?
+        yield(repository)
+      end
+      
+      #
+      # Yields the block with a Database instance found by name in the 
+      # repository 
+      #
+      # As this method relies on repository, it shares its exception contract.
+      #
+      # @raise ArgumentError if no block is provided
+      # @raise NoSuchDatabaseError if the database cannot be found.
+      # @return block execution result
+      #
+      def with_database(name)
+        raise ArgumentError, "Missing block" unless block_given?
+        db = repository.database(name)
+        raise NoSuchDatabaseError if db.nil?
+        yield(db)
+      end
+      
+      # 
+      # Yields the block with the Database instance for the current one 
+      # in repository.
+      # 
+      # As this method relies on repository, it shares its exception contract.
+      #
+      # @raise ArgumentError if no block is provided
+      # @raise NoDefaultDatabaseError if the database cannot be found.
+      # @return block execution result
+      #
+      def with_current_database
+        raise ArgumentError, "Missing block" unless block_given?
+        db = repository.current_database
+        raise NoDefaultDatabaseError if db.nil?
+        yield(db)
+      end
+      
+      #
+      # Yields the block with a connection on a given database; diconnect after that.
+      #
+      # As this method relies on repository, it shares its exception contract.
+      #
+      # @raise ArgumentError if no block is provided
+      # @raise NoSuchDatabaseError if the database cannot be found.
+      # @return block execution result
+      #
+      def with_connection(db, conn_options = {}, &block)
+        case db
+          when Symbol
+            db = repository.database(db)
+          when DbAgile::Core::Database
+          else
+            raise ArgumentError, "Invalid database name #{db}"
+        end
+        raise NoSuchDatabaseError if db.nil?
+        db.with_connection(&block)
+      end
+      
+      # 
+      # Yields the block with a connection on the current database.
+      #
+      # Same contract as with_connection, expect for parameters.
+      #
+      # @raise NoDefaultDatabaseError if the database cannot be found.
+      #
+      def with_current_connection(conn_options = {}, &block)
+        with_current_database{|db|
+          with_connection(db, conn_options, &block)
+        }
+      end
+      
+    end # module Repository
+  end # class Environment
+end # module DbAgile

data/lib/dbagile/environment/robustness.rb

@@ -0,0 +1,7 @@
+module DbAgile
+  
+  # Raised when the interactive mode is definitely required, 
+  # but set to false
+  class InteractiveModeRequiredError < DbAgile::Error; end
+  
+end # module DbAgile

data/lib/dbagile/environment/testing.rb

@@ -0,0 +1,23 @@
+module DbAgile
+  class Environment
+    module Testing 
+      
+      # Returns the output buffer as a string
+      def output_buffer_str
+        if self.output_buffer.kind_of?(StringIO)
+          output_buffer.string
+        else
+          raise DbAgile::AssumptionFailedError, "StringIO expected as output buffer"
+        end
+      end
+      
+      #
+      # Returns true if the current output buffer matches a regular expression
+      #
+      def has_flushed?(rx)
+        (self.output_buffer_str =~ rx) ? true : false
+      end
+      
+    end # module Testing
+  end # class Environment
+end # module DbAgile

data/lib/dbagile/environment.rb

@@ -0,0 +1,122 @@
+require 'dbagile/environment/robustness'
+require 'dbagile/environment/on_error'
+require 'dbagile/environment/buffering'
+require 'dbagile/environment/interactions'
+require 'dbagile/environment/repository'
+require 'dbagile/environment/delegator'
+module DbAgile
+  #
+  # Defines the contract to be an environment for dbagile.
+  #
+  class Environment
+    include DbAgile::Environment::OnError
+    include DbAgile::Environment::Buffering
+    include DbAgile::Environment::Interactions
+    include DbAgile::Environment::Repository
+    
+    #
+    # Installs the testing methods, StringIO on output buffers then 
+    # returns self
+    #
+    def with_testing_methods!(interactive = true)
+      require 'dbagile/environment/testing'
+      extend(DbAgile::Environment::Testing)
+      self.output_buffer  = StringIO.new
+      self.message_buffer = StringIO.new
+      self.interactive = interactive
+      self
+    end
+    
+    #
+    # Creates a default Environment instance with following options:
+    # 
+    # - repository_path -> what Environment::default_repository_path returns
+    # - input_buffer    -> STDIN
+    # - output_buffer   -> STDOUT
+    # - interactive?    -> true
+    # - asking_buffer   -> STDIN
+    # - message_buffer  -> STDERR
+    # - show_backtrace  -> false
+    #
+    def initialize
+      @repository_path = Environment::default_repository_path
+      @input_buffer    = STDIN
+      @output_buffer   = STDOUT
+      @interactive     = true
+      @asking_buffer   = STDIN
+      @message_buffer  = STDERR
+      @show_backtrace  = false
+    end
+    
+    #
+    # Duplicates the environment but removes any cached value (repository 
+    # and so on)
+    #
+    def dup
+      env = Environment.new
+      env.repository_path = self.repository_path
+      env.input_buffer    = self.input_buffer
+      env.output_buffer   = self.output_buffer
+      env.interactive     = self.interactive?
+      env.asking_buffer   = self.asking_buffer
+      env.message_buffer  = self.message_buffer
+      env.show_backtrace  = self.show_backtrace?
+      env
+    end
+    
+    # 
+    # Returns the default path to use for a repository.
+    #
+    # The algorithm implemented tries to locate a repository folder in the
+    # following order:
+    #
+    # - dbagile.idx file in the current directory -> it's parent folder
+    # - dbagile folder in the current directory   -> ./dbagile
+    # - .dbagile folder in user's home            -> ~/.dbagile
+    #
+    # If none of those files exists, ~/.dbagile is returned
+    #
+    def self.default_repository_path
+      if File.exists?("./dbagile.idx")
+        "."
+      elsif File.exists?("dbagile")
+        "dbagile"
+      else
+        File.join(ENV['HOME'], '.dbagile')
+      end
+    end
+    
+    #
+    # Returns the default environment to use.
+    #
+    # The algorithm implemented tries to locate a repository folder in the
+    # following order:
+    #
+    # - dbagile.idx file in the current directory -> it's parent folder
+    # - dbagile folder in the current directory   -> ./dbagile
+    # - .dbagile folder in user's home            -> ~/.dbagile
+    #
+    # If none of those files exists, a default environment will be created
+    # mapping to an unexisting repository folder in ~/.dbagile
+    #
+    # By default, the repository is not loaded at all, and errors can therefore
+    # occur later, when the repository will be first accessed. Set 
+    # load_repository to true to force immediate load.
+    #
+    def self.default(load_repository = false)
+      env = Environment.new
+      if load_repository
+        env.repository
+      end
+      env
+    end
+    
+    #
+    # Convenient method for Environment::default(true)
+    #
+    def self.default!
+      Environment::default(true)
+    end
+    
+  end # class Environment
+end # module DbAgile

data/lib/dbagile/errors.rb

@@ -0,0 +1,30 @@
+module DbAgile
+  
+  # Raised when a database name is not valid
+  class InvalidDatabaseName < DbAgile::Error; end
+  
+  # Raised when a database URI is not valid
+  class InvalidDatabaseUri < DbAgile::Error; end
+  
+  # Raised when a command does not exists (dba command line tool)
+  class NoSuchCommandError < DbAgile::Error; end
+  
+  # Raised when the repository seems corrupted
+  class CorruptedRepositoryError < DbAgile::Error; end
+  
+  # Raised when a database cannot be found
+  class NoSuchDatabaseError < DbAgile::Error; end
+
+  # Raised when a database name is already used (on add)
+  class DatabaseNameConflictError < DbAgile::Error; end
+
+  # Raised when no default database is set
+  class NoDefaultDatabaseError < DbAgile::Error; end
+  
+  # Raised when input parsing of data fails for some reason
+  class InvalidFormatError < DbAgile::Error; end
+  
+  # Raised when usage of schema files fails because they are not installed
+  class NoSchemaFilesError < DbAgile::Error; end
+  
+end # module DbAgile

data/lib/dbagile/io/csv.rb

@@ -0,0 +1,99 @@
+module DbAgile
+  module IO
+    module CSV
+      extend IO::TypeSafe
+      
+      # Normalizes CSV options from DBAgile options
+      def normalize_options(options)
+        if options[:type_system]
+          options[:headers] = true unless options.key?(:headers)
+          options[:quote_char] = "'" unless options.key?(:quote_char)
+          options[:force_quotes] = true unless options.key?(:force_quotes)
+        end
+        if options[:headers]
+          options[:write_headers] = true 
+          options[:return_headers] = true 
+        end
+        options
+      end
+      module_function :normalize_options
+
+      # Makes the CSV require, depending on Ruby version
+      def build_csv_instance(io, options)
+        if RUBY_VERSION >= "1.9.0"
+          require 'csv'
+          options = normalize_options(options)
+          csv_options = options.dup.delete_if{|key,value| !::CSV::DEFAULT_OPTIONS.key?(key)}
+          [::CSV.new(io, csv_options), options]
+        else
+          require 'faster_csv'
+          options = normalize_options(options)
+          csv_options = options.dup.delete_if{|key,value| !FasterCSV::DEFAULT_OPTIONS.key?(key)}
+          [FasterCSV.new(io, csv_options), options]
+        end
+      end
+      module_function :build_csv_instance
+
+      #
+      # Outputs some data as a CSV string.
+      #
+      # @return [...] the buffer itself
+      #
+      def to_csv(data, columns, buffer = "", options = {})
+        # Creates a CSV outputter with options
+        csv, options = build_csv_instance(buffer, options)
+        
+        # Write header if required
+        if options[:headers]
+          if ts = options[:type_system]
+            csv << columns.collect{|c| ts.to_literal(c)}
+          else
+            csv << columns
+          end
+        end
+        
+        # Write tuples now
+        with_type_safe_relation(data, options) do |tuple|
+          csv << columns.collect{|c| tuple[c]}
+        end
+        
+        # Return buffer
+        buffer
+      end
+      module_function :to_csv
+      
+      # 
+      # If a block is given yields it with each tuple that can be loaded from
+      # the CSV input and returns nil. Otherwise, reads the CSV input and returns
+      # an array of tuples. 
+      #
+      def from_csv(input, options = {})
+        # Creates a CSV inputer with options
+        csv, options = build_csv_instance(input, options)
+        if ts = options[:type_system]
+          converter = lambda{|field| ts.parse_literal(field)}
+          csv.header_convert(&converter)
+          csv.convert(&converter)
+        end
+        
+        # Load data now
+        ts = options[:type_system]
+        if block_given?
+          csv.each do |row|
+            next if row.header_row?
+            yield(row.to_hash)
+          end
+        else
+          tuples = []
+          csv.each do |row|
+            next if row.header_row?
+            tuples << row.to_hash
+          end
+          tuples
+        end
+      end
+      module_function :from_csv
+      
+    end # module CSVTools
+  end # module IO
+end # module DbAgile