mapricot 0.0.4

data/History.txt

@@ -0,0 +1,23 @@
+== 0.0.1 2009-03-06
+
+First gem!
+
+== 0.0.2 2009-03-17
+
+Nokogiri and Libxml support.
+
+Select the parser to use by setting Mapricot.parser as follows:
+
+Mapricot.parser = :nokogiri
+Mapricot.parser = :libxml
+Mapricot.parser = :hpricot
+
+Hpricot will be used by default
+
+== 0.0.3 2009-03-22
+
+Can parse from url with Nokogiri
+
+== 0.0.4 2009-05-27
+
+Ditched rspec, now fully tested with test unit

data/License.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2009 Louis Zell <lzell11@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/README.rdoc

@@ -0,0 +1,119 @@
+== Mapricot
+
+XML to object mapper with an interface similar to ActiveRecord associations.
+
+
+== Install
+
+sudo gem install mapricot
+
+
+== Example Usage
+
+==== Super Simple
+  require 'mapricot'
+  
+  simple_xml = %(
+    <user>
+      <id>1</name>
+      <name>Bob</name>
+      <pet>cat</pet>
+      <pet>dog</pet>
+    </user>
+  )
+
+  class User < Mapricot::Base
+    has_one   :id,    :integer
+    has_one   :name,  :string
+    has_many  :pets,  :string
+  end
+
+  user = User.new(:xml => simple_xml)
+  puts user.id                # => 1
+  puts user.id.class          # => Fixnum
+  puts user.name              # => Bob
+  puts user.pets.class        # => Array
+  puts user.pets.join(", ")   # => cat, dog
+
+
+==== A little more realistic
+  require 'mapricot'
+  
+  xml = %(
+    <user>
+      <id>2</name>
+      <name>Sally</name>
+      <location code="ny123">
+        <city>New York</city>
+        <state>NY</state>
+      </location>
+      <hobby>
+        <description>Skiing</description>
+        <number_of_years>2</number_of_years>
+      </hobby>
+      <hobby>
+        <description>Hiking</description>
+        <number_of_years>3</number_of_years>
+      </hobby>
+    </user>
+  )
+
+
+  class User < Mapricot::Base
+    has_one   :id,        :integer
+    has_one   :name       # Tag type will default to :string
+    has_many  :pets
+    has_one   :location,  :xml
+    has_many  :hobbies,   :xml
+  end
+
+  class Location < Mapricot::Base
+    has_attribute :code
+    has_one       :city
+    has_one       :state
+  end
+
+  class Hobby < Mapricot::Base
+    has_one :description,     :string
+    has_one :number_of_years, :integer
+  end
+
+  user = User.new(:xml => xml)
+  puts user.name            # => Sally
+  puts user.pets.inspect    # => []
+  puts user.location.class  # => Location
+  puts user.location.city   # => New York
+  puts user.location.state  # => NY
+  puts user.location.code   # => ny123
+  puts user.hobbies.class         # => Array
+  puts user.hobbies.first.class   # => Hobby
+
+  user.hobbies.each do |hobby|
+    puts "#{hobby.description} for #{hobby.number_of_years} years"
+  end
+  # => Skiing for 2 years
+  # => Hiking for 3 years
+  
+== Usage, TODO: fix this garbage
+
+Your classes should inherit from Mapricot::Base, which provides the class methods 
+* has_one(name, type, opts = {})
+* has_many(name, type, opts = {})
+* has_attribute(name)
+  
+When you instantiate a Mapricot::Base object, you can pass it a string of xml:
+  class MapMe < Mapricot::Base
+  end
+  
+  MapMe.new :xml => "<some_stuff>...</some_stuff>"
+
+Or a url:
+  
+  MapMe.new :url => "http://some_url"
+  
+== Credits
+
+Named after why the luck stiff's Hpricot, which made this possible.
+
+
+Copyright (c) 2009 Lou Zell, released under the MIT license

data/benchmark/benchmarks.rb

@@ -0,0 +1,127 @@
+require File.expand_path(File.dirname(__FILE__) + "/../lib/mapricot")
+require 'benchmark'
+
+last_fm_example = %(<?xml version="1.0" encoding="utf-8"?>
+<events>
+<event>
+  <id>895664</id>
+  <title>Lydia</title>
+  <artists>
+    <artist>Lydia</artist>
+    <artist>Black Gold</artist>
+
+    <headliner>Lydia</headliner>
+  </artists>
+  <venue>
+    <name>Mercury Lounge</name>
+    <location>
+      <city>New York</city>
+      <country>United States</country>
+
+      <street>217 East Houston Street</street>
+      <postalcode>10002</postalcode>
+              <timezone>EST</timezone>
+
+          </location>
+    <url>http://www.last.fm/venue/8899833</url>
+  </venue>
+  <startDate>Thu, 05 Mar 2009</startDate>
+  <startTime>18:30</startTime>
+  <description><![CDATA[<div class="bbcode">On Sale Fri 1/16 at Noon<br />
+21+<br />
+$10<br />
+Doors 6:30pm/ Show 7:30pm</div>]]></description>
+  <image size="small">http://userserve-ak.last.fm/serve/34/9158303.jpg</image>
+
+  <image size="medium">http://userserve-ak.last.fm/serve/64/9158303.jpg</image>
+  <image size="large">http://userserve-ak.last.fm/serve/126/9158303.jpg</image>
+   <attendance>7</attendance>
+   <reviews>0</reviews>
+   <tag>lastfm:event=895664</tag>  
+  <url>http://www.last.fm/event/895664</url>
+
+</event>
+<event>
+  <id>924763</id>
+  <title>Stars Like Fleas</title>
+  <artists>
+    <artist>Stars Like Fleas</artist>
+
+    <artist>Frances</artist>
+    <artist>twi the humble feather</artist>
+    <artist>La Strada</artist>
+    <headliner>Stars Like Fleas</headliner>
+  </artists>
+  <venue>
+    <name>Music Hall of Williamsburg</name>
+
+    <location>
+      <city>Brooklyn, NY</city>
+      <country>United States</country>
+      <street>66 North 6th Street</street>
+      <postalcode>11211</postalcode>
+              <timezone>EST</timezone>
+          </location>
+    <url>http://www.last.fm/venue/8851989</url>
+  </venue>
+  <startDate>Thu, 05 Mar 2009</startDate>
+
+  <startTime>19:00</startTime>
+  <description><![CDATA[<div class="bbcode">Doors 7 p.m. / Show 8 p.m.<br />
+$10 advance / $12 day of show<br />
+18+<br />
+<br />
+On sale Wed. 2/4 at noon</div>]]></description>
+  <image size="small">http://userserve-ak.last.fm/serve/34/3598785.jpg</image>
+  <image size="medium">http://userserve-ak.last.fm/serve/64/3598785.jpg</image>
+  <image size="large">http://userserve-ak.last.fm/serve/126/3598785.jpg</image>
+   <attendance>1</attendance>
+
+   <reviews>0</reviews>
+   <tag>lastfm:event=924763</tag>  
+  <url>http://www.last.fm/event/924763</url>
+</event>
+</events>
+
+)
+
+
+class Response < Mapricot::Base
+  has_many :events, :xml
+end
+
+class Event < Mapricot::Base
+  has_one :id,              :integer
+  has_one :title,           :string
+  has_one :artist_group,    :xml,       :tag_name => "artists"
+  has_one :venue,           :xml
+end
+
+class ArtistGroup < Mapricot::Base
+  has_many  :artists,       :string
+  has_one   :headliner,     :string
+end
+
+class Venue < Mapricot::Base
+  has_one   :name,          :string
+end
+
+lfm = Response.new(:xml => last_fm_example)
+
+
+n = 200
+Benchmark.bm do |x|
+  x.report("hpricot") {
+    Mapricot.parser = :hpricot;
+    n.times { lfm = Response.new(:xml => last_fm_example) }
+  }
+  x.report("libxml") {
+    Mapricot.parser = :libxml; 
+    n.times { lfm = Response.new(:xml => last_fm_example) }
+  }
+  x.report("nokogiri") {
+    Mapricot.parser = :nokogiri; 
+    n.times { lfm = Response.new(:xml => last_fm_example) }
+  }
+  
+end

data/examples/facebook_api.rb

@@ -0,0 +1,86 @@
+require 'rubygems'
+require File.expand_path(File.dirname(__FILE__) + "/../lib/mapricot")
+
+# Using a Facebook example
+# This xml is taken straight from here: http://wiki.developers.facebook.com/index.php/Users.getInfo
+# Note, libxml does not like this for some reason:
+# <users_getInfo_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd" list="true">
+# So 'xmlns="http://api.facebook.com/1.0/"' has been stripped from tag
+# Because of this, for real requests we will have to use hpricot or nokogiri
+FACEBOOK_XML = %(<?xml version="1.0" encoding="UTF-8"?>
+  <users_getInfo_response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd" list="true">
+    <user>
+      <uid>8055</uid>
+      <about_me>This field perpetuates the glorification of the ego. Also, it has a character limit.</about_me>
+      <activities>Here: facebook, etc. There: Glee Club, a capella, teaching.</activities>
+      <affiliations list="true">
+        <affiliation>
+          <nid>50453093</nid>
+          <name>Facebook Developers</name>
+          <type>work</type>
+          <status/>
+          <year/>
+        </affiliation>
+      </affiliations>
+      <birthday>November 3</birthday>
+      <books>The Brothers K, GEB, Ken Wilber, Zen and the Art, Fitzgerald, The Emporer's New Mind, The Wonderful Story of Henry Sugar</books>
+      <current_location>
+        <city>Palo Alto</city>
+        <state>CA</state>
+        <country>United States</country>
+        <zip>94303</zip>
+      </current_location> 
+    </user>
+  </users_getInfo_response>
+)
+
+
+class UsersGetInfoResponse < Mapricot::Base
+  has_many :users,    :xml
+end
+
+class User < Mapricot::Base
+  has_one :uid,               :integer
+  has_one :about_me,          :string
+  has_one :activities,        :string
+  has_one :affiliation_list,  :xml,     :tag_name => "affiliations"   # this is cumbersome, do something about this
+  has_one :birthday,          :string
+  has_one :current_location,  :xml
+end
+
+class AffiliationList < Mapricot::Base
+  has_many :affiliations,     :xml
+end
+
+class Affiliation < Mapricot::Base
+  has_one :nid,     :integer
+  has_one :name,    :string
+  has_one :type,    :string
+  has_one :status,  :string
+  has_one :year,    :integer
+end
+
+class CurrentLocation < Mapricot::Base
+  has_one :city,    :string
+  has_one :state,   :string
+  has_one :country, :string
+  has_one :zip,     :integer
+end
+
+
+response = UsersGetInfoResponse.new(:xml => FACEBOOK_XML)
+puts response.users.class # => Array
+puts response.users.size # => 1
+
+user = response.users.first
+
+puts user.uid # => 8055
+puts user.activities # => "Here: facebook, etc. There: Glee Club, a capella, teaching."
+puts user.current_location.city # => "Palo Alto"
+puts user.current_location.state # => "CA"
+puts user.current_location.country # => "United States"
+puts user.current_location.zip  # => 94303
+
+# need to remove redundancy here:
+puts user.affiliation_list.affiliations.first.name   # => "Facebook Developers"
+puts user.affiliation_list.affiliations.first.nid   # => 50453093  

data/examples/lastfm_api.rb

@@ -0,0 +1,42 @@
+# Get events in nyc with:
+# http://ws.audioscrobbler.com/2.0/?method=geo.getevents&city=new+york&api_key=YOUR_API_KEY_HERE
+
+# The point of this is to demonstrate mapping xml from a real api response.
+# The only difference is you instantiate with:
+# Response.new(:url => "http://someurl")
+# instead of:
+# Response.new(:xml => "some string of xml")
+
+# If you do not have an API key, see examples/lastfm_api_no_request.rb
+require 'rubygems'
+require File.expand_path(File.dirname(__FILE__) + "/../lib/mapricot")
+
+class Response < Mapricot::Base
+  has_many :events,   :xml
+end
+
+class Event < Mapricot::Base
+  has_one :title
+  has_one :venue,   :xml
+end
+
+class Venue < Mapricot::Base
+  has_one :name
+  has_one :location, :xml
+end
+
+class Location < Mapricot::Base
+  has_one :city
+  has_one :country
+  has_one :street
+  has_one :postalcode,  :integer
+end
+
+response = Response.new(:url => "http://ws.audioscrobbler.com/2.0/?method=geo.getevents&city=new+york&api_key=#{YOUR_API_KEY_HERE}")
+
+response.events.each do |event|
+  puts "-------------"
+  puts event.title
+  puts event.venue.name
+  puts event.venue.location.city
+end

data/examples/lastfm_api_no_request.rb

@@ -0,0 +1,127 @@
+require 'rubygems'
+require File.expand_path(File.dirname(__FILE__) + "/../lib/mapricot")
+
+
+last_fm_example = %(
+<?xml version="1.0" encoding="utf-8"?>
+<lfm status="ok">
+<events location="New York, United States" page="1" totalpages="92" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#" total="917">
+<event>
+  <id>895664</id>
+  <title>Lydia</title>
+  <artists>
+    <artist>Lydia</artist>
+    <artist>Black Gold</artist>
+
+    <headliner>Lydia</headliner>
+  </artists>
+  <venue>
+    <name>Mercury Lounge</name>
+    <location>
+      <city>New York</city>
+      <country>United States</country>
+
+      <street>217 East Houston Street</street>
+      <postalcode>10002</postalcode>
+      <geo:point>
+         <geo:lat>40.722024</geo:lat>
+         <geo:long>-73.98682</geo:long>
+      </geo:point>
+              <timezone>EST</timezone>
+
+          </location>
+    <url>http://www.last.fm/venue/8899833</url>
+  </venue>
+  <startDate>Thu, 05 Mar 2009</startDate>
+  <startTime>18:30</startTime>
+  <description><![CDATA[<div class="bbcode">On Sale Fri 1/16 at Noon<br />
+21+<br />
+$10<br />
+Doors 6:30pm/ Show 7:30pm</div>]]></description>
+  <image size="small">http://userserve-ak.last.fm/serve/34/9158303.jpg</image>
+
+  <image size="medium">http://userserve-ak.last.fm/serve/64/9158303.jpg</image>
+  <image size="large">http://userserve-ak.last.fm/serve/126/9158303.jpg</image>
+   <attendance>7</attendance>
+   <reviews>0</reviews>
+   <tag>lastfm:event=895664</tag>  
+  <url>http://www.last.fm/event/895664</url>
+
+</event>
+<event>
+  <id>924763</id>
+  <title>Stars Like Fleas</title>
+  <artists>
+    <artist>Stars Like Fleas</artist>
+
+    <artist>Frances</artist>
+    <artist>twi the humble feather</artist>
+    <artist>La Strada</artist>
+    <headliner>Stars Like Fleas</headliner>
+  </artists>
+  <venue>
+    <name>Music Hall of Williamsburg</name>
+
+    <location>
+      <city>Brooklyn, NY</city>
+      <country>United States</country>
+      <street>66 North 6th Street</street>
+      <postalcode>11211</postalcode>
+      <geo:point>
+         <geo:lat>40.719308</geo:lat>
+
+         <geo:long>-73.961607</geo:long>
+      </geo:point>
+              <timezone>EST</timezone>
+          </location>
+    <url>http://www.last.fm/venue/8851989</url>
+  </venue>
+  <startDate>Thu, 05 Mar 2009</startDate>
+
+  <startTime>19:00</startTime>
+  <description><![CDATA[<div class="bbcode">Doors 7 p.m. / Show 8 p.m.<br />
+$10 advance / $12 day of show<br />
+18+<br />
+<br />
+On sale Wed. 2/4 at noon</div>]]></description>
+  <image size="small">http://userserve-ak.last.fm/serve/34/3598785.jpg</image>
+  <image size="medium">http://userserve-ak.last.fm/serve/64/3598785.jpg</image>
+  <image size="large">http://userserve-ak.last.fm/serve/126/3598785.jpg</image>
+   <attendance>1</attendance>
+
+   <reviews>0</reviews>
+   <tag>lastfm:event=924763</tag>  
+  <url>http://www.last.fm/event/924763</url>
+</event>
+</events></lfm>
+
+)
+
+
+class Response < Mapricot::Base
+  has_many :events, :xml
+end
+
+class Event < Mapricot::Base
+  has_one :id,              :integer
+  has_one :title,           :string
+  has_one :artist_group,    :xml,       :tag_name => "artists"
+  has_one :venue,           :xml
+end
+
+class ArtistGroup < Mapricot::Base
+  has_many  :artists,       :string
+  has_one   :headliner,     :string
+end
+
+class Venue < Mapricot::Base
+  has_one   :name,          :string
+end
+
+lfm = Response.new(:xml => last_fm_example)
+lfm.events.each do |event|
+  puts "-------------------------------"
+  puts event.title
+  puts event.artist_group.artists.inspect
+  puts event.venue.name
+end

data/examples/readme_examples.rb

@@ -0,0 +1,82 @@
+require File.expand_path(File.dirname(__FILE__) + "/../lib/mapricot")
+
+# super simple
+simple_xml = %(
+  <user>
+    <id>1</name>
+    <name>Bob</name>
+    <pet>cat</pet>
+    <pet>dog</pet>
+  </user>
+)
+
+class User < Mapricot::Base
+  has_one   :id,    :integer
+  has_one   :name,  :string
+  has_many  :pets,  :string
+end
+
+user = User.new(:xml => simple_xml)
+puts user.id                # => 1
+puts user.id.class          # => Fixnum
+puts user.name              # => Bob
+puts user.pets.class        # => Array
+puts user.pets.join(", ")   # => cat, dog
+
+puts "-------------------"
+
+# A little more realistic
+xml = %(
+  <user>
+    <id>2</name>
+    <name>Sally</name>
+    <location code="ny123">
+      <city>New York</city>
+      <state>NY</state>
+    </location>
+    <hobby>
+      <description>Skiing</description>
+      <number_of_years>2</number_of_years>
+    </hobby>
+    <hobby>
+      <description>Hiking</description>
+      <number_of_years>3</number_of_years>
+    </hobby>
+  </user>
+)
+
+
+class User < Mapricot::Base
+  has_one   :id,        :integer
+  has_one   :name       # Tag type will default to :string
+  has_many  :pets
+  has_one   :location,  :xml
+  has_many  :hobbies,   :xml
+end
+
+class Location < Mapricot::Base
+  has_attribute :code
+  has_one       :city
+  has_one       :state
+end
+
+class Hobby < Mapricot::Base
+  has_one :description,     :string
+  has_one :number_of_years, :integer
+end
+
+user = User.new(:xml => xml)
+puts user.name            # => Sally
+puts user.pets.inspect    # => []
+puts user.location.class  # => Location
+puts user.location.city   # => New York
+puts user.location.state  # => NY
+puts user.location.code   # => ny123
+puts user.hobbies.class         # => Array
+puts user.hobbies.first.class   # => Hobby
+
+user.hobbies.each do |hobby|
+  puts "#{hobby.description} for #{hobby.number_of_years} years"
+end
+# => Skiing for 2 years
+# => Hiking for 3 years

data/examples/xml_with_attributes.rb

@@ -0,0 +1,26 @@
+require File.expand_path(File.dirname(__FILE__) + "/../lib/mapricot")
+
+
+xml = %(
+<response>
+  <user id="32" name="Bob"></user>
+  <user id="33" name="Sally"></user>
+</response>
+)
+
+
+class Response < Mapricot::Base
+  has_many :users, :xml
+end
+
+class User < Mapricot::Base
+  has_attribute :id
+  has_attribute :name
+end
+
+response = Response.new(:xml => xml)
+
+response.users.each do |user|
+  puts user.name
+  puts user.id
+end