tagalus 0.5.0

data/History.txt

@@ -0,0 +1,7 @@
+=== 0.5.0 / 2009-03-26
+
+* 1st Release
+
+  * Full API access
+  * Swappable XML parsers
+

data/Manifest.txt

@@ -0,0 +1,7 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/tagalus.rb
+lib/xmlstruct.rb
+test/test_tagalus.rb

data/README.txt

@@ -0,0 +1,65 @@
+= tagalus
+
+* http://www.carboni.ca/projects/tagalus/
+
+== DESCRIPTION:
+
+This module encapsulates the API for tagal.us, a site which helps users
+define tags on twitter or other websites. The basic elements are tags,
+definitions, and comments - and these 3 objects can be written and read
+to/from tagal.us using this gem.
+
+There's just 6 useful methods - 3 that read, and 3 that write.
+
+This module uses the Carboni.ca XML base, which means you can set which
+XML parser it will use - simply use
+   Tagalus.parser = :nokogiri # can be :nokogiri, :hpricot, :rexml, or :libxml
+to change the parser.
+
+== FEATURES/PROBLEMS:
+
+* Full access to the Tagul.us API
+* Swap out XML parsers - nokogiri, hpricot, rexml, and libxml-ruby are supported
+
+== SYNOPSIS:
+
+Exmaple usage:
+   acc = Tagalus::Account.new("1290185015890")
+   acc.define("apisandbox") #=> <Definition>
+   acc.comments("apisandbox").each do |comm|
+     puts comm.text+"\n"
+   end
+   acc.post_comment "apisandbox", "Testing, 1,2,3!" #=> <Comment>
+
+== REQUIREMENTS:
+
+* none, though an XML parser other than REXML will make it run quicker
+
+== INSTALL:
+
+* sudo gem install tagalus
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Michael J. Edgar
+
+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/Rakefile

@@ -0,0 +1,29 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/tagalus.rb'
+
+Hoe.new('tagalus', Tagalus::VERSION) do |p|
+  p.rubyforge_name = 'carbonica' # if different than lowercase project name
+  p.developer('Michael J. Edgar', 'adgar@carboni.ca')
+  
+  desc 'Post your blog announcement to blogger.'
+  task :post_blogger do
+    require 'blogger'
+    p.with_config do |config, path|
+      break unless config['blogs']
+      subject, title, body, urls = p.announcement
+      
+      config['blogs'].each do |site|
+        next unless site['url'] =~ /www\.blogger\.com/
+        acc = Blogger::Account.new(site['user'],site['password'])
+        post = Blogger::Post.new(:title => title, :content => body, :categories => p.blog_categories, :formatter => :rdiscount)
+        acc.post(site['blog_id'], post)
+
+      end
+    end
+  end
+end
+
+# vim: syntax=Ruby

data/lib/tagalus.rb

@@ -0,0 +1,222 @@
+require 'net/http'
+require 'time'
+require File.dirname(__FILE__)+"/xmlstruct.rb"
+# = tagalus
+#
+# This module encapsulates the API for tagal.us, a site which helps users
+# define tags on twitter or other websites. The basic elements are tags,
+# definitions, and comments - and these 3 objects can be written and read
+# to/from tagal.us using this gem.
+#
+# There's just 6 useful methods - 3 that read, and 3 that write.
+#
+# Exmaple usage:
+#    acc = tagalus::Account.new("1290185015890")
+#    acc.define("apisandbox") #=> <Definition>
+#    acc.comments("apisandbox").each do |comm|
+#      puts comm.text+"\n"
+#    end
+#    acc.post_comment "apisandbox", "Testing, 1,2,3!" #=> <Comment>
+#
+# This module uses the Carboni.ca XML base, which means you can set which
+# XML parser it will use - simply use
+#    tagalus.parser = :nokogiri # can be :nokogiri, :hpricot, :rexml, or :libxml
+# to change the parser.
+#
+module Tagalus
+  VERSION = '0.5.0'
+  
+  API_ROOT = 'api.tagal.us'
+  
+  class TagalusError < StandardError; end
+  
+  # The list of parsers you are allowed to use with the tagalus module.
+  AVAILABLE_PARSERS = [:nokogiri, :hpricot, :rexml, :libxml]
+  # Sets which XML parser to use. Must be in AVAILABLE_PARSERS
+  def self.parser=(val)
+    raise UnsupportedParserError.new("An unsupported parser was provided: #{val}") unless AVAILABLE_PARSERS.include? val
+    @@parser = val
+    case @@parser
+    when :nokogiri
+      require 'nokogiri'
+    when :hpricot
+      require 'hpricot'
+    when :rexml
+      require 'rexml/document'
+    when :libxml
+      require 'libxml'
+    end
+  end
+  Tagalus.parser = :rexml
+  def self.parser
+    @@parser
+  end
+  
+  # = Account
+  #
+  # Encapsulates a user's account on tagal.us. Currently the tagal.us API is rather
+  # limited, but it is fully supported. Example usage:
+  #
+  #    acc = tagalus::Account.new("1290185015890")
+  #    acc.define("apisandbox") #=> <Definition>
+  #    acc.post_comment "apisandbox", "Testing, 1,2,3!" #=> <Comment>
+  #
+  class Account
+    
+    include CanParse
+    
+    # Creates a new Account object, with API Key +key+. This key is necessary to
+    # create tags, definitions, and comments on the server. Read-only operations don't
+    # require a key.
+    def initialize(key="")
+      @api_key = key
+    end
+    
+    # Retrieves the most authoritative definition of the tag with name or id +tag+
+    def define tag
+      path = "/tag/#{tag}/show.xml"
+      doc = http_get path
+      Definition.new(:xml => xpath(doc,"//definition").first)
+    end
+    
+    # Retrieves all the definitions for the tag with name or id +tag+
+    def all_definitions tag
+      path = "/definition/#{tag}/show.xml"
+      doc = http_get path
+      
+      definitions = []
+      xpath(doc,"//definition").each do |entry|
+        definitions << Definition.new(:xml => entry)
+      end
+      definitions
+    end
+    
+    # Retrieves all the comments for the tag with name or id +tag+
+    def comments tag
+      path = "/comment/#{tag}/show.xml"
+      doc = http_get path
+      
+      comments = []
+      xpath(doc, "//comment").each do |entry|
+        comments << Comment.new(:xml => entry)
+      end
+      comments
+    end
+    
+    # creates a comment on tagal.us. The tag must have already been created, or an error will be
+    # thrown. +comment+ is a string. +tag+ can be either a tagalus::Tag, String, or Fixnum.
+    def post_comment tag, comment
+      tag_params = (tag.is_a? String) ? { :the_tag => tag } : {:tag_id => (tag.is_a? Tag) ? tag.id : tag }
+      tag_params.merge! :the_comment => comment
+      path = "/comment/create.xml"
+      doc = http_post path, tag_params
+      Comment.new(:xml => doc)
+    end
+    
+    # defines a tag on tagal.us. The tag must have already been created, or an error will be
+    # thrown. +definition+ is a string. +tag+ can be either a tagalus::Tag, String, or Fixnum.
+    def post_definition tag, definition
+      tag_params = (tag.is_a? String) ? { :the_tag => tag } : {:tag_id => (tag.is_a? Tag) ? tag.id : tag }
+      tag_params.merge! :the_definition => definition
+      path = "/definition/create.xml"
+      doc = http_post path, tag_params
+      puts doc.to_s
+      Definition.new(:xml => doc)
+    end
+    
+    # creates a tag on tagal.us. The tag must not have already been created, or an error will be
+    # thrown. +tag+ and +definition+ are both strings.
+    def create_tag tag, definition
+      tag_params =  { :the_tag => tag, :the_definition => definition } 
+      path = "/tag/create.xml"
+      doc = http_post path, tag_params
+      
+      definition = Definition.new(:xml => xpath(doc,"//definition").first)
+      result = Tag.new(:xml => doc)
+      result.definitions = [definition]
+      result
+    end
+    
+    # Helper method for retrieving URLs via GET while escaping parameters and including API-specific
+    # parameters
+    def http_get(path, query_params = {})
+      query_params.merge!(:api_key => @api_key, :api_version => "0001")
+      http = Net::HTTP.new API_ROOT
+      path = path + "?" + URI.escape(query_params.map {|k,v| "#{k}=#{v}"}.join("&"), /[^-_!~*'()a-zA-Z\d;\/?:@&=+$,\[\]]/n)
+      resp = http.get(path)
+      raise tagalus::tagalusError.new("Error while querying the path #{path}") if resp.body =~ /something went wrong/
+      xml_doc(resp.body)
+    end
+    
+    # Helper method for retrieving URLs via POST while escaping parameters and including API-specific
+    # parameters
+    def http_post(path, query_params = {})
+      query_params.merge!(:api_key => @api_key, :api_version => "0001")
+      http = Net::HTTP.new API_ROOT
+      data = URI.escape(query_params.map {|k,v| "#{k}=#{v}"}.join("&"), /[^-_!~*'()a-zA-Z\d;\/?:@&=+$,\[\]]/n)
+      resp = http.post(path, data)
+      xml_doc(resp.body)
+    end
+  end
+  
+  # = Tag
+  # Represents a tag retrieved or posted to tagal.us. Fields available:
+  #  [:id] - the ID of the definition
+  #  [:tag] - the name of the tag being defined
+  #  [:updated_at] - When the comment was last updated
+  #  [:created_at] - When the comment was initially created
+  class Tag < XMLStruct
+    attr_accessor :definitions
+    field :tag, :node, "//the-tag"
+    field :id, :node, "//id"
+    field :updated_at, :proc, lambda { |entry| Time.xmlschema(xml_content(xpath(entry,"//updated-at").first)) }
+    field :created_at, :proc, lambda { |entry| Time.xmlschema(xml_content(xpath(entry,"//created-at").first)) }
+    def post_initialize; @id = @id.to_i; end
+  end
+  
+  # = Definition
+  # Represents a definition retrieved or posted on tagal.us. Fields available:
+  #  [:id] - the ID of the definition
+  #  [:meta_info] - no idea what this is, seems to always be empty
+  #  [:tag_id] - the ID of the tag being defined
+  #  [:text] - the text of the definition
+  #  [:user_id] - the ID of the user posting the comment
+  #  [:updated_at] - When the comment was last updated
+  #  [:created_at] - When the comment was initially created
+  #  [:authority] - The number of up-votes minus the number of down-votes.
+  class Definition < XMLStruct
+    field :text, :node, ".//the-definition"
+    field :tag_id, :node, ".//tag-id"
+    field :id, :node, ".//id"
+    field :authority, :node, ".//authority"
+    field :user_id, :node, ".//user-id"
+    field :meta_info, :node, ".//meta-info"
+    field :updated_at, :proc, lambda { |entry| Time.xmlschema(xml_content(xpath(entry,".//updated-at").first)) }
+    field :created_at, :proc, lambda { |entry| Time.xmlschema(xml_content(xpath(entry,".//created-at").first)) }
+    def post_initialize
+      @tag_id = @tag_id.to_i; @id = @id.to_i; @user_id = @user_id.to_i
+    end
+  end
+  
+  # = Comment
+  # Represents a comment retrieved from tagal.us. Fields available:
+  #  [:id] - the ID of the comment
+  #  [:meta_info] - no idea what this is, seems to always be empty
+  #  [:tag_id] - the ID of the tag
+  #  [:text] - the text of the comment
+  #  [:user_id] - the ID of the user posting the comment
+  #  [:updated_at] - When the comment was last updated
+  #  [:created_at] - When the comment was initially created
+  class Comment < XMLStruct
+    field :id, :node, "id"
+    field :meta_info, :node, "meta_info"
+    field :tag_id, :node, "tag-id"
+    field :text, :node, "the-comment"
+    field :user_id, :node, "user-id"
+    field :updated_at, :proc, lambda { |entry| Time.xmlschema(xml_content(xpath(entry,"//updated-at").first)) }
+    field :created_at, :proc, lambda { |entry| Time.xmlschema(xml_content(xpath(entry,"//created-at").first)) }
+    def post_initialize #:nodoc:
+      @tag_id = @tag_id.to_i; @id = @id.to_i; @user_id = @user_id.to_i
+    end
+  end
+end

data/lib/xmlstruct.rb

@@ -0,0 +1,111 @@
+# Methods for parser-agnostic parsing
+module CanParse
+  # Helper method that encapsulates a string into an XML document
+  def xml_doc(body)
+    case Tagalus.parser
+    when :nokogiri
+      Nokogiri::XML(body)
+    when :hpricot
+      Hpricot(body)
+    when :rexml
+      REXML::Document.new(body)
+    when :libxml
+      LibXML::XML::Parser.string(body).parse
+    end
+  end
+  
+  def xpath(element,path)
+    case Tagalus.parser
+    when :nokogiri
+      element.xpath(path)
+    when :hpricot
+      puts "in hpricot"
+      element/path #force the //
+    when :rexml
+      REXML::XPath.match(element,path)
+    when :libxml
+      element.find(path)
+    end
+  end
+  
+  def xml_content(element)
+    case Tagalus.parser
+    when :nokogiri
+      element.content
+    when :hpricot
+      element.inner_text
+    when :rexml
+      element.text
+    when :libxml
+      element.content
+    end
+  end
+  
+  def xml_attribute(element,attribute)
+    case Tagalus.parser
+    when :nokogiri
+      element[attribute]
+    when :hpricot
+      element.get_attribute(attribute)
+    when :rexml
+      element.attributes[attribute]
+    when :nokogiri
+      element.attributes[attribute]
+    end
+  end
+end
+
+# Generic XML Structure
+class XMLStruct
+  
+  include CanParse
+  extend CanParse
+  
+  class << self
+    
+    attr_accessor :fields
+    
+    def field(name, type, getter, path="")
+      @fields ||= {}
+      if type == :attribute
+        @fields[name.to_sym] = {:type => type, :getter => getter, :path => path}
+      else
+        @fields[name.to_sym] = {:type => type, :getter => getter}
+      end
+      attr_accessor name
+      
+    end
+  end
+  
+  def post_initialize; end
+  
+  def initialize(opts = {})
+    if opts[:xml]
+      parse_xml opts[:xml]
+    else
+      opts.each do |key, value|
+        instance_variable_set("@#{key}".to_sym, value)
+      end
+    end
+    post_initialize
+    self
+  end
+  
+  def parse_xml(entry)
+    myfields = self.class.fields
+    myfields.each do |k,v|
+      if v[:getter].is_a?(String) || v[:getter].is_a?(Symbol)
+        if v[:type] == :attribute
+          instance_variable_set("@#{k}".to_sym, xml_attribute(xpath(entry,v[:path]).first, v[:getter].to_s))
+        elsif v[:type] == :node
+          node = xpath(entry, v[:getter].to_s).first
+          if node
+            instance_variable_set "@#{k}".to_sym, xml_content(node)
+          end
+        end
+      elsif v[:getter].is_a?(Proc)
+        instance_variable_set "@#{k}".to_sym, v[:getter].call(entry)
+      end
+    end
+  end
+end

data/test/test_tagalus.rb

@@ -0,0 +1,8 @@
+require "test/unit"
+require "tagalus"
+
+class TestTagalus < Test::Unit::TestCase
+  def test_sanity
+    flunk "write tests or I will kneecap you"
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: tagalus
+version: !ruby/object:Gem::Version 
+  version: 0.5.0
+platform: ruby
+authors: 
+- Michael J. Edgar
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-27 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.11.0
+    version: 
+description: "This module encapsulates the API for tagal.us, a site which helps users define tags on twitter or other websites. The basic elements are tags, definitions, and comments - and these 3 objects can be written and read to/from tagal.us using this gem.  There's just 6 useful methods - 3 that read, and 3 that write.  This module uses the Carboni.ca XML base, which means you can set which XML parser it will use - simply use Tagalus.parser = :nokogiri # can be :nokogiri, :hpricot, :rexml, or :libxml to change the parser."
+email: 
+- adgar@carboni.ca
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/tagalus.rb
+- lib/xmlstruct.rb
+- test/test_tagalus.rb
+has_rdoc: true
+homepage: http://www.carboni.ca/projects/tagalus/
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+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: carbonica
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: This module encapsulates the API for tagal.us, a site which helps users define tags on twitter or other websites
+test_files: 
+- test/test_tagalus.rb