relaxo 0.1.0 → 0.3.0

data/README.md

@@ -2,14 +2,88 @@ Relaxo
 ======
 
 * Author: Samuel G. D. Williams (<http://www.oriontransfer.co.nz>)
-* Copyright (C) 2010, 2011 Samuel G. D. Williams.
+* Copyright (C) 2012 Samuel G. D. Williams.
 * Released under the MIT license.
 
-Relaxo is a simple gem to assist with loading CouchDB data from YAML files.
+Relaxo provides a set of tools and interfaces for interacting with CouchDB. It aims to be as simple and efficient as possible while still improving the usability of various CouchDB features.
+
+Installation
+------------
+
+Install the ruby gem as follows:
+
+	sudo gem install relaxo
+
+To build and install the gem from source:
+
+	cd build/
+	sudo GEM=gem1.9 rake1.9 install_gem
+
+Basic Usage
+-----------
+
+Connect to a local database and manipulate some documents.
+
+	require 'relaxo'
+	
+	$database = Relaxo.connect("http://localhost:5984/test")
+	
+	doc1 = {:bob => 'dole'}
+	$database.save(doc1)
+	
+	doc2 = $database.get(doc1['_id'])
+	doc2[:foo] = 'bar'
+	$database.save(doc2)
+
+Bulk Changes/Sessions
+---------------------
+
+Sessions support a very similar interface to the main database class and can for many cases be used interchangeably, but with added efficiency.
+
+	require 'relaxo'
+	require 'relaxo/session'
+	
+	$database = Relaxo.connect("http://localhost:5984/test")
+	
+	$animals = ['Neko-san', 'Wan-chan', 'Nezu-chan', 'Chicken-san']
+	
+	$database.session do |session|
+		$animals.each do |animal|
+			session.save({:name => animal})
+		end
+	end
+	# => [
+	#	{:name=>"Neko-san", "_id"=>"...", "_rev"=>"..."},
+	#	{:name=>"Wan-chan", "_id"=>"...", "_rev"=>"..."},
+	#	{:name=>"Nezu-chan", "_id"=>"...", "_rev"=>"..."},
+	#	{:name=>"Chicken-san", "_id"=>"...", "_rev"=>"..."}
+	#]
+
+All documents will allocated uuids appropriately and at the end of the session block they will be updated (saved or deleted)
+using CouchDB `_bulk_save`.
+
+To abort the session, either raise an exception or call `session.abort!` which is equivalent to `throw :abort`.
+
+Loading Data
+------------
+
+Relaxo includes a command line script to import documents into a CouchDB database:
 
 	relaxo http://localhost:5984/test design.yaml sample.yaml
 
-Where `design.yaml` and `sample.yaml` contain lists of valid documents.
+Where `design.yaml` and `sample.yaml` contain lists of valid documents, e.g.:
+
+	# design.yaml
+	-   _id: "_design/services"
+	    language: javascript
+	    views:
+	        service:
+	            map: |
+	                function(doc) {
+	                    if (doc.type == 'service') {
+	                        emit(doc._id, doc._rev);
+	                    }
+	                }
 
 License
 -------

data/bin/relaxo

@@ -1,13 +1,21 @@
 #!/usr/bin/env ruby
 
-require 'couchrest'
+require 'relaxo'
 require 'yaml'
 
 OPTIONS = {
 	:existing => :merge
 }
 
-$db = CouchRest.database!(ARGV.shift)
+if ARGV.delete('--merge')
+	OPTIONS[:existing] = :merge
+elsif ARGV.delete('--replace')
+	OPTIONS[:existing] = :replace
+elsif ARGV.delete('--update')
+	OPTIONS[:existing] = :update
+end
+
+$database = Relaxo.connect(ARGV.shift)
 $documents = YAML::load(ARGF)
 
 unless Array === $documents
@@ -25,15 +33,15 @@ $documents.each do |document|
 		$stderr.puts "Loading #{document.inspect}"
 		existing_document = nil
 		
-		if document && document['_id']
-			existing_document = $db.get(document['_id'])
+		if document && document[Relaxo::ID]
+			existing_document = $database.get(document[Relaxo::ID]) rescue nil
 		end
 		
 		if existing_document
 			if OPTIONS[:existing] == :replace
 				$stderr.puts "Replacing existing document..."
 				# The document is replaced entirely with the incoming data.
-				document['_rev'] = existing_document['_rev']
+				document[Relaxo::REV] = existing_document[Relaxo::REV]
 			elsif OPTIONS[:existing] == :update
 				$stderr.puts "Updating existing document..."
 				# Values in `existing_document` take priority
@@ -42,13 +50,13 @@ $documents.each do |document|
 				$stderr.puts "Merging existing document..."
 				# Values in `document` take priority, except for `_rev`.
 				document.update(existing_document) do |key, oldval, newval|
-					key == '_rev' ? newval : oldval
+					key == Relaxo::REV ? newval : oldval
 				end
 			end
 		end
 		
 		$stderr.puts "Saving #{document.inspect}"
-		$result = $db.save_doc(document)
+		$result = $database.save(document)
 		
 		$stats[:saved] += 1
 	rescue RestClient::BadRequest => ex

data/lib/relaxo/client.rb

@@ -0,0 +1,118 @@
+# Copyright (c) 2012 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'json'
+require 'rest_client'
+require 'cgi'
+
+module Relaxo
+	module Client
+		@@debug = false
+		
+		def self.debug= flag
+			@@debug = flag
+		end
+		
+		DEFAULT_GET_HEADERS = {:accept => :json}
+		DEFAULT_PUT_HEADERS = {:accept => :json, :content_type => :json}
+		
+		def self.execute(request)
+			# Poor mans debugging:
+			$stderr.puts "Client: #{request[:method]} #{request[:url]}" if @@debug
+			
+			response = RestClient::Request.execute(request)
+			return JSON.parse(response)
+		end
+		
+		def self.get(url)
+			execute({
+				:method => :get,
+				:url => url,
+				:headers => DEFAULT_GET_HEADERS
+			})
+		end
+		
+		def self.head(url)
+			execute({
+				:method => :head,
+				:url => url,
+				:headers => DEFAULT_GET_HEADERS
+			})
+		end
+		
+		def self.put(url, document)
+			execute({
+				:method => :put,
+				:url => url,
+				:headers => DEFAULT_PUT_HEADERS,
+				:payload => JSON.generate(document)
+			})
+		end
+		
+		def self.post(url, document)
+			execute({
+				:method => :post,
+				:url => url,
+				:headers => DEFAULT_PUT_HEADERS,
+				:payload => JSON.generate(document)
+			})
+		end
+		
+		def self.delete(url)
+			execute({
+				:method => :delete,
+				:url => url,
+				:headers => DEFAULT_PUT_HEADERS
+			})
+		end
+		
+		def self.escape(component)
+			return CGI.escape(component)
+		end
+		
+		def self.encode_parameters(parameters)
+			query = []
+			
+			parameters.each do |key, value|
+				key_string = key.to_s
+				
+				if Symbol === value || key_string.end_with?("docid")
+					query << escape(key_string) + '=' + escape(value.to_s)
+				else
+					query << escape(key_string) + '=' + escape(value.to_json)
+				end
+			end
+			
+			return '?' + query.join('&')
+		end
+		
+		def self.encode_url(url, parameters = {})
+			if parameters.empty?
+				url
+			else
+				url + encode_parameters(parameters)
+			end
+		end
+		
+		def self.escape_id(id)
+			/^_design\/(.*)/ =~ id ? "_design/#{escape($1)}" : escape(id)
+		end
+	end
+end

data/lib/relaxo/database.rb

@@ -0,0 +1,182 @@
+# Copyright (c) 2012 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'relaxo/client'
+require 'relaxo/server'
+
+module Relaxo
+	
+	ID = '_id'
+	REV = '_rev'
+	ATTACHMENTS = '_attachments'
+	
+	def self.encode_attachments!(document)
+		return unless document[ATTACHMENTS]
+		
+		document[ATTACHMENTS].each do |name,contents|
+			next if contents['stub']
+			
+			contents['data'] = Base64.encode64(contents['data'])
+		end
+	end
+	
+	class Session
+		def initialize(database)
+			@database = database
+			
+			@documents = []
+			@uuids = []
+		end
+		
+		def get(*args)
+			@database.get(*args)
+		end
+		
+		def delete(document)
+			@documents << {:_deleted => true}.merge(document)
+		end
+		
+		def save(document)
+			Relaxo::encode_attachments!(document)
+			
+			@documents << document
+			
+			# We assume the save operation will be successful:
+			unless document.key? ID
+				@uuids << (document[ID] = @database.server.next_uuid)
+			end
+		end
+		
+		def session(klass)
+			yield self
+			
+			klass.new(self, @documents.last)
+		end
+		
+		def view(*args)
+			@database.view(*args)
+		end
+		
+		def commit!
+			#puts "Commiting session:"
+			#puts YAML::dump(@documents)
+			
+			changed = []
+			
+			unless @documents.empty?
+				results = @database.bulk_save @documents
+				
+				# Update the documents with revision information:
+				@documents.each_with_index do |document, index|
+					status = results[index]
+					
+					if status['ok']
+						document[ID] = status['id']
+						document[REV] = status['rev']
+					end
+				end
+				
+				changed = @documents
+				@documents = []
+			end
+			
+			return changed
+		end
+		
+		#def rollback!
+			# Restore all documents based on @uuids
+		#end
+	end
+	
+	class Database
+		def initialize(server, name)
+			@server = server
+			@name = name
+			
+			@root = server.url + "/" + CGI.escape(name)
+		end
+		
+		attr :server
+		attr :name
+		attr :root
+		
+		def get(id, parameters = {})
+			Client.get document_url(id, parameters)
+		end
+		
+		def put(document)
+			Client.put document_url(document[ID] || @server.next_uuid), document
+		end
+		
+		def delete(document)
+			Client.delete document_url(document[ID]) + "?rev=#{document[REV]}"
+		end
+		
+		def save(document)
+			Relaxo::encode_attachments!(document)
+			
+			status = put(document)
+			
+			if status['ok']
+				document[ID] = status['id']
+				document[REV] = status['rev']
+			end
+			
+			return status
+		end
+		
+		def bulk_save(documents)
+			Client.post command_url("_bulk_docs"), {
+				:docs => documents,
+				:all_or_nothing => true
+			}
+		end
+		
+		# Accepts paramaters as described in http://wiki.apache.org/couchdb/HttpViewApi
+		def view(name, parameters = {})
+			Client.get view_url(name, parameters)
+		end
+		
+		def info
+			Client.get @root
+		end
+		
+		def documents(parameters = {})
+			view("_all_docs", parameters)
+		end
+		
+		private
+		
+		# Convert a simplified view name into a complete view path. If the name already starts with a "_" no alterations will be made.
+		def view_url(name, parameters = {})
+			path = (name =~ /^([^_].+?)\/(.*)$/ ? "_design/#{$1}/_view/#{$2}" : name)
+			
+			Client.encode_url("#{@root}/#{path}", parameters)
+		end
+		
+		def document_url(id, parameters = {})
+			Client.encode_url("#{@root}/#{Client.escape_id(id)}", parameters)
+		end
+		
+		def command_url(command, parameters = {})
+			Client.encode_url("#{@root}/#{command}", parameters)
+		end
+	end
+end

data/lib/relaxo/server.rb

@@ -0,0 +1,48 @@
+# Copyright (c) 2012 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'relaxo/client'
+
+module Relaxo
+	class Server
+		DEFAULT_UUID_FETCH_COUNT = 10
+		
+		def initialize(url)
+			@url = url
+			@uuids = []
+		end
+		
+		attr :url
+		
+		def fetch_uuids(count)
+			@uuids += Client.get("#{@url}/_uuids?count=#{count}")["uuids"]
+		end
+		
+		def next_uuid
+			fetch_uuids(DEFAULT_UUID_FETCH_COUNT) if @uuids.size == 0
+			
+			@uuids.pop
+		end
+		
+		def info
+			Client.get @url
+		end
+	end
+end

data/lib/relaxo/session.rb

@@ -0,0 +1,116 @@
+# Copyright (c) 2012 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'relaxo/client'
+require 'relaxo/server'
+
+module Relaxo
+	
+	# We monkey-patch this in as Session is basically an optional feature for doing bulk_saves.
+	class Database
+		def session(klass = nil)
+			session = Session.new(self)
+			
+			catch(:abort) do
+				yield session
+				
+				changed = session.commit!
+				
+				if klass
+					klass.new(self, changed.last)
+				else
+					changed
+				end
+			end
+		end
+	end
+	
+	class Session
+		def initialize(database)
+			@database = database
+			
+			@documents = []
+			@uuids = []
+		end
+		
+		def get(*args)
+			@database.get(*args)
+		end
+		
+		def delete(document)
+			@documents << {:_deleted => true}.merge(document)
+		end
+		
+		def save(document)
+			Relaxo::encode_attachments!(document)
+			
+			@documents << document
+			
+			# We assume the save operation will be successful:
+			unless document.key? ID
+				@uuids << (document[ID] = @database.server.next_uuid)
+			end
+		end
+		
+		def session(klass)
+			yield self
+			
+			klass.new(self, @documents.last)
+		end
+		
+		def view(*args)
+			@database.view(*args)
+		end
+		
+		def commit!
+			#puts "Commiting session:"
+			#puts YAML::dump(@documents)
+			
+			changed = []
+			
+			unless @documents.empty?
+				results = @database.bulk_save @documents
+				
+				# Update the documents with revision information:
+				@documents.each_with_index do |document, index|
+					status = results[index]
+					
+					if status['ok']
+						document[ID] = status['id']
+						document[REV] = status['rev']
+					end
+				end
+				
+				changed = @documents
+				@documents = []
+			end
+			
+			return changed
+		end
+		
+		def abort!
+			throw :abort
+		end
+		
+		#def rollback!
+			# Restore all documents based on @uuids
+		#end
+	end
+end

data/lib/relaxo/version.rb

@@ -21,7 +21,7 @@
 module Relaxo
   module VERSION
     MAJOR = 0
-    MINOR = 1
+    MINOR = 3
     TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')

data/lib/relaxo.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2012 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'relaxo/database'
+
+module Relaxo
+	def self.connect(url)
+		host = "http://localhost:5984"
+		
+		if url =~ /^(https?:\/\/.+?)\/(.+)$/
+			host = $1
+			name = $2
+		else
+			name = url
+		end
+		
+		server = Server.new(host)
+		database = Database.new(server, name)
+	end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: relaxo
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,24 +9,40 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-09 00:00:00.000000000 Z
+date: 2012-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: couchrest
+  name: json
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.7.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.7.3
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.6.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.6.7
 description: 
 email: samuel.williams@oriontransfer.co.nz
 executables:
@@ -35,6 +51,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - bin/relaxo
+- lib/relaxo/client.rb
+- lib/relaxo/database.rb
+- lib/relaxo/server.rb
+- lib/relaxo/session.rb
 - lib/relaxo/version.rb
 - lib/relaxo.rb
 - README.md