sinatra-dm 0.1.2 → 0.1.3

data/README.rdoc

@@ -1,6 +1,169 @@
-= sinatra-dm
+= Sinatra::DM 
+
+A Sinatra Extension that makes working with DataMapper easier.
+
+
+== Installation
+
+  #  Add Gemcutter to your RubyGems sources 
+  $  gem sources -a http://gemcutter.com
+
+  $  (sudo)? gem install sinatra-dm
+
+== Dependencies
+
+This Gem depends upon the following:
+
+=== Runtime:
+
+* sinatra ( >= 0.10.1 )
+* dm-core ( >= 0.10.1 )
+
+And a constant named ::APP_ROOT defined in your App, pointing to the root of your app.
+
+  # set the root of the whole app
+  APP_ROOT = Dir.pwd
+  
+==== Question:
+
+Do you know how I can avoid this APP_ROOT constant inside the Extension, but still use full paths ?
+If so, please let me know.
+
+
+=== Development & Tests:
+
+* rspec (>= 1.2.7 )
+* rack-test (>= 0.4.1)
+* rspec_hpricot_matchers (>= 0.1.0)
+* sinatra-tests (>= 0.1.5)
+
+=== Optional:
+
+* kematzy-tasks (>= 0.1.5) # handy Rake tasks for working with SQLite3 DB's
+
+
+
+
+== Getting Started
+
+
+In your Sinatra app code base, 
+
+  require 'sinatra/dm'
+  
+
+then in your App declaration,
+
+  
+  class YourApp < Sinatra::Base 
+    register(Sinatra::DataMapperExtension)  # NOTE:: the extension name
+    
+    # NOTE:: need to ensure this is set this for the logger to function
+    set :environment, ENV['RACK_ENV'].to_sym || :test
+    
+    # NOTE:: The database configuration must be set so 
+    # the DataMapper.auto_migrate! / .auto_upgrade! migrations work
+    set :database, dm_database_url
+    
+    ## ROUTES 
+    get '/posts' do
+      @posts = Post.all
+    end
+    
+  end
+
+Most of the above is obvious, but this line...
+
+  set :database, dm_database_url
+
+...is perhaps a bit confusing, so let's clarify it.
+
+<tt>#dm_database_url</tt> is an Extension setting - (see below) - that contains the whole
+SQLite3 DSN string.
+
+  "sqlite3:///path/2/your/app/root/db/db.test.db"
+
+
+In real terms, you could just as well have written this:
+
+  set :database, "sqlite3:///path/2/your/app/root/db/db.test.db"
+  
+or
+
+  set :database, "mysql://username:password@dbhost/db_name"
+  
+  # if you have MySQL set up **insecurely** on your local workstation
+  set :database, "mysql://root:@dbhost/db_name"
+
+
+
+== Configuration Options 
+
+The following options are available for you to configure your DataMapper setup
+
+* <tt>:db_dir</tt> -- sets the path to where your SQLite3 DBs should be.
+  (Default: [/full/path/2/your/app/db] )
+
+* <tt>:dm_logger_level</tt> -- sets the level at which DataMapper.Logger should log.
+  (Default: [:debug] )
+
+* <tt>:dm_logger_path</tt> -- sets the path to the log file where DataMapper.Logger should log.
+  (Default: [/full/path/2/your/app/log/dm.{environment}.log] )
+
+* <tt>:dm_setup_context</tt> -- sets the DataMapper Setup context.
+  (Default: [:default] )
+
+* <tt>:dm_database_url</tt> -- sets the DSN.
+  (Default: ENV['DATABASE_URL'] || "sqlite3://#{db_dir}/db.#{environment}.db" )
+  
+
+There are many ways in which you can use the above configurations in YourApp. 
+
+Here are a few examples:
+
+  class YourApp < Sinatra::Base
+    register(Sinatra::DataMapperExtension)  # NOTE:: the extension name
+    
+    <snip...>
+    
+    # set the db path to outside of your app root
+    set :db_dir, "/home/USERNAME/SQLite3-dbs/"
+    
+    # to only log :warn and above
+    set :dm_logger_level, :warn
+    
+    # set the path to your log files outside of your app root
+    set :dm_logger_path, "/var/log/dm.your_app.log"
+    
+    # use a different Setup context than :default
+    set :dm_setup_context, :custom
+      
+    <snip...>
+    
+    # NB! Don't forget to set the database configuration
+    set :database, dm_database_url
+  
+  end
+
+
+== RTFM
+
+If the above is NOT clear enough, please check the Specs for a better understanding.
+
+
+== TODOs
+
+There are a number of things I'd love to have help with through a fork:
+
+* Enabling DataMapper Migrations to work flawlessly.
+
+* Decide if there should be a :dm_logger_status (On/Off) switch for turning off DM logger
+
+* Test it with a PostgreSQL db (although I'm sure it would work fine there as is)
+
+* Any other improvements you can think of.
+
 
-Description goes here.
 
 == Note on Patches/Pull Requests
  
@@ -15,4 +178,7 @@ Description goes here.
 
 == Copyright
 
-Copyright (c) 2009 kematzy. See LICENSE for details.
+Copyright (c) 2009 kematzy. Released under the MIT License.
+
+See LICENSE for details.
+

data/Rakefile

@@ -12,6 +12,7 @@ begin
     gem.authors = ["kematzy"]
     gem.add_dependency('sinatra', '>= 0.10.1')
     gem.add_dependency('dm-core', '>= 0.10.1')
+    gem.add_dependency('kematzy-tasks', '>= 0.1.0')
     # gem.add_dependency('dependency', '>=x.x.x')
     gem.add_development_dependency("sinatra-tests", '>= 0.1.5')
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
@@ -36,6 +37,23 @@ end
 
 task :spec => :check_dependencies
 
+namespace :spec do
+
+  desc "Run all specifications quietly"
+  Spec::Rake::SpecTask.new(:quiet) do |t|
+    t.libs << "lib"
+    t.spec_opts = ["--color", "--require", "spec/spec_helper.rb"]
+  end
+  
+  desc "Run specific spec (SPEC=/path/2/file)"
+  Spec::Rake::SpecTask.new(:select) do |t|
+    t.libs << "lib"
+    t.spec_files = [ENV["SPEC"]]
+    t.spec_opts = ["--color", "--format", "specdoc", "--require", "spec/spec_helper.rb"] 
+  end
+  
+end
+
 task :default => :spec
 
 require 'rake/rdoctask'

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.3

data/lib/sinatra/dm.rb

@@ -1,89 +1,273 @@
 
 require 'sinatra/base'
 require 'dm-core'
-# # require 'dm-migrations'
-# require 'dm-timestamps'
-# require 'dm-validations'
-# require 'dm-serializer'
-# require 'dm-types'
 
 module Sinatra
   
-  # Sinatra DataMapperExtension module
+  # = Sinatra DataMapperExtension module
+  # 
+  # A Sinatra Extension that makes working with DataMapper easier.
+  # 
+  # 
+  # == Installation
+  # 
+  #   #  Add Gemcutter to your RubyGems sources 
+  #   $  gem sources -a http://gemcutter.com
+  # 
+  #   $  (sudo)? gem install sinatra-dm
+  # 
+  # == Dependencies
+  # 
+  # This Gem depends upon the following:
+  # 
+  # === Runtime:
+  # 
+  # * sinatra ( >= 0.10.1 )
+  # * dm-core ( >= 0.10.1 )
+  # 
+  # And a constant named ::APP_ROOT defined in your App, pointing to the root of your app.
+  # 
+  #   # set the root of the whole app
+  #   APP_ROOT = Dir.pwd
+  # 
+  # === Development & Tests:
+  # 
+  # * rspec (>= 1.2.7 )
+  # * rack-test (>= 0.4.1)
+  # * rspec_hpricot_matchers (>= 0.1.0)
+  # * sinatra-tests (>= 0.1.5)
+  # 
+  # === Optional:
+  # 
+  # * kematzy-tasks (>= 0.1.5) # handy Rake tasks for working with SQLite3 DB's
+  # 
+  # 
+  # == Getting Started
+  # 
+  # In your Sinatra app code base, 
+  # 
+  #   require 'sinatra/dm'
+  # 
+  # then in your App declaration,
+  # 
+  # 
+  #   class YourApp < Sinatra::Base 
+  #     register(Sinatra::DataMapperExtension)  # NOTE:: the extension name
+  # 
+  #     # NOTE:: need to ensure this is set this for the logger to function
+  #     set :environment, ENV['RACK_ENV'].to_sym || :test
+  # 
+  #     # NOTE:: The database configuration must be set so 
+  #     # the DataMapper.auto_migrate! / .auto_upgrade! migrations work
+  #     set :database, dm_database_url
+  # 
+  #     ## ROUTES 
+  #     get '/posts' do
+  #       @posts = Post.all
+  #     end
+  # 
+  #   end
+  # 
+  # Most of the above is obvious, but this line...
+  # 
+  #   set :database, dm_database_url
+  # 
+  # ...is perhaps a bit confusing, so let's clarify it.
+  # 
+  # <tt>#dm_database_url</tt> is an Extension setting - (see below) - that contains the whole
+  # SQLite3 DSN string.
+  # 
+  #   "sqlite3:///path/2/your/app/root/db/db.test.db"
+  # 
+  # 
+  # In real terms, you could just as well have written this:
+  # 
+  #   set :database, "sqlite3:///path/2/your/app/root/db/db.test.db"
+  # 
+  # or
+  # 
+  #   set :database, "mysql://username:password@dbhost/db_name"
+  # 
+  #   # if you have MySQL set up **insecurely** on your local workstation
+  #   set :database, "mysql://root:@dbhost/db_name"
+  # 
+  # 
+  # 
+  # == Configuration Options 
+  # 
+  # The following options are available for you to configure your DataMapper setup
+  # 
+  # * <tt>:db_dir</tt> -- sets the path to where your SQLite3 DBs should be.
+  #   (Default: [/full/path/2/your/app/db] )
+  # 
+  # * <tt>:dm_logger_level</tt> -- sets the level at which DataMapper.Logger should log.
+  #   (Default: [:debug] )
+  # 
+  # * <tt>:dm_logger_path</tt> -- sets the path to the log file where DataMapper.Logger should log.
+  #   (Default: [/full/path/2/your/app/log/dm.{environment}.log] )
+  # 
+  # * <tt>:dm_setup_context</tt> -- sets the DataMapper Setup context.
+  #   (Default: [:default] )
+  # 
+  # * <tt>:dm_database_url</tt> -- sets the DSN.
+  #   (Default: ENV['DATABASE_URL'] || "sqlite3://#{db_dir}/db.#{environment}.db" )
+  # 
+  # 
+  # There are many ways in which you can use the above configurations in YourApp. 
+  # 
+  # Here are a few examples:
+  # 
+  #   class YourApp < Sinatra::Base
+  #     register(Sinatra::DataMapperExtension)  # NOTE:: the extension name
+  #     
+  #     <snip...>
+  #     
+  #     # set the db path to outside of your app root
+  #     set :db_dir, "/home/USERNAME/SQLite3-dbs/"
+  #     
+  #     # to only log :warn and above
+  #     set :dm_logger_level, :warn
+  #     
+  #     # set the path to your log files outside of your app root
+  #     set :dm_logger_path, "/var/log/dm.your_app.log"
+  #     
+  #     # use a different Setup context than :default
+  #     set :dm_setup_context, :custom
+  #     
+  #     <snip...>
+  #     
+  #     # NB! Don't forget to set the database configuration
+  #     set :database, dm_database_url
+  #     
+  #   end
+  # 
   # 
-  #  TODO:: Need to write documentation here 
   # 
   module DataMapperExtension 
     
-    VERSION = '0.1.2' unless const_defined?(:VERSION)
+    VERSION = '0.1.3' unless const_defined?(:VERSION)
     def self.version; "Sinatra::DataMapperExtension v#{VERSION}"; end
     
     module Helpers 
       
       ##
-      # TODO: add some comments here
+      # Access to the database settings, should you need them
+      # within your app
       #  
       # ==== Examples
       # 
+      #   if database.name == :default
+      #     # do something...
+      # 
+      #   
       # 
       # @api public
-      def database
-        options.database
+      def database 
+        settings.database
+      end
+      
+      ##
+      # Handy alias to the DataMapper logger
+      #  
+      # ==== Examples
+      # 
+      #   db_logger.info("message")
+      #   
+      # 
+      # @api public/private
+      def db_logger
+        self.class.database_logger
       end
       
     end #/ Helpers
     
     
     ##
-    # TODO: add some comments here
+    # Sets the Database DSN connection, and setup name.
     #  
     # ==== Examples
+    #   
+    #   # Default usage is via the set :database setting
+    #   
+    #   set :database, "sqlite3:///path/2/your/app/db/test.db"
+    #   
+    # 
+    # But you can also set the db connection on your App directly via this as a class method
+    # 
+    #   YourApp.database = "sqlite3:///path/2/your/app/db/test.db", :custom_setup_name
     # 
     # 
     # @api public
-    def database=(url, context = :default)
-      # NOTE:: see note below in :database method 
-      # @database = nil  
+    def database=(*args) 
+      if args.first.is_a?(Array)
+        reset_db = true
+        url = args.first[0]
+        context = args.first[1] || dm_setup_context || :default
+      else
+        url = args.first
+        context = dm_setup_context || :default
+      end
       set :dm_setup_context, context
-      set :database_url, url
-      db_type = database_url.split('://').first
-      db_url = database_url.sub(::APP_ROOT, '').sub("#{db_type}://",'')
+      set :dm_database_url, url
+      db_type = dm_database_url.split('://').first
+      db_url = dm_database_url.sub(::APP_ROOT, '').sub("#{db_type}://",'')
       puts "-- - activated DataMapper #{db_type.capitalize} Database at [ #{db_url} ]"
+      database_reset if reset_db
       database_logger
       database
     end
     
     ##
-    # TODO: add some comments here
+    # Provides access to your database setup
     #  
     # ==== Examples
     # 
+    #   YourApp.database  => returns the whole DataMapper db setup 
+    # 
     # 
     # @api public
-    def database
+    def database 
       # NOTE:: Having an instance variable here, causes problems
       # when having two Sinatra Apps, each with their own db setup.
       # the instance variable retains only the last setup, so the
       # first setup is overwritten.
-      database ||= ::DataMapper.setup(dm_setup_context, database_url)
+      @database ||= ::DataMapper.setup(dm_setup_context, dm_database_url)
     end
     
+    ##
+    # Resets the current DB setup and connection
+    #  
+    # ==== Examples
+    # 
+    # 
+    # @api private
+    def database_reset
+      @database = nil
+    end
     
     ##
-    # TODO: add some comments here
+    # Sets up the DataMapper::Logger instance, caches it and returns it
     #  
     # ==== Examples
+    #   
+    #   YourApp.database_logger.debug("Message") => log's message in the log
     # 
     # 
     # @api public
-    def database_logger
+    def database_logger 
+      # NOTE:: Having an instance variable here, causes problems
+      # when having two Sinatra Apps, each with their own db setup.
+      # the instance variable retains only the last setup, so the
+      # first setup is overwritten.
       @database_logger ||= ::DataMapper::Logger.new(dm_logger_path, dm_logger_level)
     end
     
+    # :nodoc:
+    
     ## TODO: Should support real migrations, 
     
     ##
-    # TODO: add some comments here
+    # TODO: implement this functionality
     #  
     # ==== Examples
     # 
@@ -99,7 +283,7 @@ module Sinatra
     # end
     
     ##
-    # TODO: add some comments here
+    # TODO: implement this functionality
     #  
     # ==== Examples
     # 
@@ -119,31 +303,16 @@ module Sinatra
     #   define_method("#{adapter}?") { @database.options['adapter'] == adapter } 
     # end
     
-  protected
-    
-    
-    # ##
-    # # TODO: add some comments here
-    # #  
-    # # ==== Examples
-    # # 
-    # # 
-    # # @api public
-    # def create_migrations_table
-    #   database.create_table? :migrations do
-    #     primary_key :id
-    #     text :name, :null => false, :index => true
-    #     timestamp :ran_at
-    #   end
-    # end
+    # :doc:
     
+  protected
     
     def self.registered(app)
       app.set :db_dir, "#{::APP_ROOT}/db"
       app.set :dm_logger_level, :debug
       app.set :dm_logger_path, lambda { "#{::APP_ROOT}/log/dm.#{environment}.log" }
       app.set :dm_setup_context, :default
-      app.set :database_url, lambda { ENV['DATABASE_URL'] || "sqlite3://#{::APP_ROOT}/db/#{environment}.db" }
+      app.set :dm_database_url, lambda { ENV['DATABASE_URL'] || "sqlite3://#{db_dir}/db.#{environment}.db" }
       
       # app.set :migrations_table_name, :migrations
       # app.set :migrations_log, lambda { STDOUT }
@@ -152,42 +321,16 @@ module Sinatra
       
       ## add the extension specific options to those inspectable by :options_inspect method
       if app.respond_to?(:sinatra_options_for_inspection)
-        %w( db_dir dm_logger_path dm_logger_level database_url 
+        %w( db_dir dm_logger_path dm_logger_level dm_database_url 
         dm_setup_context database ).each do |m|
           app.sinatra_options_for_inspection << m
         end
       end
       
-      # QUESTION:: Should this actually be here? 
-      # or should I just use the rake tasks
-      # 
-      if app.development?
-        app.get '/install/db/bootstrap' do 
-          out = ""
-          Dir["#{::APP_ROOT}/db/bootstraps/*.sql"].each do |b|
-            db = self.class.database_url.sub('sqlite3://','')
-            `sqlite3 #{db} < #{b}`
-            out << "\t\t<li> -- #{b.sub(::APP_ROOT,'..')} loaded</li>\n"
-          end
-          
-          html = %Q[<div id="main-content">\n]
-          html << %Q[\t<h2>Install :: Database Bootstrapping</h2>\n]
-          html << %Q[\t<p>Loading bootstraps from [ #{::APP_ROOT}/db/bootstraps/ ]</p>\n]
-          html << %Q[\t<ul>\n]
-          html << out
-          html << %Q[\t</ul>\n]
-          html << %Q[\t<p>Bootstrapping finished.</p>\n]
-          html << %Q[\t<p><a href="javascript:history.go(-1);">Go Back</a></p>\n]
-          html << %Q[</div>\n]
-          
-          erb(html)
-        end
-      end
-      
     end #/ self.registered
     
   end #/ DataMapperExtension
   
-  register(Sinatra::DataMapperExtension)
+  # register(Sinatra::DataMapperExtension)
   
 end #/ Sinatra