zomgrss 1.0.0

data/.document

@@ -0,0 +1,3 @@
+README.markdown
+lib/**/*.rb
+LICENSE

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+examples/sample.db

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Federico Builes
+
+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/README.markdown

@@ -0,0 +1,170 @@
+ZOMGRSS
+=======
+ZOMGRSS is a Ruby gem to create RSS feeds from your Ruby collections.
+
+Installation
+-----------
+
+     $ gem install zomgrss
+
+Example
+-------
+
+     class BlogPost < ActiveRecord::Base
+       rss_me
+     end
+
+     print BlogPost.to_rss
+
+     # => (no line-breaks in original)
+     <?xml version="1.0" encoding="UTF-8"?>
+     <rss version="2.0">
+       <channel>
+         <title>Your blog!</title>
+         <description>A nice description of your emo posts</description>
+         <link>http://example.com/blog</link>
+         <item>
+           <title>My first post</title>
+           <link isPermaLink="false">http://example.com/blog/1</link>
+           <description>Isnt this super interesting?</description>
+           <pubDate>Sat, 22 May 2010 21:38:17 -0500</pubDate>
+           <guid>1@http://exmaple.com/blog/</guid>
+         </item>
+         <item>
+           <title>My second post</title>
+           <link isPermaLink="false">http://example.com/blog/2</link>
+           <description>I wish my lawn was emo so I could stop doing silly jokes</description>
+           <pubDate>Sat, 22 May 2010 21:38:17 -0500</pubDate>
+           <guid>2@http://exmaple.com/blog/</guid>
+         </item>
+       </channel>
+     </rss>
+
+You can see more examples in the `examples/` folder.
+
+Usage
+-----
+For a basic dose of ZOMGRSS just call `rss_me` in your class and then call `Class.to_rss`. Example:
+
+     class BlogPost
+       include DataMapper::Resource
+       rss_me
+
+       property :id, Serial
+       property :title, String, :required => true
+       property :body, Text, :required => true
+       property :created_at, DateTime
+     end
+
+     BlogPost.to_rss  # => returns the RSS feed for all the objects in BlogPost.
+
+ZOMGRSS expects your class to have four basic attributes: `id`, `title`, `body` and `created_at`. These
+are used to populate the RSS title, description, GUID and pubDate fields of each item in your feed. Users
+of DataMapper and ActiveRecord should have instant access to the `id` and `created_at` fields. Read
+Custom Options to find out how to modify these.
+
+Your RSS feed also include three important fields:
+
+* `title`: Your feed's title (i.e. _Brian's Emo Blog_)
+* `description`: A description of your feed (i.e. _I'm Brian and I like to cut myself._)
+* `base_url`: A base URL for your feed (i.e. _http://blog.emobrian.com/_)
+
+To set these fields just call the `rss_options` class method:
+
+     BlogPost.rss_options[:title] = "My new not emo blog"
+     BlogPost.rss_options[:description] = "Emo no more, I'm HipsterBrian now"
+     BlogPost.rss_options[:base_url] = "http://blog.hipsterbrian.com/"
+
+You'll also want to modify the `link_format` option, which specifies the format of the links used
+in your site. A typical site will use the same URL for every item, changing only the ID of the
+post. An example of the link format for Brian's Hipster blog would be:
+
+      BlogPost.rss_options[:link_format] = "http://blog.hipsterbrian.com/:id"
+
+ZOMGRSS would replace `:id` with the object's ID field.
+
+
+Custom Options
+---------------
+### Custom Method Names
+
+If your class uses different names for the necessary methods (`title`, `body` and `created_at`) you
+can set them in the rss_options. If you had the following class:
+
+     class BlogPost
+       include DataMapper::Resource
+       rss_me
+
+       property :id, Serial
+       property :title_text, String, :required => true
+       property :description, Text, :required => true
+       property :created, DateTime
+     end
+
+You'd have to set the following options:
+
+     BlogPost.rss_options[:title_method] = :title_text
+     BlogPost.rss_options[:body_method] = :description
+     BlogPost.rss_options[:date_method] = :created
+
+And then call the `to_rss` class method as you normally would:
+
+     BlogPost.to_rss
+
+
+### Custom Finders
+
+Sometimes you'll want to create an RSS feed of only certain objects. By default ZOMGRSS uses `:all`
+as the finder, meaning it will call YourClass.all to find the records to be included in the feed. If
+you want to use a different finder you can modify it through the `:finder` option:
+
+     class BlogPost < ActiveRecord::Base
+       rss_me
+
+       # return only 5 records
+       named_scope :only_five, { :limit => 5 }
+     end
+
+     BlogPost.rss_options[:finder] = :only_five
+     BlogPost.to_rss  # => Will create a feed with only 5 items.
+
+You can also pass options to your custom finders to use more complex queries:
+
+     class BlogPost < ActiveRecord::Base
+       rss_me
+
+       # returns 'max-min' records
+       named_scope :limit, lambda { |max, min| { :limit => (max - min) } }
+     end
+
+     BlogPost.rss_options[:finder] = :limit
+     BlogPost.rss_options[:finder_options] = [10,5]
+     BlogPost.to_rss  # => Creates a feed with only 5 items.
+
+### GUIDs
+
+Every RSS item needs to have an unique identifier. The current format used by ZOMGRSS follows the
+Movable Type convention: "id@http://example.com" (as in _342@http://blog.hipsterbrian.com_). If you
+need to change this you can set a custom GUID format:
+
+     BlogPost.rss_options[:guid_format] = "http://blog.hipsterbrian.com/unique/:id"
+
+ZOMGRSS will replace the `:id` in the format for the object's ID.
+
+
+TODO
+----
+* Allow the user to set global default options. Right now you'll have to set the default options for
+each new RSS feed you want to create.
+* Support for Atom?
+* Allow lambdas instead of methods in rss_options (useful to return a text snippet of a field).
+* Create Rubygem (iknorite?)
+* Generate static .xml files.
+
+Most of these can be easily implemented but I haven't needed them so far. If you'd like to see them
+included please let me know through an Issue in the [Github Tracker](http://github.com/febuiles/zomgrss/issues).
+
+Contact
+--------
+* **Email**: federico@mheroin.com
+* **Issues**: [Github Tracker](http://github.com/febuiles/zomgrss/issues)

data/Rakefile

@@ -0,0 +1,35 @@
+require 'rake'
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "zomgrss"
+    gem.summary = "Create RSS feeds from Ruby collections."
+    gem.description = "Create RSS feeds from Ruby collections."
+    gem.email = "federico@mheroin.com"
+    gem.homepage = "http://github.com/febuiles/zomgrss"
+    gem.authors = ["Federico Builes"]
+    gem.add_development_dependency "builder"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/*_spec.rb']
+end
+
+desc 'Default: run specs.'
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "zomgrss #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/examples/active_record_sample.rb

@@ -0,0 +1,23 @@
+require 'active_record'
+require File.join(File.dirname(__FILE__), '..', '/lib/zomgrss.rb')
+
+# Run the do.rb example first to create the samples database.
+ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => "sample.db")
+
+class BlogPost < ActiveRecord::Base
+  rss_me
+  named_scope :limit, lambda { |max, min| { :limit => (max - min) } }
+end
+
+# Set options for the RSS generator.
+BlogPost.rss_options[:title] = "My new not emo blog"
+BlogPost.rss_options[:description] = "Emo no more, I'm HipsterBrian now"
+BlogPost.rss_options[:base_url] = "http://blog.hipsterbrian.com/"
+BlogPost.rss_options[:link_format] = "http://blog.hipsterbrian.com/:id"
+
+# Use a custom finder for items
+BlogPost.rss_options[:finder] = :limit
+BlogPost.rss_options[:finder_options] = [10, 9]
+
+
+print BlogPost.to_rss

data/examples/datamapper_sample.rb

@@ -0,0 +1,33 @@
+require 'dm-core'
+require 'dm-timestamps'
+require File.join(File.dirname(__FILE__), '..', '/lib/zomgrss.rb')
+
+DataMapper::setup(:default, "sqlite3://#{Dir.pwd}/sample.db")
+
+class BlogPost
+  include DataMapper::Resource
+  rss_me
+
+  property :id, Serial
+  property :title, String, :required => true
+  property :body, Text, :required => true
+  property :created_at, DateTime
+end
+
+DataMapper.auto_upgrade!
+
+# Create some sample posts...
+BlogPost.create(:title => "My first post", :body => "Isnt this super interesting?")
+BlogPost.create(:title => "My second post", :body => "I wish my lawn was emo so I could stop doing silly jokes")
+
+# Set default options for the RSS generator.
+BlogPost.rss_options[:title] = "My new not emo blog"
+BlogPost.rss_options[:description] = "Emo no more, I'm HipsterBrian now"
+BlogPost.rss_options[:base_url] = "http://blog.hipsterbrian.com/"
+BlogPost.rss_options[:link_format] => "http://blog.hipsterbrian.com/:id"
+
+# This is the resulting RSS.
+print BlogPost.to_rss
+
+
+

data/lib/zomgrss.rb

@@ -0,0 +1,60 @@
+require 'builder'
+require 'time'
+
+def rss_me
+  self.extend ZOMGRSS
+end
+
+module ZOMGRSS
+  def to_rss
+    finder = rss_options[:finder]
+    finder_options = rss_options[:finder_options]
+
+    if finder_options
+      items = self.send(finder, *finder_options)
+    else
+      items = self.send(finder)
+    end
+
+    xml = Builder::XmlMarkup.new
+
+    xml.instruct! :xml, :version => '1.0'
+    xml.rss :version => "2.0" do
+      xml.channel do
+        xml.title rss_options[:title]
+        xml.description rss_options[:description]
+        xml.link rss_options[:base_url]
+
+        items.each do |item|
+          xml.item do
+            xml.title item.send(rss_options[:title_method])
+            xml.link(rss_options[:link_format].gsub(":id", item.id.to_s), :isPermaLink => false)
+            xml.description item.send(rss_options[:body_method])
+            xml.pubDate Time.parse(item.send(rss_options[:date_method]).to_s).rfc822()
+            xml.guid rss_options[:guid_format].gsub(":id", item.id.to_s)
+          end
+        end
+      end
+    end
+  end
+
+  def rss_options(rss_options={ })
+    @rss_opts = (@rss_opts || self.default_rss_options).merge(rss_options)
+  end
+
+  protected
+  def default_rss_options
+    {
+      :title => "Your blog!",
+      :description => "A nice description of your emo posts",
+      :base_url => "http://example.com/blog",
+      :body_method => :body,
+      :title_method => :title,
+      :link_format => "http://example.com/blog/:id",
+      :date_method => :created_at,
+      :guid_format => ":id@http://example.com/blog/", # works nicely when switching domains.
+      :finder => :all,
+      :finder_options => nil
+    }
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,4 @@
+--colour
+--format progress
+--loadby mtime
+--reverse

data/spec/spec_helper.rb

@@ -0,0 +1,40 @@
+require File.join(File.dirname(__FILE__), '..', '/lib/zomgrss.rb')
+require 'spec'
+require 'nokogiri'
+
+class SuperSomething
+  attr_reader :id, :title, :body, :created_at
+
+  rss_me
+
+  def self.all
+    self.some(3)
+  end
+
+  def initialize(date)
+    @id = 4                    # chosen by a fair dice roll, guaranteed to be random.
+    @title = "SuperTitle!"
+    @body = '<p><img src="http://mheroin.com/img.jpg" />SuperBody!!</p>'
+    @created_at = date
+  end
+
+  def self.some(lim=1, date=Time.utc(1987, "apr", 4, 2, 0, 0))
+    Array.new(lim, SuperSomething.new(date))
+  end
+
+  def fecha; @created_at; end
+  def titulo; @title; end
+  def cuerpo; @body; end
+end
+
+def base_url
+  "http://mheroin.com"
+end
+
+def default_options
+  SuperSomething.send(:default_rss_options)
+end
+
+def parse_feed
+  @feed = Nokogiri::XML(SuperSomething.to_rss)
+end

data/spec/zomgrss_spec.rb

@@ -0,0 +1,156 @@
+require "spec_helper"
+
+describe "Installation" do
+  it "is done by calling 'rss_me'" do
+    lambda { class Throwaway; rss_me; end }.should_not raise_error
+  end
+
+  it "provides .to_rss to the class" do
+    c = class Throwaway; rss_me; end
+    c.should respond_to(:to_rss)
+  end
+end
+
+describe "Options" do
+  it "provides default options if there are none set" do
+    SuperSomething.rss_options.should == default_options
+  end
+
+  it "adds options to the current options if they exist" do
+    SuperSomething.rss_options(:title => "My new title")
+    SuperSomething.rss_options.should == default_options.merge(:title => "My new title")
+  end
+
+  it "includes a feed title" do
+    SuperSomething.rss_options[:title].should_not be_nil
+  end
+
+  it "includes a feed description" do
+    SuperSomething.rss_options[:description].should_not be_nil
+  end
+
+  it "includes a feed base URL" do
+    SuperSomething.rss_options[:base_url].should_not be_nil
+  end
+
+  it "includes a custom title method, defaulted to :title" do
+    SuperSomething.rss_options[:title_method].should == :title
+  end
+
+  it "includes a custom body method, defaulted to :body" do
+    SuperSomething.rss_options[:body_method].should == :body
+  end
+
+  it "includes a link format for the feed items" do
+    SuperSomething.rss_options[:link_format].should_not be_nil
+  end
+
+  it "includes a date field for the feed items, defaulted to :created_at" do
+    SuperSomething.rss_options[:date_method].should == :created_at
+  end
+
+  it "includes a GUID format for the feed items" do
+    SuperSomething.rss_options[:guid_format].should_not be_nil
+  end
+
+  it "includes a custom finder method, defaulted to :all" do
+    SuperSomething.rss_options[:finder].should == :all
+  end
+
+  it "includes the options for the custom finder method, defaulted to nil" do
+    SuperSomething.rss_options[:finder_options].should be_nil
+  end
+end
+
+describe "ZOMGRSS.to_rss" do
+  before :each do
+    parse_feed
+  end
+
+  after :each do
+    SuperSomething.rss_options(default_options)
+  end
+
+  it "returns a a well formed RSS feed" do
+    @feed.errors.should be_empty
+  end
+
+  it "uses the correct feed base data" do
+    @feed.at_css("channel title").text.should == default_options[:title]
+    @feed.at_css("channel description").text.should == default_options[:description]
+    @feed.at_css("channel link").text.should == default_options[:base_url]
+  end
+
+  it "replaces :link_format with the actual item link" do
+    expected = default_options[:link_format].gsub(":id", "4")
+    @feed.at_css("channel item link").text.should == expected
+  end
+
+  it "uses :created_at or a custom field for the item's date" do
+    expected = "Sat, 04 Apr 1987 02:00:00 -0000"
+    @feed.at_css("channel item pubDate").text.should == expected
+
+    SuperSomething.rss_options(:date_method => :fecha)
+    @feed.at_css("channel item pubDate").text.should == expected
+  end
+
+  it "generates a MovableType-like GUID from the items " do
+    expected = default_options[:guid_format].gsub(":id", "4")
+    @feed.at_css("channel item guid").text.should == expected
+  end
+
+  it "can use a custom GUID format" do
+    expected = "http://something.com/4"
+
+    SuperSomething.rss_options[:guid_format] = "http://something.com/:id"
+    parse_feed
+    @feed.at_css("channel item guid").text.should == expected
+  end
+
+  it "can use a custom finder to fetch the objects" do
+    @feed.css("channel item").length.should == 3
+
+    SuperSomething.rss_options[:finder] = :some
+    parse_feed
+    @feed.css("channel item").length.should == 1
+  end
+
+  it "can pass custom options to the finder" do
+    @feed.css("channel item").length.should == 3
+
+    SuperSomething.rss_options[:finder] = :some
+    SuperSomething.rss_options[:finder_options] = 2
+    parse_feed
+    @feed.css("channel item").length.should == 2
+  end
+
+  it "explodes custom finder options" do
+    @feed.css("channel item").length.should == 3
+
+    SuperSomething.rss_options[:finder] = :some
+    SuperSomething.rss_options[:finder_options] = [2, Time.utc(1987, "may", 4, 2, 0, 0)]
+    parse_feed
+    @feed.css("channel item").length.should == 2
+    @feed.at_css("channel item pubDate").text.should == "Mon, 04 May 1987 02:00:00 -0000"
+  end
+
+  it "supports custom title methods" do
+    @feed.at_css("channel item title").text.should == "SuperTitle!"
+
+    SuperSomething.rss_options[:title_method] = :titulo
+    parse_feed
+    @feed.at_css("channel item title").text.should == "SuperTitle!"
+  end
+
+  it "supports custom body methods" do
+    @feed.at_css("channel item description").text.should == '<p><img src="http://mheroin.com/img.jpg" />SuperBody!!</p>'
+
+    SuperSomething.rss_options[:body_method] = :cuerpo
+    parse_feed
+    @feed.at_css("channel item description").text.should == '<p><img src="http://mheroin.com/img.jpg" />SuperBody!!</p>'
+  end
+
+  it "uses a GUID with isPermaLink=false" do
+    @feed.at_css("channel item link").attributes["isPermaLink"].text.should == "false"
+  end
+end

data/zomgrss.gemspec

@@ -0,0 +1,59 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{zomgrss}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Federico Builes"]
+  s.date = %q{2010-05-22}
+  s.description = %q{Create RSS feeds from Ruby collections.}
+  s.email = %q{federico@mheroin.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.markdown"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "examples/active_record_sample.rb",
+     "examples/datamapper_sample.rb",
+     "lib/zomgrss.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb",
+     "spec/zomgrss_spec.rb",
+     "zomgrss.gemspec"
+  ]
+  s.homepage = %q{http://github.com/febuiles/zomgrss}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Create RSS feeds from Ruby collections.}
+  s.test_files = [
+    "spec/spec_helper.rb",
+     "spec/zomgrss_spec.rb",
+     "examples/active_record_sample.rb",
+     "examples/datamapper_sample.rb"
+  ]
+
+  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_development_dependency(%q<builder>, [">= 0"])
+    else
+      s.add_dependency(%q<builder>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<builder>, [">= 0"])
+  end
+end
+

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification 
+name: zomgrss
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Federico Builes
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-22 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: builder
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: Create RSS feeds from Ruby collections.
+email: federico@mheroin.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- examples/active_record_sample.rb
+- examples/datamapper_sample.rb
+- lib/zomgrss.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- spec/zomgrss_spec.rb
+- zomgrss.gemspec
+has_rdoc: true
+homepage: http://github.com/febuiles/zomgrss
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Create RSS feeds from Ruby collections.
+test_files: 
+- spec/spec_helper.rb
+- spec/zomgrss_spec.rb
+- examples/active_record_sample.rb
+- examples/datamapper_sample.rb