tumblr-rb 0.0.1 → 0.1.0

data/.gitignore

@@ -17,5 +17,6 @@ tmtags
 coverage
 rdoc
 pkg
+.bundle
 
 ## PROJECT::SPECIFIC

data/Gemfile

@@ -5,6 +5,7 @@ gem 'weary','>= 0.7.1'
 group :test do
 	gem 'rake'
 	gem 'redgreen'
-	gem 'fakeweb'
+	gem 'contest'
+	gem 'vcr'
 	gem 'jeweler'
 end

data/Gemfile.lock

@@ -0,0 +1,58 @@
+--- 
+dependencies: 
+  contest: 
+    group: 
+    - :test
+    version: ">= 0"
+  rake: 
+    group: 
+    - :test
+    version: ">= 0"
+  weary: 
+    group: 
+    - :default
+    version: ">= 0.7.1"
+  vcr: 
+    group: 
+    - :test
+    version: ">= 0"
+  jeweler: 
+    group: 
+    - :test
+    version: ">= 0"
+  redgreen: 
+    group: 
+    - :test
+    version: ">= 0"
+specs: 
+- json_pure: 
+    version: 1.2.2
+- git: 
+    version: 1.2.5
+- redgreen: 
+    version: 1.2.2
+- rubyforge: 
+    version: 2.0.4
+- ruby-hmac: 
+    version: 0.4.0
+- crack: 
+    version: 0.1.7
+- oauth: 
+    version: 0.3.6
+- weary: 
+    version: 0.7.1
+- rake: 
+    version: 0.8.7
+- gemcutter: 
+    version: 0.5.0
+- jeweler: 
+    version: 1.4.0
+- contest: 
+    version: 0.1.2
+- fakeweb: 
+    version: 1.2.8
+- vcr: 
+    version: 0.1.2
+hash: c4f81bd854c0ac103c3a0434d4d004dd192b9b45
+sources: []
+

data/README.md

@@ -1,13 +1,97 @@
 # tumblr
 
-Ruby wrapper and command line tool for the [Tumblr API](http://www.tumblr.com/docs/en/api). In case there wasn't enough of those. This one is powered by the [Weary](http://github.com/mwunsch/weary) gem.
+Ruby wrapper and command line tool for the [Tumblr API](http://www.tumblr.com/docs/en/api). In case there weren't enough of those already. This one is powered by the [Weary](http://github.com/mwunsch/weary) gem.
+
+[RDoc](http://rdoc.info/projects/mwunsch/tumblr) | [Gem](http://rubygems.org/gems/tumblr-rb) | [Metrics](http://getcaliper.com/caliper/project?repo=git%3A%2F%2Fgithub.com%2Fmwunsch%2Ftumblr.git)
 
 ## Installation
 
-	gem install tumblr-rb	
+	gem install tumblr-rb
+	
+## Getting Started
+
+Like [Jekyll](http://tom.preston-werner.com/jekyll/), and [Mustache](http://defunkt.github.com/mustache/), Tumblr gem will transform documents preceded by a [YAML](http://www.yaml.org/) frontmatter block.
+
+YAML frontmatter beings with `---` on a single line, followed by YAML, ending with another `---` on a single line, e.g.
+
+	---
+	type: quote
+	source: Billy Shakespeare
+	state: draft
+	tags: hamlet, shakespeare
+	---
+	"To be or not to be."
+	
+Understood YAML parameters are taken from the Tumblr API: http://www.tumblr.com/docs/en/api#api_write
+
+#### All Posts
+
+	type				regular, photo, link, quote, conversation, video, audio
+						will take a guess if ommitted.
+			
+	state				published, queue, draft, submission
+	
+	format				html or markdown
+	
+	tags				comma-separated list of tags
+	
+	date    			post date
+	
+	private				true if the post is private
+	
+	slug				A custom string to appear in the post's URL
+	
+	group				id for a secondary blog
+	
+	generator			description of the publishing application
+	
+	send-to-twitter		Twitter status update if the tumblelog has enabled it
+	
+	publish-on			if the post state is 'queue', publish on this date
+	
+#### Additional parameters for specific Post Types
+
+	regular			title
+	
+	photo			caption, click-through-url
+	
+	quote			source
+	
+	link			name, description
+	
+	conversation	title
+	
+	video			title, caption
+	
+	audio			caption
+	
+To publish to Tumblr, do this:
+
+	request = Tumblr.new(username, password).post(document)
+	request.perform do |response|
+		if response.success?
+			puts response.body 	# Returns the new post's id.
+		else
+			puts "Something went wrong: #{response.code} #{response.message}"
+		end
+	end
+
+## Goals
+
++ Full API coverage. Leave no method behind.
++ Well tested. Like a good Rubyist.
++ Obnoxiously simple CLI. *nix idioms are wonderful.
++ Kind-of-sort-of proof-of-concept for [Weary](http://github.com/mwunsch/weary).
+
+## TODO:
+
++ Make the CLI
++ Make the manpages for the CLI
++ More convenience methods for the Tumblr class.
++ File-uploading for Photos, Videos, Audio (needs to get into Weary)
 
 ## Copyright
 
 The Tumblr gem is Copyright (c) 2010 Mark Wunsch and is licensed under the [MIT License](http://creativecommons.org/licenses/MIT/). 
 
-Tumblr is Copyright (c) Tumblr, Inc. I am in no way affiliated with Tumblr.
+Tumblr is Copyright (c) Tumblr, Inc. The Tumblr gem is NOT affiliated with Tumblr.

data/Rakefile

@@ -21,7 +21,7 @@ begin
     gem.email = "mark@markwunsch.com"
     gem.homepage = "http://github.com/mwunsch/tumblr"
     gem.authors = ["Mark Wunsch"]
-    gem.add_dependency 'weary'
+    gem.add_dependency 'weary', '>= 0.7.1'
     gem.add_development_dependency "bundler", ">= 0.9.7"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
@@ -63,3 +63,8 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -I lib -r tumblr"
+end

data/lib/tumblr.rb

@@ -1,5 +1,150 @@
 require 'weary'
 
-module Tumblr
-  VERSION = "0.0.1"
+require 'tumblr/post'
+require 'tumblr/reader'
+require 'tumblr/writer'
+require 'tumblr/authenticator'
+
+class Tumblr
+  VERSION = "0.1.0"
+  GENERATOR = "The Tumblr Gem v#{VERSION}"
+  
+  def initialize(*credentials)
+    @credentials = {:email => credentials[0], :password => credentials[1]} unless credentials.blank?
+  end
+  
+  # Convenience method for Reader#read
+  def read(username, parameters={})
+    reader = !@credentials.blank? ? Reader.new(@credentials[:email],@credentials[:password]) : Reader.new
+    reader.read(username, parameters)
+  end
+  
+  # Post a document to Tumblr. If the document has a post-id, it will be edited.
+  def post(doc)
+    raise 'Requires an e-mail address and password' unless @credentials
+    tumblr_post = if doc.is_a?(Tumblr::Post)
+      doc.to_h
+    elsif doc.respond_to?(:keys)
+      doc
+    else
+      Tumblr.parse(doc).to_h
+    end
+    writer = Writer.new(@credentials[:email],@credentials[:password])
+    tumblr_post.has_key?(:'post-id') ? writer.edit(tumblr_post) : writer.write(tumblr_post)
+  end
+  
+  # Parse a post out of a string
+  def self.parse(doc)
+    document = {}
+    if doc =~ /^(\s*---(.*)---\s*)/m
+      document[:data] = YAML.load(Regexp.last_match[2].strip)
+      document[:body] = doc.sub(Regexp.last_match[1],'').strip
+    else
+      document[:data] = {'type' => infer_post_type(doc)}
+      document[:body] = doc
+    end
+    create_post document
+  end
+  
+  # Guess the Type of Post for a given documents
+  def self.infer_post_type(doc)
+    begin
+      url = URI.parse(doc)
+      if url.is_a?(URI::HTTP)
+        (url.host.include?('youtube.com') || url.host.include?('vimeo.com')) ? :video : :link
+      else
+        :regular
+      end
+    rescue URI::InvalidURIError
+      :regular
+    end
+  end
+      
+  # Map a post type key to its class
+  def self.map(key)
+    case key
+      when :regular
+        Post::Regular
+      when :photo
+        Post::Photo
+      when :quote
+        Post::Quote
+      when :link
+        Post::Link
+      when :conversation
+        Post::Conversation
+      when :video
+        Post::Video
+      when :audio
+        Post::Audio
+      else
+        raise "#{key} is not an understood Tumblr post type"
+    end
+  end
+  
+  private
+  
+  def self.create_post(document)
+    post_data = document[:data]
+    type = (post_data['type'] || infer_post_type(document[:body])).to_sym
+    post = case type
+      when :regular
+        create_regular document
+      when :photo
+        create_photo document
+      when :audio
+        create_audio document
+      when :quote, :link, :conversation, :video
+        create_simple type, document
+      else
+        raise "#{type} is not a recognized Tumblr post type."
+    end
+    basic_setup post, post_data
+  end
+  
+  def self.basic_setup(post, post_data)
+    %w(format state private slug date group generator).each do |basic|
+      post.send "#{basic}=".intern, post_data[basic] if post_data[basic]
+    end
+    %w(tags send-to-twitter publish-on).each do |attribute|
+      post.send attribute.gsub('-','_').intern, post_data[attribute] if post_data[attribute]
+    end
+    post
+  end
+  
+  def self.setup_params(post, data)
+    post_params = post.class.parameters.collect {|param| param.to_s.gsub('_','-') }
+    post_params.each do |param|
+      post.send "#{param.gsub('-','_')}=".intern, data[param] if data[param]
+    end
+    post
+  end
+    
+  def self.create_regular(doc)
+    data = doc[:data]
+    post = Tumblr::Post::Regular.new(data['post-id'])
+    post.body = doc[:body]
+    setup_params post, data
+  end
+  
+  def self.create_photo(doc)
+    data = doc[:data]
+    post = Tumblr::Post::Photo.new(data['post-id'])
+    post.source = doc[:body]
+    setup_params post, data
+  end
+  
+  def self.create_audio(doc)
+    data = doc[:data]
+    post = Tumblr::Post::Audio.new(data['post-id'])
+    post.externally_hosted_url = doc[:body]
+    setup_params post, data
+  end
+  
+  def self.create_simple(type, doc)
+    data = doc[:data]
+    post = map(type).new(doc[:body], data['post-id'])
+    setup_params post, data
+  end  
+  
 end

data/lib/tumblr/authenticator.rb

@@ -0,0 +1,15 @@
+class Tumblr
+  class Authenticator < Weary::Base
+    
+    def initialize(*credentials)
+      @defaults = {:email => credentials[0], :password => credentials[1]} unless credentials.blank?
+    end
+    
+    # http://www.tumblr.com/docs/en/api#authenticate
+    post :authenticate do |auth|
+      auth.url = 'http://www.tumblr.com/api/authenticate'
+      auth.requires = [:email, :password]
+    end
+    
+  end
+end

data/lib/tumblr/post.rb

@@ -0,0 +1,173 @@
+# An object that represents a post. From:
+# http://www.tumblr.com/docs/en/api#api_write
+class Tumblr
+  class Post
+    BASIC_PARAMS = [:date,:tags,:format,:group,:generator,:private,
+                    :slug,:state,:'send-to-twitter',:'publish-on']
+    POST_PARAMS = [:title,:body,:source,:caption,:'click-through-url',
+                   :quote,:name,:url,:description,:conversation,
+                   :embed,:'externally-hosted-url']
+    
+    def self.parameters(*attributes)
+      if !attributes.blank?
+        @parameters = attributes
+        attr_accessor *@parameters
+      end
+      @parameters
+    end
+    
+    attr_reader :type, :state, :post_id, :format
+    attr_accessor :slug, :date, :group, :generator
+    
+    def initialize(post_id = nil)
+      @post_id = post_id if post_id
+    end
+    
+    def private=(bool)
+      @private = bool ? true : false
+    end
+    
+    def private?
+      @private
+    end
+    
+    def tags(*post_tags)
+      @tags = post_tags.join(',') if !post_tags.blank?
+      @tags
+    end
+    
+    def state=(published_state)
+      allowed_states = [:published, :draft, :submission, :queue]
+      if !allowed_states.include?(published_state.to_sym)
+        raise "Not a recognized published state. Must be one of #{allowed_states.inspect}"
+      end
+      @state = published_state.to_sym
+    end
+    
+    def format=(markup)
+      markup_format = markup.to_sym
+      if markup_format.eql?(:html) || markup_format.eql?(:markdown)
+        @format = markup_format
+      end
+    end
+    
+    def send_to_twitter(status=false)
+      if status
+        if status.to_sym.eql?(:no)
+          @send_to_twitter = false
+        else
+          @send_to_twitter = status
+        end
+      end
+      @send_to_twitter
+    end
+    
+    def publish_on(pubdate=nil)
+      @publish_on = pubdate if state.eql?(:queue) && pubdate
+      @publish_on
+    end
+    
+    # Convert to a hash to be used in post writing/editing
+    def to_h
+      post_hash = {}
+      basics = [:post_id, :type, :date, :tags, :format, :group, :generator,
+                :slug, :state, :send_to_twitter, :publish_on]
+      params = basics.select {|opt| respond_to?(opt) && send(opt) }
+      params |= self.class.parameters.select {|opt| send(opt) } unless self.class.parameters.blank?
+      params.each { |key| post_hash[key.to_s.gsub('_','-').to_sym] = send(key) } unless params.empty?
+      post_hash[:private] = 1 if private?
+      post_hash
+    end
+    
+    # Publish this post to Tumblr
+    def write(email, password)
+      Writer.new(email,password).write(to_h)
+    end
+    
+    def edit(email, password)
+      Writer.new(email,password).edit(to_h)
+    end
+    
+    def delete(email, password)
+      Writer.new(email,password).delete(to_h)
+    end
+    
+    # Write to Tumblr and set state to Publish
+    def publish_now(email, password)
+      self.state = :published
+      return edit(email,password) if post_id
+      write(email,password)
+    end
+    
+    # Save as a draft
+    def save_as_draft(email, password)
+      self.state = :draft
+      return edit(email,password) if post_id
+      write(email,password)
+    end
+    
+    # Adds to Queue. Pass an additional date to publish at a specific date.
+    def add_to_queue(email, password, pubdate = nil)
+      self.state = :queue
+      self.publish_on(pubdate) if pubdate
+      return edit(email,password) if post_id
+      write(email,password)
+    end
+    
+    # Convert post to a YAML representation
+    def to_yaml
+      post = {}
+      post['data'] = post_data
+      post['body'] = to_h[post_body].to_s
+      YAML.dump(post)
+    end
+    
+    # Convert post to a string for writing to a file
+    def to_s
+      post_string = YAML.dump(post_data)
+      post_string += "---\x0D\x0A"
+      post_string += YAML.load(to_yaml)['body']
+      post_string
+    end
+    
+    private
+    
+    def post_data
+      data = {}
+      to_h.each_pair do |key,value|
+        data[key.to_s] = value.to_s
+      end
+      data.reject! {|key,value| key.eql?(post_body.to_s) }
+      data
+    end
+    
+    def post_body
+      case type
+        when :regular
+          :body
+        when :photo
+          :source
+        when :quote
+          :quote
+        when :link
+          :url
+        when :conversation
+          :conversation
+        when :video
+          :embed
+        when :audio
+          :'externally-hosted-url'
+        else
+          raise "#{type} is not a recognized Tumblr post type."
+      end
+    end
+  end
+end
+
+require 'tumblr/post/regular'
+require 'tumblr/post/photo'
+require 'tumblr/post/quote'
+require 'tumblr/post/link'
+require 'tumblr/post/conversation'
+require 'tumblr/post/video'
+require 'tumblr/post/audio'