swift 0.7.1 → 0.7.2

data/Rakefile

@@ -30,12 +30,8 @@ end
 task :test    => :check_dependencies
 task :default => :test
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "swift #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+require 'yard'
+YARD::Rake::YardocTask.new do |yard|
+  yard.files   = ['lib/**/*.rb']
 end
+

data/VERSION

@@ -1 +1 @@
-0.7.1
+0.7.2

data/ext/swift.h

@@ -21,6 +21,9 @@ extern VALUE eSwiftConnectionError;
   } \
   catch (dbi::Error &error) { \
     rb_raise(eSwiftRuntimeError, "%s", error.what()); \
+  } \
+  catch (std::bad_alloc &error) { \
+    rb_raise(rb_eNoMemError, "%s", error.what()); \
   }
 
 #include "adapter.h"

data/lib/swift.rb

@@ -7,8 +7,69 @@ require_relative 'swift/header'
 require_relative 'swift/scheme'
 require_relative 'swift/type'
 
+# A rational rudimentary object relational mapper.
+#
+# == Synopsis
+#   require 'swift'
+#   require 'swift/migrations'
+#
+#   Swift.trace true # Debugging.
+#   Swift.setup :default, Swift::DB::Postgres, db: 'swift'
+#
+#   class User < Swift::Scheme
+#     store     :users
+#     attribute :id,    Swift::Type::Integer, serial: true, key: true
+#     attribute :name,  Swift::Type::String
+#     attribute :email, Swift::Type::String
+#   end # User
+#
+#   # Migrate it.
+#   User.migrate!
+#
+#   # Create
+#   User.create name: 'Apple Arthurton', email: 'apple@arthurton.local' # => User
+#
+#   # Get by key.
+#   user = User.get id: 1
+#
+#   # Alter attribute and update in one.
+#   user.update name: 'Jimmy Arthurton'
+#
+#   # Alter attributes and update.
+#   user.name = 'Apple Arthurton'
+#   user.update
+#
+#   # Destroy
+#   user.destroy
+#
+# == See
+# * README.rdoc has more usage examples.
+# * API.rdoc is a public API overview.
 module Swift
   class << self
+
+    # Setup a new DB connection.
+    #
+    # You almost certainly want to setup a <tt>:default</tt> named adapter. The <tt>:default</tt> scope will be used
+    # for unscoped calls to <tt>Swift.db</tt>.
+    #
+    # @example
+    #   Swift.setup :default, Swift::DB::Postgres, db: 'db1'
+    #   Swift.setup :other,   Swift::DB::Postgres, db: 'db2'
+    #
+    # @param  [Symbol]         name    Adapter name.
+    # @param  [Swift::Adapter] type    Concrete adapter subclass. See Swift::DB
+    # @param  [Hash]           options Connection options
+    # @option options [String]  :db       Name.
+    # @option options [String]  :user     (*nix login user)
+    # @option options [String]  :password ('')
+    # @option options [String]  :host     ('localhost')
+    # @option options [Integer] :port     (DB default)
+    # @option options [String]  :timezone (*nix TZ format) See http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+    # @return [Swift::Adapter]
+    #
+    # @see Swift::DB
+    # @see Swift::Adapter
     def setup name, type, options = {}
       unless type.kind_of?(Class) && type < Swift::Adapter
         raise TypeError, "Expected +type+ Swift::Adapter subclass but got #{type.inspect}"
@@ -16,8 +77,25 @@ module Swift
       (@repositories ||= {})[name] = type.new(options)
     end
 
+    # Fetch or scope a block to a specific DB by name.
+    #
+    # @example
+    #   Swift.db :other do |other|
+    #     # Inside this block all these are the same:
+    #     # other
+    #     # Swift.db
+    #     # Swift.db :other
+    #
+    #     other_users = User.prepare('select * from users where age > ?')
+    #     other_users.execute(32)
+    #   end
+    #
+    # @param  [Symbol] name   Adapter name.
+    # @param  [Proc]   &block Scope this block to the named adapter instead of <tt>:default</tt>.
+    # @return [Swift::Adapter]
+    #--
+    # I pilfered the logic from DM but I don't really understand what is/isn't thread safe.
     def db name = nil, &block
-      # I pilfered the logic from DM but I don't really understand what is/isn't thread safe.
       scopes     = (Thread.current[:swift_db] ||= [])
       repository = if name || scopes.empty?
         @repositories[name || :default] or raise "Unknown db '#{name || :default}', did you forget to #setup?"
@@ -36,6 +114,11 @@ module Swift
       repository
     end
 
+    # List of known Swift::Schema classes.
+    #
+    # Handy if you are brewing stuff like migrations and need a list of defined schema subclasses.
+    #
+    # @return [Array<Swift::Schema>]
     def schema
       @schema ||= []
     end

data/lib/swift/adapter.rb

@@ -1,22 +1,96 @@
 module Swift
+
+  # Adapter.
+  #
+  # @abstract
+  # @see      Swift::DB See Swift::DB for concrete adapters.
+  # @todo     For the time being all adapters are SQL and DBIC++ centric. It would be super easy to abstract though I
+  #           don't know if you would be better off doing it at the Ruby or DBIC++ level (or both).
+  #--
+  # TODO: Extension methods are undocumented.
   class Adapter
     attr_reader :options
 
+    # Select by id(s).
+    #
+    # @example Single key.
+    #   Swift.db.get(User, id: 12)
+    # @example Complex primary key.
+    #   Swift.db.get(UserAddress, user_id: 12, address_id: 15)
+    #
+    # @param  [Swift::Scheme] scheme Concrete scheme subclass to load.
+    # @param  [Hash]          keys   Hash of id(s) <tt>{id_name: value}</tt>.
+    # @return [Swift::Scheme, nil]
+    # @see    Swift::Scheme.get
+    #--
+    # NOTE: Not significantly shorter than Scheme.db.first(User, 'id = ?', 12)
     def get scheme, keys
       relation = scheme.new(keys)
       prepare_get(scheme).execute(*relation.tuple.values_at(*scheme.header.keys)).first
     end
 
+    # Select one or more.
+    #
+    # @example All.
+    #   Swif.db.all(User)
+    # @example All with conditions and binds.
+    #   Swift.db.all(User, ':name = ? and :age > ?', 'Apple Arthurton', 32)
+    # @example Block form iterator.
+    #   Swift.db.all(User, ':age > ?', 32) do |user|
+    #     puts user.name
+    #   end
+    #
+    # @param  [Swift::Scheme] scheme     Concrete scheme subclass to load.
+    # @param  [String]        conditions Optional SQL 'where' fragment.
+    # @param  [Object, ...]   *binds     Optional bind values that accompany conditions SQL fragment.
+    # @param  [Proc]          &block     Optional 'each' iterator block.
+    # @return [Swift::Result]
+    # @see    Swift::Scheme.all
     def all scheme, conditions = '', *binds, &block
       where = "where #{exchange_names(scheme, conditions)}" unless conditions.empty?
       prepare(scheme, "select * from #{scheme.store} #{where}").execute(*binds, &block)
     end
 
+    # Select one.
+    #
+    # @example First.
+    #   Swif.db.first(User)
+    # @example First with conditions and binds.
+    #   Swift.db.first(User, ':name = ? and :age > ?', 'Apple Arthurton', 32)
+    # @example Block form iterator.
+    #   Swift.db.first(User, ':age > ?', 32) do |user|
+    #     puts user.name
+    #   end
+    #
+    # @param  [Swift::Scheme] scheme     Concrete scheme subclass to load.
+    # @param  [String]        conditions Optional SQL 'where' fragment.
+    # @param  [Object, ...]   *binds     Optional bind values that accompany conditions SQL fragment.
+    # @param  [Proc]          &block     Optional 'each' iterator block.
+    # @return [Swift::Scheme, nil]
+    # @see    Swift::Scheme.first
     def first scheme, conditions = '', *binds, &block
       where = "where #{exchange_names(scheme, conditions)}" unless conditions.empty?
       prepare(scheme, "select * from #{scheme.store} #{where} limit 1").execute(*binds, &block).first
     end
 
+    # Create one or more.
+    #
+    # @example Scheme.
+    #   user = User.new(name: 'Apply Arthurton', age: 32)
+    #   Swift.db.create(User, user)
+    # @example Coerce hash to scheme.
+    #   Swif.db.create(User, name: 'Apple Arthurton', age: 32)
+    # @example Multiple relations.
+    #   apple = User.new(name: 'Apple Arthurton', age: 32)
+    #   benny = User.new(name: 'Benny Arthurton', age: 30)
+    #   Swift.db.first(User, apple, benny)
+    # @example Coerce multiple relations.
+    #   Swift.db.first(User, {name: 'Apple Arthurton', age: 32}, {name: 'Benny Arthurton', age: 30})
+    #
+    # @param  [Swift::Scheme]       scheme     Concrete scheme subclass to load.
+    # @param  [Swift::Scheme, Hash> *relations Scheme or tuple hash. Hashes will be coerced into scheme via Swift::Scheme#new
+    # @return [Array<Swift::Scheme>]
+    # @see    Swift::Scheme.create
     def create scheme, *relations
       statement = prepare_create(scheme)
       relations.map do |relation|
@@ -28,6 +102,29 @@ module Swift
       end
     end
 
+    # Update one or more.
+    #
+    # @example Scheme.
+    #   user      = Swift.db.create(User, name: 'Apply Arthurton', age: 32)
+    #   user.name = 'Arthur Appleton'
+    #   Swift.db.update(User, user)
+    # @example Coerce hash to scheme.
+    #   user      = Swift.db.create(User, name: 'Apply Arthurton', age: 32)
+    #   user.name = 'Arthur Appleton'
+    #   Swif.db.update(User, user.tuple)
+    # @example Multiple relations.
+    #   apple = Swift.db.create(User, name: 'Apple Arthurton', age: 32)
+    #   benny = Swift.db.create(User, name: 'Benny Arthurton', age: 30)
+    #   Swift.db.update(User, apple, benny)
+    # @example Coerce multiple relations.
+    #   apple = Swift.db.create(User, name: 'Apple Arthurton', age: 32)
+    #   benny = Swift.db.create(User, name: 'Benny Arthurton', age: 30)
+    #   Swift.db.update(User, apple.tuple, benny.tuple)
+    #
+    # @param  [Swift::Scheme]       scheme     Concrete scheme subclass to load.
+    # @param  [Swift::Scheme, Hash> *relations Scheme or tuple hash. Hashes will be coerced into scheme via Swift::Scheme#new
+    # @return [Array<Swift::Scheme>]
+    # @see    Swift::Scheme#update
     def update scheme, *relations
       statement = prepare_update(scheme)
       relations.map do |relation|
@@ -37,6 +134,28 @@ module Swift
       end
     end
 
+    # Destroy one or more.
+    #
+    # @example Scheme.
+    #   user      = Swift.db.create(User, name: 'Apply Arthurton', age: 32)
+    #   user.name = 'Arthur Appleton'
+    #   Swift.db.destroy(User, user)
+    # @example Coerce hash to scheme.
+    #   user      = Swift.db.create(User, name: 'Apply Arthurton', age: 32)
+    #   user.name = 'Arthur Appleton'
+    #   Swif.db.destroy(User, user.tuple)
+    # @example Multiple relations.
+    #   apple = Swift.db.create(User, name: 'Apple Arthurton', age: 32)
+    #   benny = Swift.db.create(User, name: 'Benny Arthurton', age: 30)
+    #   Swift.db.destroy(User, apple, benny)
+    # @example Coerce multiple relations.
+    #   apple = Swift.db.create(User, name: 'Apple Arthurton', age: 32)
+    #   benny = Swift.db.create(User, name: 'Benny Arthurton', age: 30)
+    #   Swift.db.destroy(User, apple.tuple, benny.tuple)
+    #
+    # @param  [Swift::Scheme]       scheme     Concrete scheme subclass to load.
+    # @param  [Swift::Scheme, Hash] *relations Scheme or tuple hash. Hashes will be coerced into scheme via Swift::Scheme#new
+    # @see    Swift::Scheme#destroy
     def destroy scheme, *relations
       statement = prepare_destroy(scheme)
       relations.map do |relation|
@@ -53,14 +172,10 @@ module Swift
       fields =  scheme.header.map{|p| field_definition(p)}.join(', ')
       fields += ", primary key (#{keys.join(', ')})" unless keys.empty?
 
-      drop_store scheme.store
+      execute("drop table if exists #{scheme.store}")
       execute("create table #{scheme.store} (#{fields})")
     end
 
-    def drop_store name
-      execute("drop table if exists #{name}")
-    end
-
     protected
       def exchange_names scheme, query
         query.gsub(/:(\w+)/){ scheme.send($1.to_sym).field }

data/lib/swift/attribute.rb

@@ -1,9 +1,25 @@
 module Swift
+
+  # An attribute (column) definition.
   #--
   # NOTE: Default method is defined in the extension.
   class Attribute
     attr_reader :name, :field, :key, :serial
 
+    # @example
+    #   user = Class.new(Swift::Scheme)
+    #   Swift::Attribute.new(user, :name, Swift::Type::String)
+    #
+    # @param [Swift::Scheme] scheme
+    # @param [Symbol]        name
+    # @param [Hash]          options
+    # @option options [Object, Proc]          :default
+    # @option options [Symbol]                :field
+    # @option options [TrueClass, FalseClass] :key
+    # @option options [TrueClass, FalseClass] :serial
+    #
+    # @see Swift::Scheme
+    # @see Swift::Type
     def initialize scheme, name, options = {}
       @name    = name
       @default = options.fetch(:default, nil)
@@ -13,6 +29,7 @@ module Swift
       define_scheme_methods(scheme)
     end
 
+    # Evals attribute accessors for this attribute into the scheme.
     def define_scheme_methods scheme
       scheme.class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{name};        tuple.fetch(:#{field}, nil)   end

data/lib/swift/db.rb

@@ -36,14 +36,18 @@ module Swift
         false
       end
 
-      def drop_store name
-        exists_sql =<<-SQL
-          select count(*) as exists from syscat.tables where tabschema = CURRENT_SCHEMA and tabname = '#{name.upcase}'
+      def migrate!
+        keys   =  scheme.header.keys
+        fields =  scheme.header.map{|p| field_definition(p)}.join(', ')
+        fields += ", primary key (#{keys.join(', ')})" unless keys.empty?
+
+        sql = <<-SQL
+          select count(*) as exists from syscat.tables
+          where tabschema = CURRENT_SCEMA and tabname = '#{scheme.store.upcase}'
         SQL
 
-        execute(exists_sql.strip) do |r|
-          execute("drop table #{name}") if r[:exists] > 0
-        end
+        execute(sql) {|result| execute("drop table #{scheme.store}") if result[:exists] > 0 }
+        execute("create table #{scheme.store} (#{fields})")
       end
 
       def field_type attribute

data/lib/swift/scheme.rb

@@ -1,23 +1,62 @@
 module Swift
+
+  # A relation (instance) definition.
+  #
+  # @example A user scheme.
+  #   class User < Swift::Scheme
+  #     store     :users
+  #     attribute :id,         Swift::Type::Integer, serial: true, key: true
+  #     attribute :name,       Swift::Type::String
+  #     attribute :email,      Swift::Type::String
+  #     attribute :updated_at, Swift::Type::Time
+  #   end # User
+  #
+  # @todo Tuple should be renamed tuples (plural?)
   class Scheme
     attr_accessor :tuple
     alias_method :scheme, :class
 
+    # @example
+    #   User.new(
+    #     name:       'Apple Arthurton',
+    #     email:      'apple@arthurton.local',
+    #     updated_at: Time.now
+    #   )
+    # @param [Hash] options Create relation and set attributes. <tt>{name: value}</tt>
     def initialize options = {}
       @tuple = scheme.header.new_tuple
       options.each{|k, v| send(:"#{k}=", v)}
     end
 
+    # @example
+    #   apple = User.create(
+    #     name:       'Apple Arthurton',
+    #     email:      'apple@arthurton.local',
+    #     updated_at: Time.now
+    #   )
+    #   apple.update(name: 'Arthur Appleton')
+    #
+    # @param [Hash] options Update attributes. <tt>{name: value}</tt>
     def update options = {}
       options.each{|k, v| send(:"#{k}=", v)}
       Swift.db.update(scheme, self)
     end
 
+    # @example
+    #   apple = User.create(
+    #     name:       'Apple Arthurton',
+    #     email:      'apple@arthurton.local',
+    #     updated_at: Time.now
+    #   )
+    #   apple.destroy
     def destroy
       Swift.db.destroy(scheme, self)
     end
 
     class << self
+      # Attribute set.
+      #
+      # @return [Swift::Header]
       attr_accessor :header
 
       def inherited klass
@@ -32,27 +71,83 @@ module Swift
         scheme
       end
 
+      # Define a new attribute for this scheme.
+      #
+      # @see Swift::Attribute#new
       def attribute name, type, options = {}
         header.push(attribute = type.new(self, name, options))
         (class << self; self end).send(:define_method, name, lambda{ attribute })
       end
 
+      # Define the store (table).
+      #
+      # @param  [Symbol] name Storage name.
+      # @return [Symbol]
       def store name = nil
         name ? @store = name : @store
       end
 
+      # Create (insert).
+      #
+      # @example
+      #   apple = User.create(
+      #     name:       'Apple Arthurton',
+      #     email:      'apple@arthurton.local',
+      #     updated_at: Time.now
+      #   )
+      #
+      # @param [Hash] options Create with attributes. <tt>{name: value}</tt>
       def create options = {}
         Swift.db.create(self, options)
       end
 
+      # Select by id(s).
+      #
+      # @example Single key.
+      #   User.get(id: 12)
+      # @example Complex primary key.
+      #   UserAddress.get(user_id: 12, address_id: 15)
+      #
+      # @param  [Hash] keys Hash of id(s) <tt>{id_name: value}</tt>.
+      # @return [Swift::Scheme, nil]
       def get keys
         Swift.db.get(self, keys)
       end
 
+      # Select one or more.
+      #
+      # @example All.
+      #   User.all
+      # @example All with conditions and binds.
+      #   User.all(':name = ? and :age > ?', 'Apple Arthurton', 32)
+      # @example Block form iterator.
+      #   User.all(':age > ?', 32) do |user|
+      #     puts user.name
+      #   end
+      #
+      # @param  [String]        conditions Optional SQL 'where' fragment.
+      # @param  [Object, ...]   *binds     Optional bind values that accompany conditions SQL fragment.
+      # @param  [Proc]          &block     Optional 'each' iterator block.
+      # @return [Swift::Result]
       def all conditions = '', *binds, &block
         Swift.db.all(self, conditions, *binds, &block)
       end
 
+      # Select one.
+      #
+      # @example First.
+      #   User.first
+      # @example First with conditions and binds.
+      #   User.first(':name = ? and :age > ?', 'Apple Arthurton', 32)
+      # @example Block form iterator.
+      #   User.first(User, 'age > ?', 32) do |user|
+      #     puts user.name
+      #   end
+      #
+      # @param  [String]        conditions Optional SQL 'where' fragment.
+      # @param  [Object, ...]   *binds     Optional bind values that accompany conditions SQL fragment.
+      # @param  [Proc]          &block     Optional 'each' iterator block.
+      # @return [Swift::Scheme, nil]
       def first conditions = '', *binds, &block
         Swift.db.first(self, conditions, *binds, &block)
       end

data/swift.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{swift}
-  s.version = "0.7.1"
+  s.version = "0.7.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Shane Hanna", "Bharanee 'Barney' Rathna"]
-  s.date = %q{2010-09-24}
+  s.date = %q{2010-10-02}
   s.description = %q{A rational rudimentary database abstraction.}
   s.email = ["shane.hanna@gmail.com", "deepfryed@gmail.com"]
   s.extensions = ["ext/extconf.rb"]
@@ -74,20 +74,20 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.6}
   s.summary = %q{A rational rudimentary database abstraction.}
   s.test_files = [
-    "test/test_pool.rb",
-     "test/test_io.rb",
-     "test/test_validations.rb",
-     "test/test_transactions.rb",
-     "test/test_adapter.rb",
-     "test/test_identity_map.rb",
+    "test/test_adapter.rb",
+     "test/test_scheme.rb",
+     "test/test_types.rb",
      "test/test_error.rb",
-     "test/helper.rb",
+     "test/test_io.rb",
      "test/test_encoding.rb",
+     "test/test_transactions.rb",
+     "test/test_validations.rb",
      "test/test_timestamps.rb",
-     "test/test_scheme.rb",
-     "test/test_types.rb",
-     "examples/scheme.rb",
+     "test/helper.rb",
+     "test/test_identity_map.rb",
+     "test/test_pool.rb",
      "examples/async.rb",
+     "examples/scheme.rb",
      "examples/db.rb"
   ]
 

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 7
-  - 1
-  version: 0.7.1
+  - 2
+  version: 0.7.2
 platform: ruby
 authors: 
 - Shane Hanna
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-24 00:00:00 +10:00
+date: 2010-10-02 00:00:00 +10:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -136,18 +136,18 @@ signing_key:
 specification_version: 3
 summary: A rational rudimentary database abstraction.
 test_files: 
-- test/test_pool.rb
-- test/test_io.rb
-- test/test_validations.rb
-- test/test_transactions.rb
 - test/test_adapter.rb
-- test/test_identity_map.rb
+- test/test_scheme.rb
+- test/test_types.rb
 - test/test_error.rb
-- test/helper.rb
+- test/test_io.rb
 - test/test_encoding.rb
+- test/test_transactions.rb
+- test/test_validations.rb
 - test/test_timestamps.rb
-- test/test_scheme.rb
-- test/test_types.rb
-- examples/scheme.rb
+- test/helper.rb
+- test/test_identity_map.rb
+- test/test_pool.rb
 - examples/async.rb
+- examples/scheme.rb
 - examples/db.rb