zemanta 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+test_file.*

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--drb

data/.rvmrc

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional.
+environment_id="ruby-1.9.2-p180@zemanta"
+
+#
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficicent compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+#
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments" \
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]] ; then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+
+  [[ -s ".rvm/hooks/after_use" ]] && . ".rvm/hooks/after_use"
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  rvm --create  "$environment_id"
+fi
+
+#
+# If you use an RVM gemset file to install a list of gems (*.gems), you can have
+# it be automatically loaded. Uncomment the following and adjust the filename if
+# necessary.
+#
+# filename=".gems"
+# if [[ -s "$filename" ]] ; then
+#   rvm gemset import "$filename" | grep -v already | grep -v listed | grep -v complete | sed '/^$/d'
+# fi
+
+#
+# If you use bundler and would like to run bundle each time you enter the
+# directory, you can uncomment the following code.
+#
+#   # Ensure that Bundler is installed. Install it if it is not.
+#   if ! command -v bundle >/dev/null; then
+#      printf "The rubygem 'bundler' is not installed. Installing it now.\n"
+#      gem install bundler
+#   fi
+#
+#   # Bundle while reducing excess noise.
+#   printf "Bundling your gems. This may take a few minutes on a fresh clone.\n"
+#   bundle | grep -v '^Using ' | grep -v ' is complete' | sed '/^$/d'
+#
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in zemanta.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,19 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  # watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  # watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  # watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", # "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  # watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  # watch('config/routes.rb')                           { "spec/routing" }
+  # watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+  # # Capybara request specs
+  # watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/requests/#{m[1]}_spec.rb" }
+end
+

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Oto Brglez
+
+MIT License
+
+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.

data/README.md

@@ -0,0 +1,122 @@
+# Ruby client for Zemanta
+
+This Gem provides Ruby client and comand-line tool for Zemanta API.
+
+## Requirements
+
+To use this client you must gain API key.
+You can get API key on http://developer.zemanta.com
+
+## Installation
+
+Add this line to your Gemfile
+	
+	gem 'zemanta'
+
+Or install it as seperate gem
+
+	$ gem install zemanta
+
+## Using Zemanta from comand-line
+
+After installing the Gem create file ~/.zemanta with API key.
+
+	ZEMANTA_KEY="xxx"
+
+For comand-line usage use command -h. You will get following output...
+
+	Usage: zemanta COMMAND [options]
+
+	Commands
+		suggest: Suggest method allows to query Zemanta for contextual metadata about a given text.
+	Options
+	    -h, --help                       help
+	    -a, --api_key NEW_KEY            Zemanta api_key
+	    -t, --text TEXT                  Text to work on
+	    -f, --file FILE                  File to work on
+	    -m, --mtype TYPE                 Output type (JSON or RB)
+	    -r, --result_field FIELD         Result field
+
+Usage example would be...
+
+	zemanta suggest -f test_file.txt -r articles -m json
+
+## Using Zemanta in your Ruby application
+
+You can use client from your Ruby code or from comand-line.
+
+### Configuration
+
+Zemanta API requires API key, so to use this client you also have to set the key. You can do this like so...
+
+	zemanta = Zemanta.new "API_KEY_GOES_HERE"
+
+Or if you like class wide key...
+
+	Zemanta.api_key = "API_KEY_GOES_HERE"
+
+The 3rd option is to set enviroment variable "ZEMANTA_KEY" and client will pick it up.
+
+### Suggests with #suggest method
+
+Zemanta API provides 3 methods; and so does this client.
+You can use suggest method like so...
+
+	suggests = Zemanta.new.suggest("My long text goes here...")
+
+	suggests['articles'] 	# All the suggested articles
+	suggests['images'] 		# All suggested images
+	...
+
+For more information and structure look at this #suggest resource.
+
+http://developer.zemanta.com/docs/suggest/
+
+### Suggests with #suggest_markup
+
+In comparison to #zemanta_suggest, this method returns only links to semantical entities.
+
+	suggests = Zemanta.new.suggest_markup("My long text goes here...")
+	suggests['markup']
+
+For more information about this response see suggest_markup method documentation.
+
+http://developer.zemanta.com/docs/suggest_markup/
+
+### #preferences method
+
+Method #preferences allows Zemanta API users to get preferences of specific user. 
+
+	me = Zemanta.new.preferences
+	me['user']	# Get nice key...
+
+### Client options
+
+Zemanta API methods also provide some additional options. You can use them like so:
+
+	suggests = z.suggest("
+		Some text here...
+	",{
+		return_images: 0,	# Don't return any images.
+		articles_limit: 2 	# Limit of articles returned
+	})
+
+For more options please read:
+http://developer.zemanta.com/docs/suggest/
+
+## Limits
+
+Your daily limit is set at 1.000 calls per day. Send email to support@zemanta.com to make it 10.000 calls per day.
+
+## Testing and developement
+
+Client is tested/build with RSpec with help of Guard, but it does NOT use mockups or anything like that. For testing and developement you must get your own Zemanta API Key.
+
+## About
+
+This is unofficial client and comes without any warranty. Please
+read and use documentation provided by Zemanta.
+
+## Contribution and authors
+
+Oto Brglez / @otobrglez / <oto.brglez@opalab.com>

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/bin/zemanta

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'zemanta'
+require 'pp'
+
+# Read content of ~/.zemanta or die.
+def read_key_from_zemanta_rc path=nil
+	path = "#{ENV['HOME']}/.zemanta" if path.nil?
+	unless File.exist? path
+		puts "Please create \"#{path}\" with content: "
+		puts "ZEMANTA_KEY=\"your_key_here\""
+		exit(1)
+	end
+	eval(File.read(path))
+	return ZEMANTA_KEY
+end
+
+api_key = ENV["ZEMANTA_KEY"]
+api_key = read_key_from_zemanta_rc if api_key.nil? or api_key.strip==""
+
+options = {
+	output_type: "RB"
+}
+
+parser = OptionParser.new do |opt|
+	opt.banner = "Usage: zemanta COMMAND [options]"
+	opt.separator ""
+	opt.separator "Commands"
+	opt.separator "	suggest: Suggest method allows to query Zemanta for contextual metadata about a given text."
+
+	# opt.separator "	suggest_markup: In comparison to suggest, this method returns only links to semantical entities."
+
+	opt.separator "Options"
+	opt.on("-h","--help","help") do
+    	puts parser
+  	end
+
+  	opt.on("-a","--api_key NEW_KEY","Zemanta api_key") do |a|
+  		api_key=a
+  	end
+
+  	opt.on("-t","--text TEXT","Text to work on") do |t|
+  		options[:text] = t
+  	end
+
+  	opt.on("-f","--file FILE","File to work on") do |t|
+  		if File.exist? t
+  			options[:text] = File.read(t)
+  		else
+  			puts "Can't read file: #{t}"
+  			exit(1)
+  		end
+  	end
+
+  	opt.on("-m","--mtype TYPE","Output type (JSON or RB)") do |t|
+  		allowed = %w(JSON RB)
+  		if allowed.include?t.upcase
+  			options[:output_type] = t.upcase
+  		else
+  			puts "Alowed output types: " + allowed.join(", ")
+  			exit(1)
+  		end
+  	end
+
+  	opt.on("-r","--result_field FIELD","Result field") do |o|
+  		options[:result_field] = o.split(",").map(&:strip).first
+  	end
+end
+
+# Dirty/ugly hack!!! 
+if not(ARGV[1].nil?) and ARGV[1][0] != "-"
+	options[:text] = ARGV[1]
+end
+
+parser.parse!
+
+##### The thing ######
+
+def output response, options
+	if options[:output_type] =~ /json/i
+		puts response.to_json
+	else
+		pp response
+	end
+end
+
+z = Zemanta.new(api_key)
+
+case ARGV[0]
+when "suggest"
+	suggests = z.suggest(options[:text], options)
+	if options[:result_field].nil?
+		output(suggests,options)
+	else
+		output(suggests[ (options[:result_field]) ],options)
+	end
+#else
+#	puts "\"#{ARGV[0]}\" is not implemented in comand-line yet!!!"
+else
+	parser
+end

data/lib/zemanta/version.rb

@@ -0,0 +1,3 @@
+class Zemanta
+  VERSION = "0.0.1"
+end

data/lib/zemanta.rb

@@ -0,0 +1,65 @@
+require "zemanta/version"
+require "httparty"
+
+class Zemanta
+	include HTTParty
+	base_uri 'http://api.zemanta.com'
+
+	# api_key for Zemanta
+	@@api_key=nil
+	def self.api_key=(key); @@api_key=key end
+	def self.api_key; @@api_key end
+	def api_key; Zemanta.api_key end
+
+	# Initialize the client
+	def initialize(api_key=nil)
+		@@api_key = api_key unless api_key.nil?
+		@@api_key = ENV["ZEMANTA_KEY"] if @@api_key.nil? and not(ENV["ZEMANTA_KEY"].nil?)
+	end
+
+	# Provide contextual metadata about text
+	# See: http://developer.zemanta.com/docs/suggest/
+	def suggest text, options={}
+		get("suggest",options.merge!({
+			text: text
+		}))
+	end
+
+	# Suggest method allows developers to query Zemanta
+	# for contextual metadata on a given text.
+	# In comparison to zemanta.suggest, this method returns
+	# only links to semantical entities.
+	def suggest_markup text, options={}
+		get("suggest_markup",options.merge!({
+			text: text
+		}))
+	end
+
+	# Get preferences of specific user. 
+	def preferences options={}
+		get("preferences",options)
+	end
+
+	# Get REST service with JSON response
+	def get(method,options)
+		options.merge!({
+			method: "zemanta.#{method}",
+			api_key: @@api_key,
+			format: "json"})
+
+		handle_response(
+			self.class.get('/services/rest/0.0/',query:options),
+		options)
+	end
+
+	# Handle response from service
+	def handle_response response, options={}
+		unless response['status'] =~ /ok/
+			msg = response.parsed_response.match("<h1>(.+?)</h1>")[1]
+			msg = "Error." if msg.nil?
+			throw "Zemanta: %s" % msg
+		end
+
+		response
+	end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require "rubygems"
+require "bundler/setup"
+
+require "zemanta"
+
+RSpec.configure do |config|
+
+end

data/spec/zemanta_spec.rb

@@ -0,0 +1,99 @@
+require "spec_helper"
+
+describe Zemanta do
+	it "should respond to #VERSION" do
+		Zemanta::VERSION.should_not be_nil
+	end
+
+	it "can use ENV variable for api_key" do
+		ENV["ZEMANTA_KEY"].should_not be_nil
+	end
+
+	it "has some methods" do
+		client = Zemanta.new ENV["ZEMANTA_KEY"]
+		client.should respond_to :suggest
+		client.should respond_to :suggest_markup
+		client.should respond_to :preferences
+	end
+
+	context "Initialization process" do
+		it "has api_key from ENV" do
+			Zemanta.api_key.should == ENV["ZEMANTA_KEY"]
+		end
+		
+		it "should break if no #api_key is present" do
+			client = Zemanta.new "AAA"
+			client.api_key.should == "AAA"
+
+			Zemanta.api_key = "BBB"
+			Zemanta.api_key.should == "BBB"
+			client_2 = Zemanta.new
+			client_2.api_key.should == "BBB"
+		end
+
+		it "should break on fake api_key" do
+			client = Zemanta.new("FAKE")
+			expect{
+				suggests = client.suggest("fake it till u make it...")
+			}.to raise_error
+		end
+	end
+
+	context "#suggest method" do
+		let(:z){ Zemanta.new(ENV["ZEMANTA_KEY"]) }
+
+		it "can #suggest to some text" do
+			suggests = z.suggest("
+				The Phoenix Mars Lander has successfully deployed its robotic arm and
+				tested other instruments including a laser designed to detect dust,
+				clouds, and fog. 
+			")
+
+			suggests['articles'].should_not be_nil
+			suggests['images'].should_not be_nil
+			suggests['markup'].should_not be_nil
+			suggests['signature'].should_not be_nil
+			suggests['keywords'].should_not be_nil
+			suggests['rid'].should_not be_nil
+			suggests['categories'].should_not be_nil
+			suggests['rich_objects'].should_not be_nil
+		end
+
+		it "can do some additional #attributes" do
+			suggests = z.suggest("
+				Ronald Reagan je bil 40. predsednik ZDA v letih 1981-1989 in 33. guverner drzave Kalifornija v letih 1967-1975.
+				Pred vstopom v politiko je bil Reagan tudi napovedovalec, filmski igralec in predsednik Ameriskega zdruzenja igralcev.
+			",{
+				return_images: 0,
+				articles_limit: 2
+			})
+
+			suggests['articles'].size.should == 2
+			suggests['images'].should be_nil
+		end
+	end
+
+	context "#suggest_markup" do
+		let(:z){ Zemanta.new(ENV["ZEMANTA_KEY"]) }
+		it "can #suggest_markup to some text" do
+			suggests = z.suggest_markup "
+				The Phoenix Mars Lander has successfully deployed its robotic arm and
+tested other instruments including a laser designed to detect dust,
+clouds, and fog. The arm will be used to dig up samples of the Martian
+surface which will be analyzed as a possible habitat for life.
+			"
+
+			suggests["markup"].should_not be_nil
+			suggests["markup"]["text"].should_not be_nil
+		end
+	end
+
+	context "#preferences" do
+		let(:z){ Zemanta.new(ENV["ZEMANTA_KEY"]) }
+		it "can have #preferences" do
+			z.should respond_to :preferences
+			prefs = z.preferences
+			prefs["user"].should_not be_nil
+		end
+	end
+end

data/zemanta.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/zemanta/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Oto Brglez"]
+  gem.email         = ["otobrglez@gmail.com"]
+  gem.description   = %q{Ruby client for Zemanta}
+  gem.summary       = %q{This GEM provides Ruby client and comand-line tool for Zemanta API.}
+  gem.homepage      = "https://github.com/otobrglez/zemanta"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "zemanta"
+  gem.require_paths = ["lib"]
+  gem.version       = Zemanta::VERSION
+
+  gem.has_rdoc      = false
+
+  gem.add_dependency "httparty"
+  # gem.add_dependency "nokogiri"
+
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'guard'
+  gem.add_development_dependency 'guard-rspec'
+  gem.add_development_dependency 'growl'
+  gem.add_development_dependency 'spork', '~> 1.0rc'
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification 
+name: zemanta
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Oto Brglez
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-06-12 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rake
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: guard
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: guard-rspec
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: growl
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: spork
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0rc
+  type: :development
+  prerelease: false
+  version_requirements: *id007
+description: Ruby client for Zemanta
+email: 
+- otobrglez@gmail.com
+executables: 
+- zemanta
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- .rvmrc
+- Gemfile
+- Guardfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/zemanta
+- lib/zemanta.rb
+- lib/zemanta/version.rb
+- spec/spec_helper.rb
+- spec/zemanta_spec.rb
+- zemanta.gemspec
+homepage: https://github.com/otobrglez/zemanta
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -4004596336368350971
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -4004596336368350971
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.12
+signing_key: 
+specification_version: 3
+summary: This GEM provides Ruby client and comand-line tool for Zemanta API.
+test_files: 
+- spec/spec_helper.rb
+- spec/zemanta_spec.rb