use0mk 0.1.1

data/CHANGELOG

@@ -0,0 +1,3 @@
+v0.1.1. Documentation changes.
+v0.1. Ready.
+

data/LICENSE

@@ -0,0 +1,27 @@
+
+= License
+
+Use0MK is licensed under the terms of the MIT License. The license text is as follows.
+
+== MIT License
+
+Copyright © 2010 Stojan Dimitrovski <s.dimitrovski@gmail.com>
+
+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/Manifest

@@ -0,0 +1,6 @@
+CHANGELOG
+LICENSE
+Manifest
+README
+Rakefile
+lib/use0mk.rb

data/README

@@ -0,0 +1,64 @@
+
+= Use0MK
+
+Use0MK is a Ruby interface for the {http://0.mk} URL shortening service. It uses standard Ruby conventions in exposing 0.mk's API and allows developers to more easily utilize 0.mk.
+
+== Installation
+
+Use0MK requires the +json+ gem in order to work properly.
+
+Use0MK as a gem is hosted on {http://gemcutter.org}. After adding gemcutter to your gem sources, install it with:
+
+  gem install use0mk
+
+== Examples
+
+=== Shortening a URL
+
+  require "use0mk"
+
+  # Pass your username as the first argument and your API key as
+  # the second. You can safely use this without them.
+  zeromk = Use0MK::Interface.new
+
+  # It is probably a good idea to watch for exceptions when
+  # calling any method on Use0MK::Interface or Use0MK::ShortenedURI
+  # in order to check if something went wrong. Watch for the exceptions
+  # thrown by URI.parse, Net::HTTP errors and the Use0MK errors.
+  short = zeromk.shorten("http://google.com")
+
+  puts "Shortened #{short.title}[#{short.long_uri}] to #{short.short_uri},"
+  puts "with #{short.short_name}. Use #{short.delete_uri} with this"
+  puts "delete code #{short.delete_code} to delete this shortened URL."
+  puts "You can view the stats on this shortened URL by following"
+  puts "#{short.stats_uri}, too."
+
+  puts
+
+  puts "Too late, now your shortened URL has been deleted.\n" if short.delete
+
+
+=== Previewing a URL
+
+  require "use0mk"
+
+  zeromk = Use0MK::Interface.new # username, API key
+
+  # It's a good idea to watch for URI, Net::HTTP and Use0MK errors here.
+  # Pass a hash of :uri, or :short_name to preview in order to have it
+  # work out for you.
+  preview = zeromk.preview :uri => "http://0.mk/use0mkrb"
+
+  deletable = preview.delete
+
+  puts "The #{preview.short_uri} links to #{preview.long_uri}."
+  puts "Too bad, tho, it was created by #{preview.origin}ing a"
+  puts "given URL/shortname. Now you #{deletable ? 'can' : 'cannot'}"
+  puts "delete the short URL. #{deletable ? ':)' : ':(' }"
+
+  puts
+
+== Copyright
+
+Use0MK is Copyright © 2010 Stojan Dimitrovski. Refer to the LICENSE file included in this distribution for more information on the copyrights.
+

data/Rakefile

@@ -0,0 +1,11 @@
+require "rubygems"
+require "echoe"
+
+Echoe.new("use0mk") do |g|
+  g.author = "Stojan Dimitrovski"
+  g.email = "s.dimitrovski@gmail.com"
+  g.summary = "Ruby interface for the 0.mk URL shortening service."
+  g.url = "http://github.com/hf/use0mk"
+  g.runtime_dependencies = ["json"]
+end
+

data/lib/use0mk.rb

@@ -0,0 +1,389 @@
+#
+#  Copyright (c) 2010 Stojan Dimitrovski <s.dimitrovski@gmail.com>
+#
+#  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 "rubygems"
+require "net/http"
+require "json"
+
+module Use0MK
+  SHORTEN_URI = "http://api.0.mk/v2/skrati"
+  PREVIEW_URI = "http://api.0.mk/v2/pregled"
+  ORIGINS = [:shorten, :preview]
+
+  # ERRORS defined below
+end
+
+# Standard error class concerning {Use0MK} errors.
+class Use0MK::Error < StandardError
+  # the message returned by 0.mk
+  # @return [String]
+  attr_reader :message
+  # the status ID for the error
+  # @return [Integer]
+  attr_reader :status
+end
+
+# Too many redirects while attempting an API call.
+#
+# *status*: 100
+class Use0MK::RedirectError < Use0MK::Error
+  def initialize(message)
+    @message = message
+    @status = 100
+  end
+end
+
+# Provided link (any URI concerning any API call) was empty.
+#
+# *status*: 1
+class Use0MK::EmptyLinkError < Use0MK::Error
+  def initialize(message)
+    @message = message
+    @status = 1
+  end
+end
+
+# Provided link (any URI concerning any API call) was invalid.
+#
+# *status*: 2
+class Use0MK::InvalidLinkError < Use0MK::Error
+  def initialize(message)
+    @message = message
+    @status = 2
+  end
+end
+
+# Provided format parameter was invalid. Probably an internal error.
+#
+# *status*: 3
+class Use0MK::InvalidFormatError < Use0MK::Error
+  def initialize(message)
+    @message = message
+    @status = 3
+  end
+end
+
+# Provided (custom) short name was invalid.
+#
+# *status*: 4
+class Use0MK::InvalidShortNameError < Use0MK::Error
+ def initialize(message)
+    @message = message
+    @status = 4
+  end
+end
+
+# Provided API key was invalid.
+#
+# *status*: 5
+class Use0MK::InvalidAPIKey < Use0MK::Error
+  def initialize(message)
+    @message = message
+    @status = 5
+  end
+end
+
+# Provided credentials were invalid.
+#
+# *status*: 6
+class Use0MK::InvalidCredentials < Use0MK::Error
+  def initialize(message)
+    @message = message
+    @status = 6
+  end
+end
+
+# API call not supported by 0.mk. Check {Use0MK::SHORTEN_URI} and
+# {Use0MK::PREVIEW_URI} to see which API is being used. Probably an
+# internal error.
+#
+# *status*: 7
+class Use0MK::InvalidAPICall < Use0MK::Error
+  def initialize(message)
+    @message = message
+    @status = 7
+  end
+end
+
+module Use0MK
+  APIERRORS = [
+    Use0MK::EmptyLinkError,
+    Use0MK::InvalidLinkError,
+    Use0MK::InvalidFormatError,
+    Use0MK::InvalidShortNameError,
+    Use0MK::InvalidAPIKey,
+    Use0MK::InvalidCredentials,
+    Use0MK::InvalidAPICall
+  ]
+end
+
+# Represents a shortened URI from 0.mk. It contains only the information
+# retrieved by the API call to 0.mk. The volume of information with any
+# API call is not consistent therefore any attribute of this class that
+# is +nil+ or +empty+ should be ignored.
+#
+# The origin (the API call which generated the object of this class)
+# of this object can be tracked with the +origin+ attribute. The origin
+# is a Symbol which is a member of {Use0MK::ORIGINS}.
+#
+# It is not a good idea to create instances of this class by hand, as
+# it contains only data available from API calls to 0.mk.
+#
+class Use0MK::ShortenedURI
+  # a member of {Use0MK::ORIGINS}
+  # @return [Symbol]
+  attr_reader :origin
+  # the long URI
+  # @return [String, nil]
+  attr_reader :long_uri
+  # the shortened URI
+  # @return [String, nil]
+  attr_reader :short_uri
+  # the short name (+http://0.mk/short_name+)
+  # @return [String, nil]
+  attr_reader :short_name
+  # the stats URI
+  # @return [String, nil]
+  attr_reader :stats_uri
+  # the document title of the long URI
+  # @return [String, nil]
+  attr_reader :title
+  # the deletion URI
+  # @return [String, nil]
+  attr_reader :delete_uri
+  # the deletion code
+  # @return [String, nil]
+  attr_reader :delete_code
+  # whether this URI is deleted
+  # @return [true, false]
+  attr_reader :deleted
+
+  # Initializes this class. Usually called from either +shorten+ or +preview+.
+  #
+  # @param [Symbol] origin origin of this class (which API call created it), a member of {Use0MK::ORIGINS}
+  # @param [Hash] attributes hash of the attributes needed to create the object
+  def initialize(origin, attributes = {})
+
+    if !(Use0MK::ORIGINS.member? origin)
+      raise ArgumentError, "origin should be a member of Use0MK::ORIGINS"
+    end
+
+    @origin = origin
+    @deleted = @origin != :shorten
+
+    @long_uri = attributes[:long_uri]
+    @short_uri = attributes[:short_uri]
+    @short_name = attributes[:short_name]
+    @stats_uri = attributes[:stats_uri]
+    @title = attributes[:title]
+    @delete_uri = attributes[:delete_uri]
+    @delete_code = attributes[:delete_code]
+  end
+
+  # Deletes the shortened URI.
+  # This method calls {Use0MK::Interface.delete} internally.
+  #
+  # @return [true, false] wheter deletion succeeds (usually +true+ when +origin+ is +:shorten+)
+  def delete
+    if @deleted
+      return false
+    end
+
+    @deleted = Use0MK::Interface.delete(@delete_uri, @delete_code)
+  end
+end
+
+# This class represents the main interface through which one can operate on
+# the 0.mk API.
+class Use0MK::Interface
+  # the username associated with 0.mk
+  # @return [String, nil]
+  attr_accessor :username
+  # the API key for 0.mk
+  # @return [String, nil]
+  attr_accessor :apikey
+
+  # Initializes the {Use0MK::Interface}.
+  #
+  # @param [String] username 0.mk username
+  # @param [String] apikey 0.mk API key
+  def initialize(username = nil, apikey = nil)
+    @username = username
+    @apikey = apikey
+  end
+
+  # Deletes a shortened URI from 0.mk.
+  # This method does not raise or handles any exceptions. It also does not
+  # handle redirection.
+  #
+  # @param [String] delete_uri the 0.mk URI to delete
+  # @param [String] delete_code the 0.mk delete code associated with the 0.mk URI
+  # @return [true, false] wheter the delete succeeded
+  def self.delete(delete_uri, delete_code)
+    delete_uri = URI.parse(delete_uri)
+
+    response = Net::HTTP.post_form(delete_uri,
+      {'brisiKod' => delete_code})
+
+    case response
+      when Net::HTTPSuccess
+        return true # phew, that was hard work, that delete
+      end
+
+    return false
+  end
+
+  # Shortens a URI.
+  # This method can raise several exceptions of which most importantly:
+  # * {URI::Error}
+  # * {Net::HTTPException}
+  # * {Use0MK::Error}
+  #
+  # It is a wise thing to watch for any of those exceptions.
+  #
+  # @param [String] uri the _long_ URI to shorten
+  # @param [String] short_name a custom short name to use when shortening the long URI (+http://0.mk/short_name+)
+  # @return [Use0MK::ShortenedURI] the shortened URI
+  def shorten(uri, short_name = nil)
+    uri = URI.parse(uri)
+
+    _shorten(uri, short_name)
+  end
+
+  # Inspects an already shortened URI.
+  # This method can raise several exceptions of which most importantly:
+  # * {URI::Error}
+  # * {Net::HTTPException}
+  # * {Use0MK::Error}
+  #
+  # It is a wise idea to watch for any of these.
+  #
+  # @param [Hash] link provide +:short_name+ to inspect only the short name of an URI, or +:uri+ to inspect a whole +http://0.mk/short_name+ URI
+  # @return [Use0MK::ShortenedURI] the shortened URI (volume of data varies)
+  def preview(link = {:short_name => nil, :uri => nil})
+    uri = nil
+
+    if !link[:short_name].nil? and !link[:short_name].empty?
+      uri = "http://0.mk/#{link[:short_name]}"
+    elsif !link[:uri].nil? and !link[:uri].empty?
+      uri = link[:uri] if (link[:uri] =~ /http:\/\/0\.mk\/.*/)
+    end
+
+    if uri.nil?
+      raise ArgumentError, ':uri should be a valid http://0.mk shortened URI.'
+    end
+
+    _preview(uri)
+  end
+
+  private
+  def _queryize(hash = {})
+    pairs = []
+
+    hash.each do |key, value|
+      if !(key.nil? or value.nil?)
+        pairs << key.to_s.strip + "=" + value.to_s.strip
+      end
+    end
+
+    return pairs.join("&")
+  end
+
+  def _generate_uri(link, short_name = nil, apicall = Use0MK::SHORTEN_URI)
+    uri = URI.parse(apicall)
+
+    query = {
+      :korisnik => @username,
+      :apikey => @apikey,
+      :format => 'json',
+      :nastavka => short_name
+    }
+
+    uri.query = _queryize(query) + "&link=#{link}"
+
+    return uri
+  end
+
+  def _fetch(uri, link, redirect = 5)
+    raise Use0MK::RedirectError, "Redirect level too deep (max 5)." if redirect <= 0
+
+    response = Net::HTTP.get_response(uri)
+    case response
+      when Net::HTTPSuccess then return response
+      when Net::HTTPRedirection then _fetch(response['location'], redirect - 1)
+      else
+        response.error!
+      end
+
+  end
+
+  def _parse(origin, json)
+    if json['status'] != 1
+      raise Use0MK::APIERRORS[json['greskaId'].to_i - 1], json['greskaMsg'].to_s.strip
+    end
+
+    assign = {
+      'dolg' => :long_uri,
+      'kratok' => :short_uri,
+      'nastavka' => :short_name,
+      'urlNaslov' => :title,
+      'statsLink' => :stats_uri,
+      'brisiLink' => :delete_uri,
+      'brisiKod' => :delete_code
+    }
+
+    attributes = {}
+    json.each do |key, value|
+      if assign.has_key? key
+        attributes[assign[key]] = value
+      end
+    end
+
+    assign.keys.each do |key|
+      if !attributes.has_key? key
+        attributes[key] = nil
+      end
+    end
+
+    shortened = Use0MK::ShortenedURI.new(origin, attributes)
+  end
+
+  def _shorten(uri, short_name)
+    request_uri = _generate_uri(uri, short_name)
+
+    response = _fetch(request_uri, uri)
+    body = JSON.parse(response.body)
+
+    _parse(:shorten, body)
+  end
+
+  def _preview(uri)
+    request_uri = _generate_uri(uri, nil, Use0MK::PREVIEW_URI)
+
+    response = _fetch(request_uri, uri)
+    body = JSON.parse(response.body)
+
+    _parse(:preview, body)
+  end
+
+
+end
+

data/use0mk.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{use0mk}
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Stojan Dimitrovski"]
+  s.date = %q{2010-12-09}
+  s.description = %q{Ruby interface for the 0.mk URL shortening service.}
+  s.email = %q{s.dimitrovski@gmail.com}
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README", "lib/use0mk.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README", "Rakefile", "lib/use0mk.rb", "use0mk.gemspec"]
+  s.homepage = %q{http://github.com/hf/use0mk}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Use0mk", "--main", "README"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{use0mk}
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Ruby interface for the 0.mk URL shortening service.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+    else
+      s.add_dependency(%q<json>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<json>, [">= 0"])
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification 
+name: use0mk
+version: !ruby/object:Gem::Version 
+  hash: 25
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- Stojan Dimitrovski
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-09 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: Ruby interface for the 0.mk URL shortening service.
+email: s.dimitrovski@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGELOG
+- LICENSE
+- README
+- lib/use0mk.rb
+files: 
+- CHANGELOG
+- LICENSE
+- Manifest
+- README
+- Rakefile
+- lib/use0mk.rb
+- use0mk.gemspec
+has_rdoc: true
+homepage: http://github.com/hf/use0mk
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Use0mk
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 11
+      segments: 
+      - 1
+      - 2
+      version: "1.2"
+requirements: []
+
+rubyforge_project: use0mk
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Ruby interface for the 0.mk URL shortening service.
+test_files: []
+