swift 0.10.0 → 0.11.0

data/API.rdoc

@@ -13,29 +13,23 @@ Public API minus the optional stuff like Pool, IdentityMap, Migrations etc.
     # Abstract.
     Adapter
       .new         #=> Adapter
-      #all         #=> Result
       #begin       #=> Adapter
       #commit
       #create      #=> Scheme or Result
-      #destroy     #=> Scheme or Result
+      #delete      #=> Result
       #execute     #=> Result
-      #first       #=> Scheme
       #get         #=> Scheme
       #prepare     #=> Statement
       #rollback
       #transaction #=> Adapter
       #update      #=> Scheme or Result
       #reconnect
-      #delete      #=> Result
-
-      # TODO: DBI < Adapter
-        # returning? #=> true or false
 
     # Concrete.
     DB
-      Mysql    < Adapter # TODO: Adapter::DBI?
-      Postgres < Adapter # TODO: Adapter::DBI?
-      Sqlite3  < Adapter # TODO: Adapter::DBI?
+      Mysql    < Adapter::Sql
+      Postgres < Adapter::Sql
+      Sqlite3  < Adapter::Sql
 
     # Enumerable collection of Scheme or Hash tuples.
     Result
@@ -48,21 +42,20 @@ Public API minus the optional stuff like Pool, IdentityMap, Migrations etc.
       #execute #=> Result
 
     Scheme
-      .all       #=> Result
       .attribute #=> Type
       .create    #=> Scheme or Result
-      .first     #=> Scheme
       .get       #=> Scheme
       .header    #=> Header
       .load      #=> Scheme
       .new       #=> Scheme
-      .scheme    #=> Alias for self.class
       .store     #=> Symbol
-      #destroy   #=> Scheme or Result
+      #execute   #=> Result
+      #prepare   #=> Statement
+      #scheme    #=> Alias for self.class
       #tuple     #=> Hash
       #update    #=> Scheme or Result
 
-    # Enumerable collection of Types for Scheme
+    # Enumerable collection of Types for Scheme.
     Header
       .new        #=> Header
       #all        #=> [Type, ...]
@@ -83,7 +76,7 @@ Public API minus the optional stuff like Pool, IdentityMap, Migrations etc.
       #default               #=> Object
       #define_scheme_methods
 
-    # Concrete
+    # Concrete.
     Type
       BigDecimal < Attribute
       Boolean    < Attribute

data/README.rdoc

@@ -121,12 +121,12 @@ Scheme/relation level helpers.
   user.update
 
   # Destroy
-  user.destroy
+  user.delete
 
 === Conditions SQL syntax.
 
-SQL is easy and most people know it so Swift ORM provides a simple symbol like syntax to convert resource
-names to field names.
+SQL is easy and most people know it so Swift ORM provides simple #to_s
+attribute to field name typecasting.
 
   class User < Swift::Scheme
     store     :users
@@ -138,7 +138,10 @@ names to field names.
 
   # Convert :name and :age to fields.
   # select * from users where eman like '%Arthurton' and ega > 20
-  users = User.all(':name like ? and :age > ?', '%Arthurton', 20)
+  users = User.execute(
+    %Q{select * from #{User} where #{User.name} like ? and #{User.age} > ?},
+    '%Arthurton', 20
+  )
 
 === Identity Map
 
@@ -162,8 +165,9 @@ Swift comes with a simple identity map. Just require it after you load swift.
   # Create
   User.create name: 'James Arthurton', email: 'james@arthurton.local' # => User
 
-  User.first(':name = ?', 'James Arthurton')
-  User.first(':name = ?', 'James Arthurton') # Gets same object reference
+  find_user = User.prepare(%Q{select * from #{User} where #{User.name = ?})
+  find_user.execute('James Arthurton')
+  find_user.execute('James Arthurton') # Gets same object reference
 
 === Bulk inserts
 
@@ -265,7 +269,6 @@ The adapter level SELECT benchmarks without using ORM.
 
 * More tests.
 * Assertions for dumb stuff.
-* Abstract interface for other adapters? Move dbic++ to Swift::DBI::(Adapter, Pool, Result, Statment etc.)
 
 == Contributing
 

data/Rakefile

@@ -32,6 +32,6 @@ task :default => :test
 
 require 'yard'
 YARD::Rake::YardocTask.new do |yard|
-  yard.files   = ['lib/**/*.rb']
+  yard.files   = ['lib/**/*.rb', 'ext/*.cc']
 end
 

data/VERSION

@@ -1 +1 @@
-0.10.0
+0.11.0

data/ext/adapter.cc

@@ -1,28 +1,40 @@
 #include "adapter.h"
 
-// extend the default dbi::FieldSet class with some ruby love.
+// Extend the default dbi::FieldSet class with some ruby love.
 class Fields : public dbi::FieldSet {
   public:
-  Fields() : dbi::FieldSet(0) {}
+    Fields() : dbi::FieldSet(0) {}
 
-  void operator<<(VALUE v) {
-    VALUE name = TO_S(v);
-    fields.push_back(std::string(RSTRING_PTR(name), RSTRING_LEN(name)));
-  }
+    void operator<<(VALUE v) {
+      VALUE name = TO_S(v);
+      fields.push_back(std::string(RSTRING_PTR(name), RSTRING_LEN(name)));
+    }
 };
 
 static VALUE cSwiftAdapter;
 
+void build_extra_options_string(VALUE key, VALUE value, VALUE ptr) {
+  std::string *optstring = (std::string *)ptr;
+  *optstring += CSTRING(key) + std::string("=") + CSTRING(value) + std::string(";");
+}
+
+std::string parse_extra_options(VALUE options) {
+  std::string optstring = "";
+  if (!NIL_P(options))
+    rb_hash_foreach(options, RUBY_STATIC_FUNC(build_extra_options_string), (VALUE)&optstring);
+  return optstring;
+}
+
 static void adapter_free(dbi::Handle *handle) {
-    if (handle) {
-      handle->conn()->cleanup();
-      delete handle;
-    }
+  if (handle) {
+    handle->conn()->cleanup();
+    delete handle;
+  }
 }
 
 VALUE adapter_alloc(VALUE klass) {
-    dbi::Handle *handle = 0;
-    return Data_Wrap_Struct(klass, 0, adapter_free, handle);
+  dbi::Handle *handle = 0;
+  return Data_Wrap_Struct(klass, 0, adapter_free, handle);
 }
 
 dbi::Handle* adapter_handle(VALUE self) {
@@ -33,6 +45,14 @@ dbi::Handle* adapter_handle(VALUE self) {
   return handle;
 }
 
+/*
+  Begin a transaction (unit of work).
+
+  @overload commit(name = nil)
+    @param [Symbol, String] name Optional transaction name.
+
+  @see Swift::Adapter#transaction
+*/
 static VALUE adapter_begin(int argc, VALUE *argv, VALUE self) {
   VALUE save_point;
   rb_scan_args(argc, argv, "01", &save_point);
@@ -45,17 +65,31 @@ static VALUE adapter_begin(int argc, VALUE *argv, VALUE self) {
   return Qtrue;
 }
 
+/*
+  Close the connection.
+*/
 static VALUE adapter_close(VALUE self) {
   dbi::Handle *handle = adapter_handle(self);
   try { handle->close(); } CATCH_DBI_EXCEPTIONS();
   return Qtrue;
 }
 
-// TODO:
+/*
+  Shallow copy of adapter.
+
+  @note Currently not allowed.
+  @see  Object.clone
+*/
 static VALUE adapter_clone(VALUE self) {
   rb_raise(eSwiftRuntimeError, "clone is not allowed.");
 }
 
+/*
+  Commit a transaction (unit of work).
+
+  @overload commit(name = nil)
+    @param [Symbol, String] name Optional transaction name.
+*/
 static VALUE adapter_commit(int argc, VALUE *argv, VALUE self) {
   VALUE save_point;
   rb_scan_args(argc, argv, "01", &save_point);
@@ -68,14 +102,28 @@ static VALUE adapter_commit(int argc, VALUE *argv, VALUE self) {
   return Qtrue;
 }
 
-// TODO:
+/*
+  Shallow copy of adapter.
+
+  @note Currently not allowed.
+  @see  Object.dup
+*/
 static VALUE adapter_dup(VALUE self) {
   rb_raise(eSwiftRuntimeError, "dup is not allowed.");
 }
 
-// TODO: Attempt TO_S() before escaping?
+/*
+  Escape a string.
+
+  @note Bind values do not need to be escaped.
+
+  @overload escape(value)
+    @param  [String] value String to be escaped.
+    @return [String]
+*/
 static VALUE adapter_escape(VALUE self, VALUE value) {
-  if (TYPE(value) != T_STRING) rb_raise(eSwiftArgumentError, "Cannot escape non-string value.");
+  if (TYPE(value) != T_STRING)
+    value = TO_S(value);
 
   dbi::Handle *handle = adapter_handle(self);
   try {
@@ -85,7 +133,19 @@ static VALUE adapter_escape(VALUE self, VALUE value) {
   CATCH_DBI_EXCEPTIONS();
 }
 
-// TODO: Change bind_values to an array in the interface? Avoid array -> splat -> array.
+/*
+  Execute a single statement.
+
+  @example
+    result = User.execute("select * from #{User} where #{User.name} = ?", 'apple')
+    result.first # User object.
+
+  @overload execute(statement = '', *binds, &block)
+    @param  [String]  statement Query statement.
+    @param  [*Object] binds     Bind values.
+    @yield  [Swift::Result]
+    @return [Swift::Result]
+*/
 static VALUE adapter_execute(int argc, VALUE *argv, VALUE self) {
   VALUE statement, bind_values, block, rows, scheme = Qnil;
 
@@ -116,12 +176,38 @@ static VALUE adapter_execute(int argc, VALUE *argv, VALUE self) {
   CATCH_DBI_EXCEPTIONS();
 }
 
+/*
+  Reestablish a connection.
+*/
 static VALUE adapter_reconnect(VALUE self) {
   dbi::Handle *handle = adapter_handle(self);
   try { handle->reconnect(); } CATCH_DBI_EXCEPTIONS();
   return Qtrue;
 }
 
+/*
+  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'
+
+  @overload new(options = {})
+    @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
+*/
 static VALUE adapter_initialize(VALUE self, VALUE options) {
   VALUE db       = rb_hash_aref(options, ID2SYM(rb_intern("db")));
   VALUE driver   = rb_hash_aref(options, ID2SYM(rb_intern("driver")));
@@ -130,7 +216,18 @@ static VALUE adapter_initialize(VALUE self, VALUE options) {
   if (NIL_P(db))     rb_raise(eSwiftArgumentError, "Adapter#new called without :db");
   if (NIL_P(driver)) rb_raise(eSwiftArgumentError, "Adapter#new called without :driver");
 
-  user = NIL_P(user) ? CURRENT_USER() : user;
+  user           = NIL_P(user) ? current_user() : user;
+  VALUE extra    = rb_hash_dup(options);
+
+  rb_hash_delete(extra, ID2SYM(rb_intern("db")));
+  rb_hash_delete(extra, ID2SYM(rb_intern("driver")));
+  rb_hash_delete(extra, ID2SYM(rb_intern("user")));
+  rb_hash_delete(extra, ID2SYM(rb_intern("password")));
+  rb_hash_delete(extra, ID2SYM(rb_intern("host")));
+  rb_hash_delete(extra, ID2SYM(rb_intern("port")));
+  rb_hash_delete(extra, ID2SYM(rb_intern("timezone")));
+
+  std::string extra_options_string = parse_extra_options(extra);
 
   try {
     DATA_PTR(self) = new dbi::Handle(
@@ -139,16 +236,30 @@ static VALUE adapter_initialize(VALUE self, VALUE options) {
       CSTRING(rb_hash_aref(options, ID2SYM(rb_intern("password")))),
       CSTRING(db),
       CSTRING(rb_hash_aref(options, ID2SYM(rb_intern("host")))),
-      CSTRING(rb_hash_aref(options, ID2SYM(rb_intern("port"))))
+      CSTRING(rb_hash_aref(options, ID2SYM(rb_intern("port")))),
+      extra_options_string.size() > 0 ? (char*)extra_options_string.c_str() : 0
     );
   }
   CATCH_DBI_EXCEPTIONS();
 
-  rb_iv_set(self, "@timezone", rb_hash_aref(options, ID2SYM(rb_intern("timezone"))));
   rb_iv_set(self, "@options",  options);
+  rb_iv_set(self, "@timezone", rb_hash_aref(options, ID2SYM(rb_intern("timezone"))));
+
   return Qnil;
 }
 
+/*
+  Prepare a statement for on or more executions.
+
+  @example
+    sth = User.prepare("select * from #{User} where #{User.name} = ?")
+    sth.execute('apple') #=> Result
+    sth.execute('benny') #=> Result
+
+  @overload prepare(statement, &block)
+    @param  [String] statement Query statement.
+    @return [Swift::Statement]
+*/
 static VALUE adapter_prepare(int argc, VALUE *argv, VALUE self) {
   VALUE sql, scheme, prepared;
   dbi::AbstractStatement *statement;
@@ -170,6 +281,12 @@ static VALUE adapter_prepare(int argc, VALUE *argv, VALUE self) {
   CATCH_DBI_EXCEPTIONS();
 }
 
+/*
+  Rollback the current transaction.
+
+  @overload rollback(name = nil)
+    @param [Symbol, String] name Optional transaction name.
+*/
 static VALUE adapter_rollback(int argc, VALUE *argv, VALUE self) {
   VALUE save_point;
   dbi::Handle *handle = adapter_handle(self);
@@ -182,12 +299,16 @@ static VALUE adapter_rollback(int argc, VALUE *argv, VALUE self) {
   return Qtrue;
 }
 
+/*
+  Block form transaction sugar.
+
+  @overload transaction(name = nil, &block)
+    @param [Symbol, String] name Optional transaction name.
+*/
 static VALUE adapter_transaction(int argc, VALUE *argv, VALUE self) {
   int status;
   VALUE sp, block, block_result = Qnil;
-
   dbi::Handle *handle = adapter_handle(self);
-
   rb_scan_args(argc, argv, "01&", &sp, &block);
 
   if (NIL_P(block)) rb_raise(eSwiftArgumentError, "Transaction called without a block.");
@@ -209,6 +330,16 @@ static VALUE adapter_transaction(int argc, VALUE *argv, VALUE self) {
   return block_result;
 }
 
+/*
+  Bulk insert resources.
+
+  @overload write(store, fields, stream)
+    @param [Swift::Scheme, String]           store  Write to store.
+    @param [Array<Swift::Attribute, String>] fields Write to fields in store.
+    @param [IO]                              stream IO to read from.
+
+  @note The format of the stream and bulk write performance are entirely down to each adapter.
+*/
 static VALUE adapter_write(int argc, VALUE *argv, VALUE self) {
   uint64_t rows = 0;
   VALUE stream, table, fields;
@@ -234,11 +365,11 @@ static VALUE adapter_write(int argc, VALUE *argv, VALUE self) {
 
     if (TYPE(stream) == T_STRING) {
       dbi::StringIO io(RSTRING_PTR(stream), RSTRING_LEN(stream));
-      rows = handle->write(RSTRING_PTR(table), write_fields, &io);
+      rows = handle->write(RSTRING_PTR(TO_S(table)), write_fields, &io);
     }
     else {
       AdapterIO io(stream);
-      rows = handle->write(RSTRING_PTR(table), write_fields, &io);
+      rows = handle->write(RSTRING_PTR(TO_S(table)), write_fields, &io);
     }
     return SIZET2NUM(rows);
   }
@@ -266,4 +397,3 @@ void init_swift_adapter() {
   rb_define_alloc_func(cSwiftAdapter, adapter_alloc);
 }
 
-

data/ext/extconf.rb

@@ -1,17 +1,17 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
 require 'mkmf'
 
 Config::CONFIG['CC']  = 'g++'
 Config::CONFIG['CPP'] = 'g++'
 
-$CFLAGS  = '-fPIC -Os'
+$CFLAGS  = '-fPIC -Os -I/usr/include -I/opt/local/include -I/usr/local/include'
 
 def apt_install_hint pkg
   "sudo apt-get install #{pkg}"
 end
 
 def library_installed? name, hint
-  if have_library(name)
+  if find_library(name, 'main', *%w(/usr/lib /usr/local/lib /opt/lib /opt/local/lib /sw/lib))
     true
   else
     $stderr.puts <<-ERROR

data/ext/pool.cc

@@ -26,7 +26,7 @@ VALUE pool_init(VALUE self, VALUE n, VALUE options) {
   if (NIL_P(db))     rb_raise(eSwiftArgumentError, "Pool#new called without :db");
   if (NIL_P(driver)) rb_raise(eSwiftArgumentError, "#new called without :driver");
 
-  user = NIL_P(user) ? CURRENT_USER() : user;
+  user = NIL_P(user) ? current_user() : user;
   if (NUM2INT(n) < 1) rb_raise(eSwiftArgumentError, "Pool#new called with invalid pool size.");
 
   try {

data/ext/result.cc

@@ -45,12 +45,12 @@ dbi::AbstractResult* result_handle(VALUE self) {
   return handle->result;
 }
 
-// TODO:
+// NOTE clone and dup cannot be allowed since the underlying c++ object needs to be cloned, which
+//      frankly is too much work :)
 static VALUE result_clone(VALUE self) {
   rb_raise(eSwiftRuntimeError, "clone is not allowed.");
 }
 
-// TODO:
 static VALUE result_dup(VALUE self) {
   rb_raise(eSwiftRuntimeError, "dup is not allowed.");
 }

data/ext/statement.cc

@@ -43,7 +43,7 @@ dbi::AbstractStatement* statement_handle(VALUE self) {
   return handle->statement;
 }
 
-// TODO: Change bind_values to an array in the interface? Avoid array -> splat -> array.
+// array -> splat -> array is an overhead, but it reads nicer.
 static VALUE statement_execute(int argc, VALUE *argv, VALUE self) {
   VALUE bind_values, block;
   rb_scan_args(argc, argv, "0*&", &bind_values, &block);

data/ext/swift.cc

@@ -7,17 +7,45 @@ VALUE eSwiftArgumentError;
 VALUE eSwiftRuntimeError;
 VALUE eSwiftConnectionError;
 
+/*
+  Initialize Swift with a non standard dbic++ path.
+
+  @note
+    By default Swift looks in '/usr/lib/dbic++/'. Not normally required unless you install dbic++ somewhere funny.
+
+  @overload init(path)
+    @param [path] path Non standard dbic++ path.
+*/
 VALUE swift_init(VALUE self, VALUE path) {
   try { dbi::dbiInitialize(CSTRING(path)); } CATCH_DBI_EXCEPTIONS();
   return Qtrue;
 }
 
+/*
+  Trace statement execution.
+
+  @example Toggle tracing.
+    Swift.trace true
+    Swift.db.execute 'select * from users'
+    Swift.trace false
+  @example Block form.
+    Swift.trace true do
+      Swift.db.execute 'select * from users'
+    end
+
+  @overload trace(show = true, output = $stderr)
+    @param [true, false] show   Optional trace toggle boolean.
+    @param [IO]          output Optional output. Defaults to stderr.
+*/
 VALUE swift_trace(int argc, VALUE *argv, VALUE self) {
     VALUE flag, io;
     rb_io_t *fptr;
-    int fd = 2; // defaults to stderr
+    int status, fd = 2; // defaults to stderr
 
-    rb_scan_args(argc, argv, "11", &flag, &io);
+    rb_scan_args(argc, argv, "02", &flag, &io);
+
+    if (NIL_P(flag))
+      flag = Qtrue;
 
     if (TYPE(flag) != T_TRUE && TYPE(flag) != T_FALSE)
         rb_raise(eSwiftArgumentError, "Swift#trace expects a boolean flag, got %s", CSTRING(flag));
@@ -27,8 +55,25 @@ VALUE swift_trace(int argc, VALUE *argv, VALUE self) {
         fd = fptr->fd;
     }
 
-    dbi::trace(flag == Qtrue ? true : false, fd);
-    return flag;
+    // block form trace
+    if (rb_block_given_p()) {
+      // orig values
+      bool orig_trace    = dbi::_trace;
+      int  orig_trace_fd = dbi::_trace_fd;
+
+      dbi::trace(flag == Qtrue ? true : false, fd);
+      VALUE block_result = rb_protect(rb_yield, Qnil, &status);
+      dbi::trace(orig_trace, orig_trace_fd);
+
+      if (status)
+        rb_jump_tag(status);
+      else
+        return block_result;
+    }
+    else {
+      dbi::trace(flag == Qtrue ? true : false, fd);
+      return flag;
+    }
 }
 
 VALUE atexit_gc(...) {

data/ext/swift.h

@@ -12,6 +12,7 @@
 #define CONST_GET(scope, constant) rb_funcall(scope, rb_intern("const_get"), 1, rb_str_new2(constant))
 #define TO_S(v)                    rb_funcall(v, rb_intern("to_s"), 0)
 #define CSTRING(v)                 RSTRING_PTR(TO_S(v))
+#define RUBY_STATIC_FUNC(func)     ((int (*)(ANYARGS))func)
 
 extern VALUE eSwiftError;
 extern VALUE eSwiftArgumentError;
@@ -31,7 +32,7 @@ extern VALUE eSwiftConnectionError;
 
 
 // works without a controlling tty, getlogin() will fail when process is daemonized.
-inline VALUE CURRENT_USER() {
+inline VALUE current_user() {
   struct passwd *ptr = getpwuid(getuid());
   return ptr ? rb_str_new2(ptr->pw_name) : rb_str_new2("root");
 }

data/lib/swift/adapter/sql.rb

@@ -0,0 +1,69 @@
+require 'swift/adapter'
+
+module Swift
+  class Adapter
+
+    # Abstract SQL Adapter.
+    #
+    # @abstract
+    class Sql < Adapter
+      protected
+        def returning?
+          raise NotImplementedError
+        end
+
+        def prepare_cached scheme, name, &block
+          @prepared               ||= Hash.new{|h,k| h[k] = Hash.new}
+          @prepared[scheme][name] ||= prepare(scheme, yield)
+        end
+
+        def prepare_get scheme
+          prepare_cached(scheme, :get) do
+            where = scheme.header.keys.map{|key| "#{key} = ?"}.join(' and ')
+            "select * from #{scheme.store} where #{where} limit 1"
+          end
+        end
+
+        def prepare_create scheme
+          prepare_cached(scheme, :create) do
+            values    = (['?'] * scheme.header.insertable.size).join(', ')
+            returning = "returning #{scheme.header.serial}" if scheme.header.serial and returning?
+            "insert into #{scheme.store} (#{scheme.header.insertable.join(', ')}) values (#{values}) #{returning}"
+          end
+        end
+
+        def prepare_update scheme
+          prepare_cached(scheme, :update) do
+            set   = scheme.header.updatable.map{|field| "#{field} = ?"}.join(', ')
+            where = scheme.header.keys.map{|key| "#{key} = ?"}.join(' and ')
+            "update #{scheme.store} set #{set} where #{where}"
+          end
+        end
+
+        def prepare_delete scheme
+          prepare_cached(scheme, :delete) do
+            where = scheme.header.keys.map{|key| "#{key} = ?"}.join(' and ')
+            "delete from #{scheme.store} where #{where}"
+          end
+        end
+
+        def field_definition attribute
+          "#{attribute.field} " + field_type(attribute)
+        end
+
+        def field_type attribute
+          case attribute
+            when Type::String     then 'text'
+            when Type::Integer    then attribute.serial ? 'serial' : 'integer'
+            when Type::Float      then 'float'
+            when Type::BigDecimal then 'numeric'
+            when Type::Time       then 'timestamp'
+            when Type::Date       then 'date'
+            when Type::Boolean    then 'boolean'
+            when Type::IO         then 'blob'
+            else 'text'
+          end
+        end
+    end # Sql
+  end # Adapter
+end # Swift