vlaah 0.9.0

data/lib/vlaah/base.rb

@@ -0,0 +1,133 @@
+require 'vlaah/version'
+require 'net/http'
+require 'uri'
+require 'rexml/document'
+
+# = VLAAH API Client Library For Ruby
+#
+# This library provides model classes about VLAAH API.
+#
+# == Installation
+#
+# You can install this library with RubyGems.
+#
+#     gem install vlaah
+#
+# Or checkout it from Subversion repository.
+#
+#     svn co http://vlaah.rubyforge.org/svn/trunk vlaah-ruby
+#
+# == Applying A New Application And Setting Application Key
+#
+# You must apply the application in the VLAAH API page before you use this API.
+# And you can get an application key of 64 characters.
+#
+#     VLAAH::Base.application_key = "<your application key goes here.>";
+#
+# To apply a new application, go http://api.vlaah.com.
+#
+# See VLAAH::Topic, VLAAH::Person and VLAAH::Comment for more manuals and
+# examples.
+#
+# == Author
+#
+# This library was written by Hong, MinHee. <dahlia@lunant.net> And, thanks for
+# our Lunant friends.
+#
+# == License
+#
+# It is provided with MIT License.
+# See more details on http://www.opensource.org/licenses/mit-license.php
+module VLAAH
+  Copyright = "Copyright (c) 2008 Lunant <http://lunant.net/>"
+  Author    = "Hong, MinHee <dahlia@lunant.net>"
+  Protocol  = "VLAAH/0.9"
+
+  HTTP = ::Net::HTTP unless defined? HTTP
+  Host = "vlaah.com" unless defined? Host
+  Path = "/"         unless defined? Path
+
+  # :stopdoc:
+  class Error < StandardError; end
+  class ApplicationKeyError < Error; end
+  # :startdoc:
+
+  # It is an internal abstract class to inherit.
+  class Base
+    @@application_key = nil
+    @@connection = nil
+    @@cache = {}
+
+    # The application key. Default value is +nil+.
+    #
+    #     VLAAH::Base.application_key  #=> nil
+    #     VLAAH::Base.application_key = '6cec5bcd27b9.........35af1e8ea0b'
+    #     VLAAH::Base.application_key  #=> '6cec5bcd27b9.........35af1e8ea0b'
+    def self.application_key
+      @@application_key
+    end
+
+    # Your application key goes here.
+    #
+    #     VLAAH::Base.application_key = '6cec5bcd27b9.........35af1e8ea0b'
+    def self.application_key=(appkey)
+      @@application_key = appkey
+    end
+
+    protected
+
+    def self.connect_http
+      if @@connection
+        @@connection
+      else
+        @@connection = HTTP.new Host
+      end
+    end
+
+    def self.raw_data(*resource)
+      page = resource.pop if resource.last.is_a? ::Integer
+
+      unsafe = /[^-_.~a-zA-Z\d;:@&,]/n
+
+      path = resource.flatten \
+                     .reject { |x| x.nil? } \
+                     .map { |s| URI.escape(s.to_s, unsafe) } \
+                     .join("/")
+
+      path += "?#{page}" if page
+
+      return @@cache[path] if @@cache.include? path
+
+      unless appkey = application_key
+        raise ApplicationKeyError,
+              "Missing VLAAH::Base.application_key",
+              caller[1..-1]
+      end
+
+      headers = {
+        "Accept" => "text/xml",
+        "User-Agent" => "VLAAH-Ruby/#{Version} (appkey/#{appkey})",
+        "X-Accept-Protocol" => Protocol
+      }
+
+      response = connect_http.get(Path + path, headers)
+      accepted = response["X-Accept-Protocol"]
+
+      if accepted =~ /(^|,)\s*#{Protocol}\s*;\s*expires\s*=\s*(.+?)(,|$)/
+        warn "#{caller[0]}: warning:" +
+             " This version of VLAAH protocol is deprecated;" +
+             " #{Protocol} will be expired on #{$2.strip}"
+      end
+
+      xml = ::REXML::Document.new(response.body).root
+
+      if xml.name == "error" and xml.attributes["type"] =~ /application-key/
+        raise ApplicationKeyError,
+              "Invalid VLAAH::Base.application_key",
+              caller[1..-1]
+      end
+
+      return xml
+    end
+  end
+end

data/lib/vlaah/comment.rb

@@ -0,0 +1,156 @@
+require 'vlaah/topic'
+require 'date'
+
+module VLAAH
+  # = Comment
+  #
+  # It represents comments of the topic. Comments are also kind of topic in
+  # VLAAH. So it inherits VLAAH::Topic.
+  #
+  #     VLAAH::Comment.superclass            #=> VLAAH::Topic
+  #     VLAAH::Topic.find("?1234567").class  #=> VLAAH::Comment
+  #
+  # == Getting Comment Body
+  #
+  # To get body of the comment, call +body+ method. You can customize the name
+  # and the attributes of the wrapping paragraph element with arguments.
+  #
+  #     comment.body
+  #       #=> '<p>Hello, <a href="http://vlaah.com/VLAAH" class="topic">VLAAH'
+  #           '</a> <em>world</em>!</p>'
+  #     comment.body("blockquote")
+  #       #=> '<blockquote>Hello, <a href="http://vlaah.com/VLAAH"'
+  #           ' class="topic">VLAAH</a> <em>world</em>!</blockquote>'
+  #     comment.body("q", :class => "vlaah-comment")
+  #       #=> '<q class="vlaah-comment">Hello, <a href="http://vlaah.com/VLAAH"'
+  #           ' class="topic">VLAAH</a> <em>world</em>!</q>'
+  #
+  # If you want just a plain text, pass +nil+.
+  #
+  #     comment.body(nil)  #=> "Hello, VLAAH world!"
+  #
+  # It may be +nil+.
+  #
+  #     comment_without_body.body  #=> nil
+  #
+  # == Getting Author
+  #
+  #     comment.author       #=> <VLAAH::Person name="~dahlia" ...>
+  #     comment.author.name  #=> "~dahlia"
+  #     comment.author.nick  #=> "Hong, MinHee"
+  #
+  # +author+ may be +nil+.
+  #
+  #     anonymous_comment.author  #=> nil
+  class Comment < Topic
+    include ::Comparable
+
+    NamePattern = /^\?[1-9]\d*$/
+
+    # Returns the comment named +name+. May be +nil+.
+    def self.find(name)
+      return unless NamePattern =~ name
+
+      xml = raw_data(name).root
+      new(xml) if xml.attributes.include? 'type'
+    end
+
+    # :plus or :minus.
+    #
+    #     plus_comment.type   #=> :plus
+    #     minus_comment.type  #=> :minus
+    def type
+      raw_data("@type").first.value.to_sym
+    end
+
+    # Returns +true+ if its type is plus.
+    #
+    #     plus_comment.plus?   #=> true
+    #     minus_comment.plus?  #=> false
+    def plus?
+      type == :plus
+    end
+
+    # Returns +true+ if its type is minus.
+    #
+    #     plus_comment.minus?   #=> false
+    #     minus_comment.minus?  #=> true
+    def minus?
+      type == :minus
+    end
+
+    # The created time. +DateTime+ instance.
+    #
+    #     comment.created_at       #=> #<DateTime: 70694857241/28800,0,2299161>
+    #     comment.created_at.to_s  #=> "2008-08-04T01:02:03+00:00"
+    def created_at
+      DateTime.parse raw_data("@created-at").first.value
+    end
+
+    # The author. +Person+ instance.
+    #
+    #     comment.author       #=> <VLAAH::Person name="~dahlia" nick="Hong">
+    #     comment.author.name  #=> "~dahlia"
+    def author
+      result = raw_data("author")
+      Person.new(result.first) unless result.empty?
+    end
+
+    # Returns the body string. The link to topic includes class="topic".
+    # The paragraph is wrapped into +tag+ element with +attrs+.
+    #
+    #     comment.body
+    #       #=> '<p>Hello, <a href="http://vlaah.com/VLAAH" class="topic">'
+    #           'VLAAH</a> <em>world</em>!</p>'
+    #     comment.body("blockquote")
+    #       #=> '<blockquote>Hello, <a href="http://vlaah.com/VLAAH"'
+    #           ' class="topic">VLAAH</a> <em>world</em>!</blockquote>'
+    #     comment.body("q", :class => "comment")
+    #       #=> '<q class="comment">Hello, <a href="http://vlaah.com/VLAAH"'
+    #           ' class="topic">VLAAH</a> <em>world</em>!</q>'
+    #
+    # If you want just a plain text, pass +nil+.
+    #
+    #     comment.body(nil)  #=> "Hello, VLAAH world!"
+    #
+    # It may be +nil+.
+    #
+    #     comment_without_body.body  #=> nil
+    def body(tag = "p", attrs = {})
+      result = raw_data("body/*")
+      return nil if result.empty?
+
+      if tag.nil?
+        raw_data("body//text()").map { |n| n.value }.join(" ").gsub(/\s+/, ' ')
+      else
+        element = result.first
+        element.name = tag
+
+        for key in element.attributes.keys
+          element.delete_attribute(key)
+        end
+
+        for key, value in attrs
+          element.add_attribute(key.to_s, value.to_s)
+        end
+
+        element.to_s
+      end
+    end
+
+    # Compares with the another comment by +created_at+ time.
+    def <=>(operand)
+      name[1..-1].to_i <=> operand.name[1..-1].to_i
+    end
+
+    def inspect
+      if self.body
+        "<#{self.class.name} name=#{name.inspect}" +
+        " type=#{type} body=#{body.inspect}>"
+      else
+        super
+      end
+    end
+  end
+end
+

data/lib/vlaah/comment_list.rb

@@ -0,0 +1,148 @@
+require 'vlaah/base'
+
+module VLAAH
+  # This container class is used for various lists of comments.
+  # e.g. VLAAH::Topic#comments, VLAAH::Person#feedback
+  #
+  # It accepts only instances of VLAAH::Comment. It is immutable.
+  class CommentList < Base
+    include ::Enumerable
+
+    def initialize(*resource)
+      @resource = resource.flatten
+    end
+
+    # The number of comments. May be zero.
+    def length
+      raw_data("@cardinality", nil, :first).value.to_i
+    end
+
+    alias_method :size, :length
+
+    # Returns +true+ when +self+ contains no comments.
+    def empty?
+      length.zero?
+    end
+
+    # Returns the comment at index.
+    # A negative index counts from the end of self.
+    # Returns +nil+ if the index is out of range.
+    # See also VLAAH::Comment#[].
+    def at(index)
+        return nil if empty?
+        return nil unless page = index_to_page(index)
+        page, rest = page
+        Comment.new raw_data("//comment", page).at(rest)
+    end
+
+    # Returns the ccomment at index, or returns a subarray starting at index and
+    # continuing for length comments, or returns a subarray specified by index
+    # +Range+ instance.
+    # Negative indices count backward from the end of the list (-1 is the last
+    # comment).
+    def slice(index, length = nil)
+      unless length.nil?
+        to = index + length
+        index = if index < 0 and to >= 0
+          index..-1
+        else
+          index...to
+        end
+      end
+
+      if index.is_a? ::Range
+        return [] if empty?
+        begin_page, begin_offset = index_to_page(index.begin)
+        end_page, end_offset = index_to_page(index.end)
+
+        return [] if begin_page.nil? or end_page.nil?
+
+        comments = []
+
+        for page in begin_page..end_page
+          range = if page == begin_page and begin_page == end_page
+            ::Range.new(begin_offset, end_offset, index.exclude_end?)
+          elsif page == begin_page
+            begin_offset..-1
+          elsif page == end_page
+            ::Range.new(0, end_offset, index.exclude_end?)
+          else
+            0..-1
+          end
+
+          for comment in raw_data("//comment", page)[range]
+            comments << Comment.new(comment)
+          end
+        end
+
+        comments
+      else
+        at(index)
+      end
+    end
+
+    alias_method :[], :slice
+
+    # Returns the first comment. If the list is empty, returns +nil+.
+    def first
+      self[0]
+    end
+
+    # Returns the last comment. If the list is empty, returns +nil+.
+    def last
+      self[-1]
+    end
+
+    # Calls block once for each element in self,
+    # passing that comment as a parameter.
+    def each # :yields: comment
+      length = raw_data("@total-pages", nil, :first).value.to_i
+
+      for page in (1..length)
+        for comment in raw_data("//comment", page)
+          yield Comment.new(comment)
+        end
+      end
+    end
+
+    # Returns a new array containing comments of the list in reverse order.
+    def reverse
+      to_a.reverse
+    end
+
+    def inspect
+      len = length
+
+      list = raw_data("//comment/@name").map do |c|
+        "<VLAAH::Comment name=#{c.value.inspect}>"
+      end
+
+      if list.length == len
+        "[#{list.join(', ')}]"
+      else
+        "[#{list.join(', ')} ... (#{length} comments)]"
+      end
+    end
+
+    def limit_per_page
+      if defined? @limit
+        @limit
+      else
+        @limit = raw_data("//comment").length 
+      end
+    end
+
+    def index_to_page(index)
+      return nil if index >= length
+      index = length + index if index < 0
+      return nil if index < 0
+      [index / limit_per_page + 1, index % limit_per_page]
+    end
+
+    def raw_data(xpath, page = nil, method = :match)
+      page = nil if page.is_a? Integer and page < 2
+      data = self.class.raw_data(@resource, page)
+      return ::REXML::XPath.__send__(method, data, xpath)
+    end
+  end
+end

data/lib/vlaah/locale.rb

@@ -0,0 +1,32 @@
+
+module VLAAH
+  class Locale
+    # Creates a new Locale instance.
+    #
+    #     Locale.new("ko_kr")  #=> ko_KR
+    def initialize(locale)
+      @language, @country = locale.split(/[^[:alpha:]]+/)
+    end
+
+    # The language.
+    #
+    #     Locale.new("ko_kr").language  #=> "ko"
+    def language
+      @language.downcase
+    end
+
+    # The country
+    #
+    #     Locale.new("en_us").country  #=> "US"
+    def country
+      @country.upcase
+    end
+
+    # Convert to a string.
+    #
+    #     Locale.new("ja_jp").to_s  #=> "ja_JP"
+    def to_s
+      "#{language}_#{country}"
+    end
+  end
+end

data/lib/vlaah/person.rb

@@ -0,0 +1,157 @@
+require 'vlaah/topic'
+require 'vlaah/locale'
+require 'date'
+require 'rexml/xpath'
+
+module VLAAH
+  # = Person: VLAAH User
+  #
+  # It represents the user of VLAAH. Users are kind of topic in VLAAH.
+  # So it inherits VLAAH::Topic.
+  #
+  #     VLAAH::Person.superclass            #=> VLAAH::Topic
+  #     VLAAH::Topic.find("~dahlia").class  #=> VLAAH::Person
+  #
+  # == Getting Favorites
+  #
+  # To get a set of one’s favorites, call +favorites+ method. It returns an
+  # instance of VLAAH::CommentList.
+  #
+  #     person.favorites  #=> [<VLAAH::Comment name="?12345">,
+  #                            <VLAAH::Comment name="?6789"> ... (531 comments)]
+  #
+  # If you want to find topics instead of comments, +map+ it.
+  #
+  #     person.favorites[0..5].map { |comment| comment.topic.name }
+  #       #=> ["Smalltalk", "Scheme", "Perl", "C++", "VLAAH", "Jamiroquai"]
+  #
+  # == Getting Friends
+  #
+  # There is no “friends”-like feature in VLAAH exactly. But VLAAH defines
+  # _friend_ as relation that give a plus or a minus each other.
+  #
+  #     person.friends  #=> [<VLAAH::Person name="~dahlia">, ...]
+  #
+  # Person#friends returns an array of people. It may be empty. If you want
+  # friends’ comments, you can use +comments+ singleton method of the array.
+  #
+  #     person.friends.comments  #=> [<VLAAH::Comment name="~54321">,
+  #                                   <VLAAH::Comment name="~4321">
+  #                                   ... (14092 comments)]
+  #
+  # == Getting Feedback
+  #
+  # If someone comments to your comment, it is a _recursive comment_.
+  # VLAAH defines _feedback_ as recursive comments about you.
+  #
+  # To find feedback, call +feedback+ method. It returns VLAAH::CommentList.
+  #
+  #     person.feedback  #=> [<VLAAH::Comment name="?9123"> ... (8192 comments)]
+  class Person < Topic
+    NamePattern = /^~[-_.a-z0-9]{3,32}$/
+
+    # Returns the person named name. May be +nil+.
+    def self.find(name)
+      return unless NamePattern =~ name
+
+      xml = raw_data(name).root
+      new(xml) if xml.attributes.include? 'nick'
+    end
+
+    # Returns the nick name.
+    def nick
+      raw_data("@nick").first.value
+    end
+
+    # The URL string of its picture.
+    #
+    #     person.picture_url  #=> "http://static.vlaah.com/.../default.128.gif"
+    def picture_url
+      raw_data("@picture-url").first.value
+    end
+
+    # Returns :male or :female. May be +nil+.
+    #
+    #     boy.gender           #=> :male
+    #     girl.gender          #=> :female
+    #     unidentified.gender  #=> nil
+    def gender
+      result = raw_data("@gender")
+      result.first.value.to_sym unless result.empty?
+    end
+
+    # Returns +true+ if gender is male.
+    # May be +nil+ when it does not have +gender+ field.
+    #
+    #     boy.male?           #=> true
+    #     girl.male?          #=> false
+    #     unidentified.male?  #=> nil
+    def male?
+      gender == :male if gender
+    end
+
+    # Returns +true+ if gender is female.
+    # May be +nil+ when it does not have +gender+ field.
+    #
+    #     boy.female?           #=> false
+    #     girl.female?          #=> true
+    #     unidentified.female?  #=> nil
+    def female?
+      gender == :female if gender
+    end
+
+    # Returns its birthday. May be +nil+.
+    def birthday
+      result = raw_data("@birthday")
+      Date.strptime(result.first.value) unless result.empty?
+    end
+
+    # Returns its locale. (An instance of VLAAH::Locale.)
+    #
+    #     korean.locale    #=> ko_KR
+    #     japanese.locale  #=> ja_JP
+    def locale
+      result = raw_data("@locale")
+      Locale.new(result.first.value) unless result.empty?
+    end
+
+    # Returns an array of the friends.
+    # You can find also comments that writed the friends with +comments+ method.
+    #
+    #     person.friends           #=> [<VLAAH::Person name="~dahlia" ...>,
+    #                                   <VLAAH::Person name="~shinvee" ...> ...]
+    #     person.friends.comments  #=> [<VLAAH::Comment name="?1234">,
+    #                                   <VLAAH::Comment name="?567">
+    #                                   ... (1234 comments)]
+    def friends
+      xml = self.class.raw_data(normalized_name, "friends")
+      friends = ::REXML::XPath.match(xml, "//person").map(&Person.method(:new))
+      friends.instance_variable_set(:@__vlaah_person_name, name)
+
+      def friends.comments
+        CommentList.new @__vlaah_person_name, "friends"
+      end
+
+      return friends
+    end
+
+    # Returns a list of comments that written by the person.
+    # (VLAAH::CommentList)
+    def favorites
+       CommentList.new name, "favorites"
+    end
+
+    # Returns a list of comments that appended in favorites of the person.
+    # (VLAAH::CommentList)
+    def feedback
+       CommentList.new name, "feedback"
+    end
+
+    alias_method :feedbacks, :feedback
+
+    def inspect
+      "<#{self.class.name} name=#{name.inspect} nick=#{nick.inspect}>"
+    end
+  end
+end
+