iterationlabs-online_parselets 0.1.0

data/README

@@ -0,0 +1,33 @@
+The online_parselets project is a client gem to talk to http://parselets.com.
+
+REQUIREMENTS
+
+	This gem supports both local and server-side parselet execution.  In general, 
+	however, you should have the parsley gem installed for fast, local parsing.
+	Get it here: http://github.com/fizx/parsley-ruby/tree/master
+
+INSTALL
+
+From GitHub:
+  Run the following if you haven't already:
+  gem sources -a http://gems.github.com
+  Install the gem:
+  sudo gem install iterationlabs-online_parselets
+
+From source:
+  sudo rake install
+
+USAGE
+
+	require "rubygems"
+	require "online_parselets"
+	client = OnlineParselets::Client.new(:api_key => "your_api_key")
+	parselets = @client.find("yelp")
+	parselet = parselets.first
+	yelp_data = parselet.parse(:url => "http://www.yelp.com")
+	puts yelp_data.inspect
+	# Reload a parselet from the server
+	parselet = client.parselet(parselet.server_id)
+	# Or:
+	parselet = client.parselet('my_parselet', version = 5)
+

data/lib/client.rb

@@ -0,0 +1,85 @@
+module OnlineParselets
+  # Client class to talk to the parselets.com server.
+  class Client
+    attr_accessor :api_key, :environment
+    HOST                  = { :production => "http://parselets.com", :local => "http://localhost:3000" }
+    SEARCH_PATH           = "/search/?q="
+    PARSELET_PATH         = "/parselets/"
+    RUN_ON_SERVER_PATH    = "/parse/"
+  
+    # Make a new client instance to talk to the parselets.com server.
+    #
+    # OnlineParselets::Client.new( :api_key => "your_api_key" )
+    def initialize(options = {})
+      self.api_key = options[:api_key] or raise InvalidAPIKey.new("You must provide an API key")
+      self.environment = options[:environment] || :production
+      raise InvalidEnvironmentError("Environment #{environment} is not defined") unless HOST[environment]
+    end
+  
+    # Search for parselets on the server.  Returns an array of matching OnlineParselets::Instance objects.
+    #
+    # matches = client.find("yelp")
+    def find(search_string)
+      results = OnlineParselets.catch_invalid_key do
+        JSON.parse(open(HOST[environment] + SEARCH_PATH + CGI::escape(search_string) + "&format=json&api_key=" + CGI::escape(api_key)).read)
+      end
+      results.map do |parselet|
+        Instance.new parselet['parselet'].merge( :client => self )
+      end
+    end
+    
+    # Retrieve a parselet by ID, or by name and version.  Returns nil or an Instance object.
+    #
+    # instance = client.parselet('my_parselet', 5)
+    # instance = client.parselet(17)
+    def parselet(parselet_id_or_name, parselet_version = nil)
+      result = OnlineParselets.catch_invalid_key do
+        if parselet_id_or_name.to_s =~ /\A\d+\Z/
+          unless parselet_version.nil?
+            raise Error.new("You cannot enter a version when looking up a specific parselet by id")
+          end
+        else
+          unless parselet_version.to_s =~ /\A\d+\Z/
+            raise Error.new("Version must be a number")
+          end
+          unless parselet_version.to_i > 0
+            raise Error.new("Version is 1 based, please use 1 as the first version")
+          end
+        end
+        
+        version = parselet_version ? "/#{parselet_version}" : ''
+        begin
+          fetch = open(HOST[environment] + PARSELET_PATH + CGI::escape(parselet_id_or_name.to_s) + version + "?format=json" + 
+                       "&api_key=" + CGI::escape(api_key))
+          JSON.parse(fetch.read)
+        rescue OpenURI::HTTPError => e
+          raise unless e.message == "404 Not Found"
+          nil
+        end
+      end
+      result && result['parselet'] && Instance.new(result['parselet'].merge( :client => self ))
+    end
+    
+  protected
+    
+    # Run a parselet by ID on the server.
+    #
+    # json = client.run_parselet_on_server(parselet_id = 17, :url => "http://www.example.com")
+    def run_parselet_on_server(server_id, options)
+      OnlineParselets.catch_invalid_key do
+        begin
+          url = options[:url] || options[:file]
+          unless url =~ /^http:\/\//i
+            raise InvalidServerSideParse.new("You must provide an http:// address to run this parselet on the server.")
+          end
+          fetch_url = "#{HOST[environment]}#{RUN_ON_SERVER_PATH}#{CGI::escape(server_id.to_s)}" + 
+                      "?format=json&api_key=#{CGI::escape(api_key)}&url=#{CGI::escape(url)}"
+          JSON.parse(open(fetch_url).read)
+        rescue OpenURI::HTTPError => e
+          raise unless e.message == "404 Not Found"
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/instance.rb

@@ -0,0 +1,68 @@
+require 'open-uri'
+
+module OnlineParselets
+  SERVER_SIDE_EXECUTION_WARNING = "WARNING: Please install the Parsley ruby gem, parselet execution via the server is slower, executed on cached web pages, and possibly rate-limited."
+  
+  # An OnlineParselets::Instance is a Parselet object with metadata and the ability to run locally or on the parselets.com server.
+  class Instance
+    attr_reader :name, :created_on_server_at, :code, :updated_on_server_at, :checked_on_server_at, 
+                :server_id, :pattern, :example_url, :user_id, :version_on_server, :description, :client
+
+    # Make a new instance of Instance, an object that combines a Parselet with metadata from the parselets.com server.
+    #
+    # This is mostly an internal method.
+    #
+    # instance = OnlineParselets::Instance.new(options)
+    def initialize(options = {})
+      options = options.inject({}) { |m, (k, v)| m[k.to_s] = v; m } # Turn symbols into strings.
+      @name                     = options['name']
+      @created_on_server_at     = options['created_at']
+      @code                     = options['code']
+      @updated_on_server_at     = options['updated_at']
+      @checked_on_server_at     = options['checked_at']
+      @server_id                = options['id']
+      @pattern                  = options['pattern']
+      @example_url              = options['example_url']
+      @user_id                  = options['user_id']
+      @version_on_server        = options['version']
+      @description              = options['description']
+      @client                   = options['client']
+    end
+    
+    # Run the parselet.
+    #
+    # instance.parse :url => "http://www.example.com"
+    #
+    # instance.parse :string => "<html><head>...</html>"
+    def parse(options)
+      if options[:parse_on_server].nil? && defined?(Parsley)
+        if options[:url]
+          string = open(options[:url]).read
+        end
+        parselet.parse({ :string => string }.merge(options))
+      else
+        parse_on_server(options)
+      end
+    end
+    
+    # Force an online parselet instance to run on the parselets.com server.
+    #
+    # instance.parse_on_server :url => "http://www.example.com"
+    def parse_on_server(options)
+      puts SERVER_SIDE_EXECUTION_WARNING
+      client.send(:run_parselet_on_server, server_id, options)
+    end
+    
+    # Access the wrapped Parselet object.
+    def parselet
+      @parselet ||= Parsley.new(code) if code
+    end
+  end
+end
+
+begin
+  require 'parsley'
+rescue LoadError
+  puts "Local Parsley bindings not found."
+  puts OnlineParselets::SERVER_SIDE_EXECUTION_WARNING
+end

data/lib/online_parselets.rb

@@ -0,0 +1,30 @@
+require 'rubygems'
+require 'json'
+require 'open-uri'
+require 'cgi'
+
+require File.dirname(__FILE__) + '/client'
+require File.dirname(__FILE__) + '/instance'
+
+module OnlineParselets
+  # Basic error.
+  class Error < Exception; end
+  # Indicates that the provided API key is invalid or not existent.
+  class InvalidAPIKey < Error; end
+  # Indicates that you have requested a non-existent environment.  At the moment the available environments are :local and :production.
+  class InvalidEnvironmentError < Error; end
+  # Indicates that the server-side parse failed.
+  class InvalidServerSideParse < Error; end
+  
+  def self.catch_invalid_key
+    begin
+      yield
+    rescue OpenURI::HTTPError => e
+      if e.message == "401 Authorization Required"
+        raise InvalidAPIKey.new("That API key is invalid")
+      else
+        raise
+      end
+    end
+  end
+end

data/online_parselets.gemspec

@@ -0,0 +1,25 @@
+Gem::Specification.new do |s|
+  s.name              = "online_parselets"
+  s.version           = "0.1.0"
+  s.date              = "2009-02-27"
+  s.summary           = "Client library for parselets.com"
+  s.email             = "parselets@gmail.com"
+  s.homepage          = "http://github.com/iterationlabs/online_parselets"
+  s.description       = "Client library for parselets.com"
+  s.has_rdoc          = true
+  s.require_paths     = ["lib"]
+  s.extensions        = nil
+  s.bindir            = 'bin'
+  s.authors           = ["Andrew Cantino", "Kyle Maxwell"]
+  s.files             = %w[
+                            README
+                            online_parselets.gemspec
+                            test/test_client.rb
+                            lib/client.rb
+                            lib/instance.rb
+                            lib/online_parselets.rb
+                          ]
+  s.rdoc_options      = ["--main", "README"]
+  s.extra_rdoc_files  = ["README"]
+  s.add_dependency("json", ["> 0.0.0"])
+end

data/test/test_client.rb

@@ -0,0 +1,50 @@
+require File.dirname(__FILE__) + '/../lib/online_parselets'
+require 'test/unit'
+require 'open-uri'
+include OnlineParselets
+
+class TestOnlineParseletsClient < Test::Unit::TestCase
+  def setup
+    @client = OnlineParselets::Client.new(:api_key => 'YOUR_API_KEY')
+  end
+
+  def test_new_client
+    assert_raises(InvalidAPIKey) { OnlineParselets::Client.new(:environment => :local) }
+    assert_nothing_raised { OnlineParselets::Client.new(:api_key => 'elkfjdf') }
+  end
+  
+  def test_client_gets_parselets
+    result = @client.find("yelp")
+    assert result.length > 0
+    assert_kind_of(Parsley, result.first.parselet)
+  end
+  
+  # This is brittle and depends on what parselets we have on the server
+  def test_running_a_parselet
+    assert @client.find("yelp-home kyle").first.parse(:url => "http://www.yelp.com")['categories'].length > 0
+  end
+  
+  # This is brittle and depends on what parselets we have on the server
+  def test_getting_a_specific_parselet
+    assert_equal nil, @client.parselet(12)
+    assert_kind_of(Instance, @client.parselet(50))
+    yelp = @client.parselet('yelp-home', 4)
+    assert_kind_of(Instance, yelp)
+    assert_equal 50, yelp.server_id
+  end
+  
+  def test_errors_on_getting_specific_parselet
+    assert_raises(Error) { @client.parselet(nil) }
+    assert_raises(Error) { @client.parselet(1, 1) }
+    assert_nothing_raised { @client.parselet(1) }
+    assert_raises(Error) { @client.parselet("yelp") }
+    assert_raises(Error) { @client.parselet("hello", 0) }
+    assert_nothing_raised { @client.parselet("hello", 1) }
+  end
+  
+  # This is brittle and depends on what parselets we have on the server
+  def test_server_side_parsing
+    assert @client.parselet(50).parse(:url => "http://www.yelp.com", :parse_on_server => true)['categories'].length > 0
+    assert @client.parselet('yelp-home', 4).parse(:url => "http://www.yelp.com", :parse_on_server => true)['categories'].length > 0
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: iterationlabs-online_parselets
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Andrew Cantino
+- Kyle Maxwell
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-27 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+    version: 
+description: Client library for parselets.com
+email: parselets@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- README
+- online_parselets.gemspec
+- test/test_client.rb
+- lib/client.rb
+- lib/instance.rb
+- lib/online_parselets.rb
+has_rdoc: true
+homepage: http://github.com/iterationlabs/online_parselets
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Client library for parselets.com
+test_files: []
+