throne 0.0.1 → 0.0.2

data/.gitignore

@@ -19,4 +19,7 @@ rdoc
 pkg
 
 ## PROJECT::SPECIFIC
-smeg2.gemspec
+
+# Docs - these are generated
+.yardoc
+doc/*

data/{README.md → README.rdoc}

@@ -1,10 +1,20 @@
-# ♚ Throne
+= ♚ Throne
 
 The king is here - on his couch, covered in rubies.
 
 Simple library for working with CouchDB
 
-## Basic Usage
+== Caution!
+
+This code is in _heavy_ development, in conjunction with a few development projects.
+This means the API can and probably will change substantially over the next few
+releases as we work out what fits best. You have been warned.
+
+== API documentation
+
+can be found at http://rdoc.info/projects/lstoll/throne
+
+== Basic Usage
 
 Create a database object to work with. Will create the DB if it doesn't exist
 
@@ -33,21 +43,28 @@ Delete a document
 
     @db.delete(document_id_or_document_object)
 
-Run a design document
+Run a design document/function
 
-    @db.design('DesignDoc/_view/viewname')
+    res = @db.function('_design/DesignDoc/_view/viewname')
+    res
     => An array of documents
+    res.offset
+    => couchdb offset data
 
     # with parameters
-    @db.design('DD/_list/listname/viewname', :key => ab..fg, :xyz => 7)
+    @db.function('_design/DD/_list/listname/viewname', :key => ab..fg, :xyz => 7)
     => An array of documents
 
     # Iterator Method
-    @db.design('DesignDoc/_view/viewname') do |doc|
+    @db.function('_design/DesignDoc/_view/viewname') do |doc|
       #invoked for each document
       p doc
     end
 
+    # All documents
+    @db.function('_all_docs')
+    => All docs in the database
+
 Delete the database
 
     @db.delete_database
@@ -56,7 +73,7 @@ Create the database
   
     @db.create_database
 
-## Note on Patches/Pull Requests
+== Note on Patches/Pull Requests
  
 * Fork the project.
 * Make your feature addition or bug fix.
@@ -66,6 +83,6 @@ Create the database
   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
-# Copyright
+== Copyright
 
 Copyright (c) 2009 Lincoln Stoll, Ben Schwarz. See LICENSE for details.

data/TODO

@@ -0,0 +1,21 @@
+* Update the get method to take an existing doc, and reload it. Use ETags
+* At the top level retrieved, look for a RubyType field, and cast
+* vague AR methods (Create, save, hooks) 
+
+* Model Thoughts:
+  * Everything extends Dash.
+  * When a new Document is instantiated, it's RubyClass property is set to its class
+  * It's converted to JSON just by calling to_json on the parent 'document' class
+  * When it's parsed in, the overridden/delegated get method checks the type of the
+    parent object, and in instantiates it, passing the JSON hash in as a constuctor.
+  * The super constructor then loops the sub items, instantiating when it see's a 
+    RubyClass object, otherwise just setting the value.
+  * There should be a different parent class for Master documents and the sub items.
+    sub item's don't have save/get methods - only useful when loading from a view.
+
+* Bulk fetch, and maybe bulk update.
+  * Bulk fetch, get method checks for array param. If it's an array, POST with keys
+  * bulk put, save method checks for array param, and bundles into docs array
+
+* Attachments
+  * Just a put to url/attchment with data attached. Data in as a #read object?

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/lib/throne/database.rb

@@ -33,9 +33,17 @@ class Throne::Database
   end
 
   # gets a document by it's ID
+  # 
+  # @param [String] docid the ID of the document to retrieve
+  # @param [String] rev (optional) the revision of the document to retrieve
+  # @return [Hash, nil] the document mapped to a hash, or nil if not found.
   def get(docid, rev=nil)
-    revurl = rev ? "?rev=#{rev}" : ""
-    JSON.parse(c.get(@url + '/' + docid + revurl))
+    begin
+      revurl = rev ? "?rev=#{rev}" : ""
+      JSON.parse(c.get(@url + '/' + docid + revurl))
+    rescue RestClient::ResourceNotFound
+      nil
+    end
   end
 
   # creates/updates a document from a hash/array structure
@@ -62,10 +70,11 @@ class Throne::Database
     c.delete(@url + '/' + doc + '?rev=' + rev)
   end
 
-  # runs a design by path, with optional params passed in
-  def design(path, params = {}, &block)
-    url = @url + '/_design/' + path
+  # runs a function by path, with optional params passed in
+  def function(path, params = {}, &block)
+    url = @url + '/' + path
     res = JSON.parse(c.get(paramify_url(url, params)))
+    res = Throne::ArrayWithFunctionMeta.new(res['rows'], res['offset'])
     if block_given?
       # TODO - stream properly
       res.each do |i|
@@ -77,8 +86,6 @@ class Throne::Database
     end
   end
 
-
-
   private
 
   def paramify_url url, params = {}
@@ -96,7 +103,9 @@ class Throne::Database
   def c; RestClient; end
 end
 
+# Extended string, to store the couch revision
 class Throne::StringWithRevision < String
+  # Couch revision ID
   attr_reader :revision
 
   def initialize(id, rev)
@@ -104,3 +113,15 @@ class Throne::StringWithRevision < String
     super(id)
   end
 end
+
+# Extended array, to store the couch extra data
+class Throne::ArrayWithFunctionMeta < DelegateClass(Array)
+  # Offset field as returned by couch
+  attr_reader :offset
+  
+  def initialize(array, offset)
+    @offset = offset
+    super(array)
+  end
+end
+

data/lib/throne/tasks.rb

@@ -1,52 +1,254 @@
 # Defines rake tasks for managing databases and views.
+#
+# Requires either a SERVER_URL or DB_URL defined as an environment variable.
+# If SERVER_URL is set the database path is inferred from the directory the files
+# are stored in, if DB_URL is set that database is explicitly used, 
+# overriding the name of the folder/task. 
 class Throne::Tasks
-  def self.inject_fixtures_tasks(base_path)
+  # Injects rake tasks for loading and dumping data from databases.
+  # @param [String] base_path the path where design docs are stored
+  def self.inject_data_tasks(base_path)
     namespace :throne do
-      namespace :load_fixtures do
+      namespace :load_data do
         dirs_in_path(base_path).each do |dir, fulldir|
-          desc "Loads fixtures for database #{dir}"
+          desc "Loads data for database #{dir}"
           task dir.to_sym do
-            @db = Throne::Database.new(url(dir))
-            items = []
-            # grab and parse all YML files
-            Dir.glob(fulldir + '/**/*.yml').each do |yml|
-              items << YAML::load(File.open(yml))
-            end
-            # and json
-            Dir.glob(fulldir + '/**/*.json').each do |json|
-              items << JSON.parse(File.open(json).read)
-            end
-            # load em up
-            items.each do |item|
-              if item.kind_of? Array
-                item.each do |doc|
-                  @db.save(doc)
-                end
-              elsif item.kind_of? Hash
-                @db.save(item)
-              else
-                puts "There is something funky with the data for #{dir}"
-              end
-            end
-
-            p items[0]
+            load_data_for_database(url(dir), fulldir)
           end
         end
 
         desc "load all dbs"
         task :all => dirs_in_path(base_path)
       end
+      namespace :dump_data do
+        desc "Dump data for a database into a YAML file"
+        task :yml, :db do |t, args|
+          dump_docs_from_db(args.db, base_path, :yml)
+        end
+
+        desc "Dump data for a database into a JSON file"
+        task :json, :db do |t, args|
+          dump_docs_from_db(args.db, base_path, :json)
+        end
+      end
     end
   end
 
+  # This will inject Rake tasks for loading design docs into the DB
+  # The docs should be layed out in the following format:
+  # base_path/
+  # |-- <db name>
+  #      `-- <design doc name>
+  #          |-- lists
+  #          |   `-- statuses
+  #          |       `-- list.js
+  #          `-- views
+  #              `-- statuses
+  #                  |-- map.js
+  #                  `-- reduce.js 
+  #
+  # @param [String] base_path the path where design docs are stored
   def self.inject_design_doc_tasks(base_path)
     namespace :throne do
-      desc "Pushes all design docs into the named db url"
-      task :push_designs do
+      namespace :push_design do
+        dirs_in_path(base_path).each do |dir, fulldir|
+          desc "pushes designs for database #{dir}"
+          task dir.to_sym do
+            load_design_documents(url(dir), fulldir)
+          end
+        end
+
+        desc "push all designs"
+        task :all => dirs_in_path(base_path)
+      end
+    end
+  end
+
+  # Injects tasks to create and delete databases
+  def self.inject_database_tasks(base_path)
+    namespace :throne do
+      desc "Creates a database if it doesn't exist"
+      task :createdb, :db do |t, args|
+        get_db(args).create_database
+        puts "Database at #{url(args.db)}"
+      end
+
+      desc "Deletes a database"
+      task :deletedb, :db do |t, args|
+        get_db(args).delete_database
+        puts "Database at #{url(args.db)}"
+      end
+
+      desc "Deletes, creates and re-loads a database"
+      task :rebuilddb, :db do |t, args|
+        db = get_db(args)
+        raise "you must specify the database name (task[db])" unless args.db
+        db.delete_database
+        # re-getting the object will create the DB
+        db = get_db(args)
+        # load design docs
+        load_design_documents(db.url, File.join(base_path, 'design', args.db))
+        # load data
+        load_data_for_database(db.url, File.join(base_path, 'data', args.db))
+        puts "Done."
+      end
+
+
+      def self.get_db(args)
+        args ? db = args.db : db = nil
+        unless (ENV['SERVER_URL'] && args.db) || ENV['DB_URL']
+          raise "You must specify DB_URL or task[db_name] and SERVER_URL"
+        end
+        Throne::Database.new(url(db))
       end
     end
   end
 
+  # Injects all tasks. Related data files will be stores in base_path/data, and 
+  # design docs in base_path/design
+  #
+  # @param [String] base_path path for db related files.
+  def self.inject_all_tasks(base_path)
+    inject_data_tasks(File.join(base_path, 'data'))
+    inject_design_doc_tasks(File.join(base_path, 'design'))
+    inject_database_tasks(base_path)
+  end
+
+  # Loads design documents into the database url, extracted from the source path
+  # The docs should be layed out in the following format:
+  # base_path/
+  # |-- <db name>
+  #      `-- <design doc name>
+  #          |-- lists
+  #          |   `-- statuses
+  #          |       `-- list.js
+  #          `-- views
+  #              `-- statuses
+  #                  |-- map.js
+  #                  `-- reduce.js 
+  # @param [String] db_url the url of the database to load the data in to
+  # @param [String] source_path the path to search for .yml and .json files
+  def self.load_design_documents(db_url, source_path)
+    # for each folder in base path, create a new design doc key
+    # create a lists key
+    # for each path in lists, add a key with the folder name
+    # inside this, there is a key called list, with the contents of the list function
+    # views is the same, except with a map and reduce function
+    Dir.glob(File.join(source_path, '*')).each do |doc_path|
+      doc_name = File.basename(doc_path)
+      doc = {'lists' => {}, 'views' => {}}
+      Dir.glob(File.join(doc_path, 'lists', '*')) do |list_path|
+        list_name = File.basename(list_path)
+        doc['lists'][list_name] = {}
+        listfn = File.join(list_path, 'list.js')
+        doc['lists'][list_name] = 
+            File.read(listfn) if File.exists?(listfn)
+      end
+      Dir.glob(File.join(doc_path, 'views', '*')) do |view_path|
+        view_name = File.basename(view_path)
+        doc['views'][view_name] = {}
+        mapfn = File.join(view_path, 'map.js')
+        reducefn = File.join(view_path, 'reduce.js')
+        doc['views'][view_name]['map'] =
+            File.read(mapfn) if File.exists?(mapfn)
+        doc['views'][view_name]['reduce'] =
+            File.read(reducefn) if File.exists?(reducefn)
+      end
+      # try to get the existing doc
+      doc_id = "_design/#{doc_name}"
+      db = Throne::Database.new(db_url)
+      if svr_doc = db.get(doc_id)
+        # merge
+        doc = svr_doc.merge(doc)
+      else
+        doc['_id'] = doc_id
+      end
+      doc['language'] = 'javascript'
+      db.save(doc)
+      puts "Design documents from #{source_path} loaded"
+    end
+    
+    # try and get a document with the design name
+    # if it's there, replace the lists and views keys with above data
+    # otherwise, create a new document, set language to javascript
+    # put document.
+    # WIN 
+  end
+
+  # Loads data into the database url from the source path. Picks up .yml and .json
+  # @param [String] db_url the url of the database to load the data in to
+  # @param [String] source_path the path to search for .yml and .json files
+  def self.load_data_for_database(db_url, source_path)
+    @db = Throne::Database.new(db_url)
+    items = []
+    doccount = 0
+    # grab and parse all YML files
+    Dir.glob(source_path + '/**/*.yml').each do |yml|
+      items << YAML::load(File.open(yml))
+    end
+    # and json
+    Dir.glob(source_path + '/**/*.json').each do |json|
+      items << JSON.parse(File.open(json).read)
+    end
+    # load em up
+    items.each do |item|
+      if item.kind_of? Array
+        item.each do |doc|
+          begin
+            @db.save(doc)
+          rescue RestClient::RequestFailed => e
+            if e.message =~ /409$/
+              puts "Duplicate document - this data has probaby already been loaded"
+              doccount -= 1
+            else
+              raise e
+            end
+          end
+          doccount += 1
+        end
+      elsif item.kind_of? Hash
+        begin
+          @db.save(item)
+        rescue RestClient::RequestFailed => e
+          if e.message =~ /409$/
+            puts "Duplicate document - this data has probaby already been loaded"
+            doccount -= 1
+          else
+            raise e
+          end
+        end
+        doccount += 1
+      else
+        puts "There is something funky with the data for #{source_path}"
+      end
+      puts "#{doccount} document(s) loaded into database at #{@db.url}"
+    end
+  end
+
+  def self.dump_docs_from_db(db, base_path, format)
+    raise "You must specify a DB name to dump task[dbname]" unless db
+    outdir = File.join(base_path, db)
+    Dir.mkdir(outdir) unless File.exists?(outdir)
+    @db = Throne::Database.new(url(db))
+    docs = []
+
+    @db.function('_all_docs') do |res|
+      docs << @db.get(res['key']) unless res['key'].match(/^_/)
+    end
+
+    outfn = format == :json ? 'dump.json' : 'dump.yml'
+    File.open(File.join(outdir, outfn), 'w') do |f| 
+      if format == :json
+        f.puts docs.to_json
+      elsif format == :yml
+        f.puts docs.to_yaml
+      else
+        raise("Internal Error - invalid dump format specified")
+      end
+    end
+    puts "Data dumped to #{base_path + '/' + db + '/' + outfn}"
+  end
+
   private
 
   def self.dirs_in_path(path)
@@ -63,7 +265,8 @@ class Throne::Tasks
     elsif svrurl = ENV['SERVER_URL']
       return svrurl + '/' + dbname
     else
-      raise("You must provide a SERVER_URL or DATABASE_URL")
+      raise("You must provide a SERVER_URL or DB_URL")
     end
   end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: throne
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Lincoln Stoll
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-13 00:00:00 +11:00
+date: 2009-12-14 00:00:00 +11:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -60,14 +60,15 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.md
+- README.rdoc
+- TODO
 files: 
 - .document
 - .gitignore
-- FEATURES
 - LICENSE
-- README.md
+- README.rdoc
 - Rakefile
+- TODO
 - VERSION
 - lib/throne.rb
 - lib/throne/database.rb

data/FEATURES

@@ -1,5 +0,0 @@
-* Ability to load views from disk
-* Query these views from an object
-* Map the views to a hash structure, or just an array
-* At the top level retrieved, look for a RubyType field, and cast
-* vague AR methods (Create, save, hooks)