xspf 0.3 → 0.4

data/AUTHORS

@@ -1,7 +1,7 @@
 = Authors
 
 Pau Garcia i Quiles <pgquiles at elpauer dot org>
- * Developer & maintainer
+ * XSPF for Ruby developer & maintainer
 
 Lucas Gonze <lgonze at panix dot com>
  * XSLT templates

data/ChangeLog

@@ -1,3 +1,18 @@
+0.4
+
+ * XSPF document generator (see examples of use)
+
+ * Renamed the methods which show the XML code for XSPF and XSPF::Playlist to XSPF#playlist_xml, XSPF::Playlist#tracklist_xml. These methods are now protected and should never be used. If you need to see the XML code, use to_xml
+
+ * Removed the 'xspf' parameter in to_m3u, to_smil, to_soundblox and to_html
+
+ * XSPF#playlist always returns a valid XSPF::Playlist object (both in parse and generation modes)
+ 
+ * XSPF::Playlist#tracklist always returns a valid XSPF::Tracklist object (both in parse and generation modes)
+
+ * It is able to eat its own dogfood (but keep in mind the limitations about <attribution>, <extension>, <link> and <meta>)
+
+
 0.3
 
  * Add methods to export the XSPF document to M3U, HTML, SMIL and SoundBlox

data/README

@@ -1,16 +1,13 @@
 = README: XSPF for Ruby
-This library reads and parses a XSPF playlist file. This is release 0.2. 
-
-At this early stage of development, it is not yet possible to write XSPF 
-files. 
+This library parses and generates XSPF playlist documents. This is release 0.4.
 
 Current limitations:
- - Only read, not write, XSPF files
- - For "link" and "extension" elements, only the first one is found
- - The "attribution" element is not parsed (the XML content is returned)
- - The "extension" element is not parsed (the XML content is returned)
+    - For 'link', 'meta' and 'extension' elements, only the first one is parsed and only
+one can be generated
+    - The content of the 'attribution' element is not parsed (the XML content is returned)
+    - The content of the 'extension' element is not parsed (the XML content is returned)
 
-Homepage::  http://www.elpauer.org/xspf/
+Homepage::  http://xspf.rubyforge.org
 
 == Licensing
 XSPF for Ruby is available under the Ruby license and the GPLv2 license

data/USAGE

@@ -0,0 +1,350 @@
+:title: USAGE
+
+XSPF for Ruby implements a XML Shareable Playlist Format (XSPF[http://www.xspf.org]) v1 parser and generator in pure Ruby. It makes use of REXML to parse and generate the XML code, and Ruby-XSLT to export XSPF to different formats by means of XSLT transformations (XSPF for Ruby includes the XSLT templates by Lucas Gonze in its distribution).
+
+The API is quite straightforward if you know the XSPF specification. It is possible to combine parse and generation modes: you may load (parse) a file, then modify some of its attributes or contents and save it to XSPF again.
+
+The important thing to remember while using XSPF for Ruby is in generation mode you create objects by passing a hash or nil, and in parse mode you create objects by passing its 'parent' in the XSPF hierarchy.
+
+If a XSPF attribute or element is not set, the corresponding method will return _nil_.
+
+=== Examples
+==== Parse from file
+    
+    require 'xspf'
+
+    f = File.new("playlist.xspf")
+    x = XSPF.new(f)
+    f.close
+    pl = XSPF::Playlist.new(x)
+    tl = XSPF::Tracklist.new(pl)
+    
+    puts "XML version: #{x.version}"
+    puts "XML encoding: #{ x.encoding}"
+    puts "XSPF version: #{pl.version}"
+    puts "Namespace: #{pl.xmlns}"
+    puts "Playlist title: #{pl.title}"
+    puts "Playlist creator: #{pl.creator}"
+    puts "Playlist annotation: #{pl.annotation}"
+    puts "Playlist info: #{pl.info}"
+    puts "Playlist identifier: #{pl.identifier}"
+    puts "Playlist attribution: #{pl.attribution}"
+    puts "Tracklist: #{pl.tracklist}"
+    tl.tracks.each do |t|
+        puts "Track identifier: #{t.identifier}"
+        puts "Track title: #{t.title}"
+        puts "Track creator: #{t.creator}"
+        puts "Track duration: #{t.duration}"
+        puts "Track metainformation: link=#{t.meta_rel} content=#{t.meta_content}"
+    end
+
+    # Convert the XSPF document to SMIL
+    x.to_smil
+
+    # Convert the XSPF document to HTML
+    x.to_html
+
+    # Convert the XSPF document in a M3U playlist
+    x.to_m3u
+
+==== Parse from string
+
+    require 'xspf'
+
+    playlist_document = <<-END_OF_PLAYLIST
+    <?xml version="1.0" encoding="UTF-8"?>
+    <playlist version="0" xmlns="http://xspf.org/ns/0/">
+        <title>XSPlF it up!</title>
+        <creator>Mayhem &amp; Chaos Coordinator</creator>
+        <annotation>Just a few songs to enjoy while you XSPlF it up!</annotation>
+        <info>http://mayhem-chaos.net/xspf/xspf_it_up.html</info>
+        <identifier>http://mayhem-chaos.net/xspf/xspf_it_up/1.0</identifier>
+        <attribution>
+            <location>ihttp://mayhem-chaos.net/xspf/xspf_it_up.html</location>
+        </attribution>
+        <trackList>
+            <track>
+            <identifier>http://musicbrainz.org/track/bdab6db0-2fd6-4166-a5fa-fbf2ff213793</identifier>
+            <title>I Wanna Get High</title>
+            <creator>Cypress Hill</creator>
+            <duration>174613</duration>
+            <meta rel="http://musicbrainz.org/track">http://musicbrainz.org/mm-2.1/track/bdab6db0-2fd6-4166-a5fa-fbf2ff213793</meta>
+            </track>
+            <track>
+            <identifier>bdc846e7-6c26-4193-82a6-8d1b5a4d3429</identifier>
+            <title>Smoke Two Joints</title>
+            <creator>Sublime</creator>
+            <duration>175466</duration>
+            <meta rel="http://musicbrainz.org/track">http://musicbrainz.org/mm-2.1/track/bdc846e7-6c26-4193-82a6-8d1b5a4d3429</meta>
+            </track>
+            <track>
+            <identifier>http://musicbrainz.org/track/7d9776f7-d428-40dc-a425-3c6e3dce4d58</identifier>
+            <title>Hash Pipe</title>
+            <creator>Weezer</creator>
+            <duration>186533</duration>
+            <meta rel="http://musicbrainz.org/track">http://musicbrainz.org/mm-2.1/track/7d9776f7-d428-40dc-a425-3c6e3dce4d58</meta>
+            </track>
+        </trackList>
+    </playlist>
+    END_OF_PLAYLIST
+
+    x = XSPF.new(playlist_document)
+    pl = XSPF::Playlist.new(x)
+    tl = XSPF::Tracklist.new(pl)
+
+    puts "XML version: #{x.version}"
+    puts "XML encoding: #{ x.encoding}"
+    puts "XSPF version: #{pl.version}"
+    puts "Namespace: #{pl.xmlns}"
+    puts "Playlist title: #{pl.title}"
+    puts "Playlist creator: #{pl.creator}"
+    puts "Playlist annotation: #{pl.annotation}"
+    puts "Playlist info: #{pl.info}"
+    puts "Playlist identifier: #{pl.identifier}"
+    puts "Playlist attribution: #{pl.attribution}"
+    puts "Tracklist: #{pl.tracklist}"
+    tl.tracks.each do |t|
+        puts "Track identifier: #{t.identifier}"
+        puts "Track title: #{t.title}"
+        puts "Track creator: #{t.creator}"
+        puts "Track duration: #{t.duration}"
+        puts "Track metainformation: link=#{t.meta_rel} content=#{t.meta_content}"
+    end
+
+    # Convert the XSPF document to SMIL
+    x.to_smil
+
+    # Convert the XSPF document to HTML
+    x.to_html
+
+    # Convert the XSPF document in a M3U playlist
+    x.to_m3u
+
+==== Generate
+
+    require 'xspf'
+
+    track1 = XSPF::Track.new( {
+            :location => 'http://some.nifty.locati.on/file1.ogg', 
+            :identifier => 'http://musicbrainz.org/track/9f342af1-982d-4c26-9f61-3ac258957a83',  :title => 'Plus au sud',
+            :creator => 'Yann Tiersen',
+            :tracknum => '1',
+            :album => 'Tout est calme',
+            :meta_rel => 'http://www.example.org/key',
+            :meta_content => 'value'
+          } )
+
+    track2 = XSPF::Track.new( {
+             :location => 'http://some.nifty.locati.on/file2.ogg',
+             :identifier => 'http://musicbrainz.org/track/eba1a9a9-1810-41f1-8cc9-2a00dda0a68c',
+             :title => 'Les Grandes Marées',
+             :creator => 'Yann Tiersen',
+             :tracknum => '2',
+             :album => 'Tout est calme',
+             :meta_rel => 'http://www.example.org/key',
+             :meta_content => 'value'
+           } )
+
+    track3 = XSPF::Track.new( {
+             :location => 'http://some.nifty.locati.on/file3.ogg',
+             :identifier => 'http://musicbrainz.org/track/0c18ef8c-04fa-47d5-b078-66ab6a819a83',
+             :title => 'La Crise',
+             :creator => 'Yann Tiersen',
+             :tracknum => '3',
+             :album => 'Tout est calme',
+             :meta_rel => 'http://www.example.org/key',
+             :meta_content => 'value'
+           } )
+
+    track4 = XSPF::Track.new( {
+             :location => 'http://some.nifty.locati.on/file4.ogg',
+             :identifier => 'http://musicbrainz.org/track/0f66dd52-bda0-4526-979d-af95ac637cc4',
+             :title => 'Tout est calme',
+             :creator => 'Yann Tiersen',
+             :tracknum => '4',
+             :album => 'Tout est calme',
+             :meta_rel => 'http://www.example.org/key',
+             :meta_content => 'value'
+           } )
+
+    track5 = XSPF::Track.new( {
+             :location => 'http://some.nifty.locati.on/file5.ogg',
+             :identifier => 'http://musicbrainz.org/track/a06ef58e-019e-409a-bf72-9bd080012ac3',
+             :title => 'La Rupture',
+             :creator => 'Yann Tiersen',
+             :tracknum => '5',
+             :album => 'Tout est calme',
+             :meta_rel => 'http://www.example.org/key',
+             :meta_content => 'value'
+           } )
+
+    track6 = XSPF::Track.new( {
+             :location => 'http://some.nifty.locati.on/file6.ogg',
+             :identifier => 'http://musicbrainz.org/track/f82c0a06-d4a8-41a5-9238-029e38fa9d7c',
+             :title => 'La Relève',
+             :creator => 'Yann Tiersen',
+             :tracknum => '6',
+             :album => 'Tout est calme',
+             :meta_rel => 'http://www.example.org/key',
+             :meta_content => 'value'
+           } )
+
+    track7 = XSPF::Track.new( {
+             :location => 'http://some.nifty.locati.on/file7.ogg',
+             :identifier => 'http://musicbrainz.org/track/97591e2b-967e-47eb-b2b3-9a450cd33352',
+             :title => 'La Pharmacie',
+             :creator => 'Yann Tiersen',
+             :tracknum => '7',
+             :album => 'Tout est calme',
+             :meta_rel => 'http://www.example.org/key',
+             :meta_content => 'value'
+           } )
+
+    track8 = XSPF::Track.new( {
+             :location => 'http://some.nifty.locati.on/file8.ogg',
+             :identifier => 'http://musicbrainz.org/track/ae7f8502-778d-4f5e-9dba-6fc5d553ad0e',
+             :title => 'La Terrasse',
+             :creator => 'Yann Tiersen',
+             :tracknum => '8',
+             :album => 'Tout est calme',
+             :meta_rel => 'http://www.example.org/key',
+             :meta_content => 'value'
+           } )
+
+    track9 = XSPF::Track.new( {
+             :location => 'http://some.nifty.locati.on/file9.ogg',
+             :identifier => 'http://musicbrainz.org/track/6e937503-9d01-428c-84b5-1200bab9d1c6',
+             :title => "L''Étal",
+             :creator => 'Yann Tiersen',
+             :tracknum => '9',
+             :album => 'Tout est calme',
+             :meta_rel => 'http://www.example.org/key',
+             :meta_content => 'value'
+           } )
+
+    track10 = XSPF::Track.new( {
+              :location => 'http://some.nifty.locati.on/file10.ogg',
+              :identifier => 'http://musicbrainz.org/track/2c4c845c-907a-4d96-940a-bbe8b2d0f126',
+              :title => 'La Découverte',
+              :creator => 'Yann Tiersen',
+              :tracknum => '10',
+              :album => 'Tout est calme',
+              :meta_rel => 'http://www.example.org/key',
+              :meta_content => 'value'
+            } )
+
+    tracklist = XSPF::Tracklist.new
+
+    tracklist << track1
+    tracklist << track2
+    tracklist << track3
+    tracklist << track4
+    tracklist << track5
+    tracklist << track6
+    tracklist << track7
+    tracklist << track8
+    tracklist << track9
+    tracklist << track10
+
+    playlist = XSPF::Playlist.new( {
+               :xmlns => 'http://xspf.org/ns/0/',
+               :title => 'Tout est calme',
+               :creator => 'Yann Tiersen',
+               :license => 'Redistribution or sharing not allowed',
+               :info => 'http://www.yanntiersen.com/',
+               :tracklist => tracklist,
+               :meta_rel => 'http://www.example.org/key',
+               :meta_content => 'value'
+             } )
+
+    xspf = XSPF.new( { :playlist => playlist } )
+
+    f = File.open('playlist.xspf', 'w')
+    f.write(xspf.to_xml)
+    f.close
+
+==== Parse and generate 
+
+Say you want to modify an existing XSPF document. What would you do?
+
+There are two ways to do it: the right way and the wrong way. The best way to do it is:
+
+    require 'xspf'
+
+    f = File.new("playlist.xspf")
+    x = XSPF.new(f)
+    pl = x.playlist
+    tl = pl.tracklist
+
+    some_other_track = XSPF::Track.new( {
+            :location => 'http://some.nifty.locati.on/file1.ogg',
+            :identifier => 'http://musicbrainz.org/track/9f342af1-982d-4c26-9f61-3ac258957a83',
+            :title => 'Plus au sud',
+            :creator => 'Yann Tiersen',
+            :tracknum => '1',
+            :album => 'Tout est calme',
+            :meta_rel => 'http://www.example.org/key',
+            :meta_content => 'value'
+          } )
+
+    tl << some_other_track
+    pl.title = 'My modified playlist'
+    f = File.open('playlist.xspf', 'w')
+    f.write(x.to_xml)
+    f.close
+
+Of course this would also work, but it means more work:
+
+    require 'xspf'
+
+    f = File.new("playlist.xspf")
+    x = XSPF.new(f)
+    pl = XSPF::Playlist.new(x)
+    tl = XSPF::Tracklist.new(pl)
+
+    some_other_track = XSPF::Track.new( {
+            :location => 'http://some.nifty.locati.on/file1.ogg',
+            :identifier => 'http://musicbrainz.org/track/9f342af1-982d-4c26-9f61-3ac258957a83',
+            :title => 'Plus au sud',
+            :creator => 'Yann Tiersen',
+            :tracknum => '1',
+            :album => 'Tout est calme',
+            :meta_rel => 'http://www.example.org/key',
+            :meta_content => 'value'
+          } )
+
+    tl << some_other_track
+    pl.title = 'My modified playlist'
+    pl.tracklist = tl
+    x.playlist = pl
+    f = File.open('playlist.xspf', 'w')
+    f.write(x.to_xml)
+    f.close
+
+This way, which may seem intuitive, is wrong:
+
+    require 'xspf'
+
+    f = File.new("playlist.xspf")
+    x = XSPF.new(f)
+    pl = XSPF::Playlist.new(x)
+    tl = XSPF::Tracklist.new(pl)
+
+    some_other_track = XSPF::Track.new( {
+            :location => 'http://some.nifty.locati.on/file1.ogg',
+            :identifier => 'http://musicbrainz.org/track/9f342af1-982d-4c26-9f61-3ac258957a83',
+            :title => 'Plus au sud',
+            :creator => 'Yann Tiersen',
+            :tracknum => '1',
+            :album => 'Tout est calme',
+            :meta_rel => 'http://www.example.org/key',
+            :meta_content => 'value'
+          } )
+
+    tl << some_other_track
+    pl.title = 'My modified playlist'
+    f = File.open('playlist.xspf', 'w')
+    f.write(x.to_xml)
+    f.close
+
+That will not work because 'pl' is a new object, unrelated to 'x'; and 'tl' is a new object, unrelated to 'pl'.

data/coverage/index.html

@@ -149,7 +149,7 @@ table.report tr.dark {
       </head>
       <body>
         <h3>C0 code coverage information</h3>
-        <p>Generated on Fri Oct 20 17:20:35 CEST 2006 with <a href='http://eigenclass.org/hiki.rb?rcov'>rcov 0.7.0</a>
+        <p>Generated on Mon Oct 30 22:55:21 CET 2006 with <a href='http://eigenclass.org/hiki.rb?rcov'>rcov 0.7.0</a>
         </p>
         <hr />    <table class='report'>
       <thead>
@@ -165,21 +165,21 @@ table.report tr.dark {
         <tr class='light'>
           <td>TOTAL</td>
           <td class='value'>
-            <tt>319</tt>
+            <tt>480</tt>
           </td>
           <td class='value'>
-            <tt>126</tt>
+            <tt>321</tt>
           </td>
           <td>
             <table cellspacing='0' cellpadding='0' align='right'>
               <tr>
                 <td>
-                  <tt>95.6%</tt>&nbsp;</td>
+                  <tt>100.0%</tt>&nbsp;</td>
                 <td>
                   <table cellspacing='0' class='percent_graph' cellpadding='0' width='100'>
                     <tr>
-                      <td class='covered' width='96' />
-                      <td class='uncovered' width='4' />
+                      <td class='covered' width='100' />
+                      <td class='uncovered' width='0' />
                     </tr>
                   </table>
                 </td>
@@ -190,12 +190,12 @@ table.report tr.dark {
             <table cellspacing='0' cellpadding='0' align='right'>
               <tr>
                 <td>
-                  <tt>91.3%</tt>&nbsp;</td>
+                  <tt>100.0%</tt>&nbsp;</td>
                 <td>
                   <table cellspacing='0' class='percent_graph' cellpadding='0' width='100'>
                     <tr>
-                      <td class='covered' width='91' />
-                      <td class='uncovered' width='9' />
+                      <td class='covered' width='100' />
+                      <td class='uncovered' width='0' />
                     </tr>
                   </table>
                 </td>
@@ -208,21 +208,21 @@ table.report tr.dark {
             <a href='lib-xspf_rb.html'>lib/xspf.rb</a>
           </td>
           <td class='value'>
-            <tt>319</tt>
+            <tt>480</tt>
           </td>
           <td class='value'>
-            <tt>126</tt>
+            <tt>321</tt>
           </td>
           <td>
             <table cellspacing='0' cellpadding='0' align='right'>
               <tr>
                 <td>
-                  <tt>95.6%</tt>&nbsp;</td>
+                  <tt>100.0%</tt>&nbsp;</td>
                 <td>
                   <table cellspacing='0' class='percent_graph' cellpadding='0' width='100'>
                     <tr>
-                      <td class='covered' width='96' />
-                      <td class='uncovered' width='4' />
+                      <td class='covered' width='100' />
+                      <td class='uncovered' width='0' />
                     </tr>
                   </table>
                 </td>
@@ -233,12 +233,12 @@ table.report tr.dark {
             <table cellspacing='0' cellpadding='0' align='right'>
               <tr>
                 <td>
-                  <tt>91.3%</tt>&nbsp;</td>
+                  <tt>100.0%</tt>&nbsp;</td>
                 <td>
                   <table cellspacing='0' class='percent_graph' cellpadding='0' width='100'>
                     <tr>
-                      <td class='covered' width='91' />
-                      <td class='uncovered' width='9' />
+                      <td class='covered' width='100' />
+                      <td class='uncovered' width='0' />
                     </tr>
                   </table>
                 </td>