atom-tools 0.9.0 → 2.0.5

data/COPYING

@@ -6,13 +6,13 @@ 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 BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+THE AUTHORS 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

@@ -10,7 +10,7 @@ It handles all the nasty XML and HTTP details so that you don't have to.
 
   feed = Atom::Feed.new "http://www.tbray.org/ongoing/ongoing.atom"
     # => <http://www.tbray.org/ongoing/ongoing.atom entries: 0 title=''>
-  
+
   feed.update!
   feed.entries.length
     # => 20
@@ -29,7 +29,7 @@ It handles all the nasty XML and HTTP details so that you don't have to.
 
   entry.links.last
     # => {"href"=>"http://www.tbray.org/ongoing/When/200x/2006/11/07/Munich#comments", "rel"=>"replies", "type" => "application/xhtml+xml"}
-  
+
   entry.summary.to_s
     # => "That local spelling is nicer than the ugly English [...]"
 
@@ -37,16 +37,16 @@ Things are explained in more detail in the RDoc.
 
 == The Atom Publishing Protocol
 
-  require "atom/app"
+  require "atom/service"
 
-  app = Atom::App.new "http://necronomicorp.com/app.xml"
-  coll = app.collections.first
+  service = Atom::Service.new "http://necronomicorp.com/app.xml"
+  coll = service.workspaces.first.collections.first
     # => <http://necronomicorp.com/testatom?app entries: 0 title='testing: entry endpoint'>
 
-  coll.update!
+  coll.feed.update!
     # => <http://necronomicorp.com/testatom?app entries: 10 title='testing the APP'>
 
-  entry = coll.entries.first
+  entry = coll.feed.entries.first
   entry.title
     # => 'html entities'#text
 
@@ -57,47 +57,7 @@ Things are explained in more detail in the RDoc.
   coll.put! entry
     # => #<Net::HTTPOK 200 OK readbody=true>
 
-  coll.entries.first.title
+  coll.feed.entries.first.title
     # => 'HTML entities'#text
 
-For details on authentication, see the documentation for Atom::HTTP
-
-== Advanced Use
-
-=== Extension Elements
-
-  irt = REXML::Element.new("in-reply-to")
-  irt.add_namespace "http://purl.org/syndication/thread/1.0"
-
-  irt.attributes["ref"] = "tag:entries.com,2005:1"
-
-  entry.extensions << irt
-
-  entry.to_s
-    # => '<entry xmlns="http://www.w3.org/2005/Atom"><in-reply-to ref="tag:entries.com,2005:1" xmlns="http://purl.org/syndication/thread/1.0"/></entry>'
-
-== YAML
-
-if you feel like writing this stuff by hand, atom-tools can slurp an
-atom:entry from YAML:
-
-  require "atom/yaml"
-
-  yaml = <<END
-    title: Atom-Drunk Pirates Run Amok!
-    tags: tag1 tag2
-    authors:
-    -
-      name: Brendan Taylor
-      email: whateley@gmail.com
-    -
-      name: Harvey
-      uri: http://fake.com/
-
-    content: |
-      <p>blah blah blah blah</p>
-
-      <p>and so on.</p>
-  END
-
-  entry = Atom::Entry.from_yaml(yaml)
+For details on authentication, see the documentation for Atom::HTTP.

data/Rakefile

@@ -2,76 +2,79 @@ require "rake"
 require "rake/testtask"
 require "rake/rdoctask"
 require "rake/gempackagetask"
+require "spec/rake/spectask"
 
 require "rake/clean"
 
 NAME = "atom-tools"
-VERS = "0.9.0"
-
-# the following from markaby-0.5's tools/rakehelp
-def setup_tests
-  Rake::TestTask.new do |t|
-    t.libs << "test"
-    t.test_files = FileList['test/test*.rb']
-    t.verbose = true
-  end
-end
+VERS = "2.0.5"
+
+task :default => [:spec]
+
+# For historical reasons, atom-tools has both rspec specs and test/unit tests.
+# This is silly (and there's a lot of duplication), but I have better things to
+# do than rewrite the tests.
+#
+# Ideally all the tests should be runnable with one command, but for now you
+# have to run "rake test" and "rake spec"
+
+# spec task
+desc 'Run all specs (see also "test" task)'
+Spec::Rake::SpecTask.new('spec')
 
-def setup_rdoc files
-  Rake::RDocTask.new do |rdoc|
-    rdoc.title = NAME + " documentation"
-    rdoc.rdoc_dir = 'doc'
-    rdoc.options << '--line-numbers'
-    rdoc.options << '--inline-source'
-    rdoc.rdoc_files.add(files)
-  end
+# test task
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
 end
 
-def setup_gem(pkg_name, pkg_version, author, summary, dependencies, test_file)
-  pkg_version = pkg_version
-  pkg_name    = pkg_name
-  pkg_file_name = "#{pkg_name}-#{pkg_version}"
-
-  spec = Gem::Specification.new do |s|
-    s.name = pkg_name
-    s.version = pkg_version
-    s.platform = Gem::Platform::RUBY
-    s.author = author
-    s.summary = summary
-    s.test_file = test_file
-    s.has_rdoc = true
-    s.extra_rdoc_files = [ "README" ]
-    dependencies.each do |dep|
-        s.add_dependency(*dep)
-    end
-    s.files = %w(COPYING README Rakefile setup.rb) +
-    Dir.glob("{bin,doc,test,lib}/**/*") + 
-    Dir.glob("ext/**/*.{h,c,rb}") +
-    Dir.glob("examples/**/*.rb") +
-    Dir.glob("tools/*.rb")
-
-    s.require_path = "lib"
-    s.extensions = FileList["ext/**/extconf.rb"].to_a
-
-    s.bindir = "bin"
-  end
-
-  Rake::GemPackageTask.new(spec) do |p|
-    p.gem_spec = spec
-    p.need_tar = true
-  end
-
-  task :install do
-    sh %{rake package}
-    sh %{gem install pkg/#{pkg_name}-#{pkg_version}}
-  end
+Rake::RDocTask.new do |rdoc|
+  rdoc.title = 'atom-tools documentation'
+  rdoc.main = 'README'
+  rdoc.rdoc_files.include 'README', 'lib/**/*.rb'
+  rdoc.rdoc_dir = 'doc'
 end
 
-task :default => [:package]
+spec = Gem::Specification.new do |s|
+  s.name = NAME
+  s.version = VERS
+  s.platform = Gem::Platform::RUBY
+  s.author = "Brendan Taylor"
+  s.email = 'whateley@gmail.com'
+  s.homepage = 'http://github.com/bct/atom-tools/wikis'
+
+  s.rubyforge_project = 'ibes'
+
+  s.summary = 'Tools for working with Atom Entries, Feeds and Collections.'
+  s.description = 'atom-tools is an all-in-one Atom library. It parses and builds Atom (RFC 4287) entries and feeds, and manipulates Atom Publishing Protocol (RFC 5023) Collections.
+
+It also comes with a set of commandline utilities for working with AtomPub Collections.
+
+It is not the fastest Ruby Atom library, but it is comprehensive and makes handling extensions to the Atom format very easy.'
 
-setup_tests
-setup_rdoc ['README', 'lib/**/*.rb']
+  s.test_file = "test/runtests.rb" # TODO: should have the spec here instead?
+  s.has_rdoc = true
+  s.extra_rdoc_files = [ "README" ]
 
-summary = "Tools for working with Atom Entries, Feeds and Collections"
-test_file = "test/runtests.rb"
-setup_gem(NAME, VERS, "Brendan Taylor", summary, [], test_file)
+  s.files = %w(COPYING README Rakefile setup.rb) +
+  Dir.glob("{bin,doc,test,spec,lib}/**/*") +
+  Dir.glob("ext/**/*.{h,c,rb}") +
+  Dir.glob("examples/**/*.rb") +
+  Dir.glob("tools/*.rb")
+
+  s.require_path = "lib"
+  s.extensions = FileList["ext/**/extconf.rb"].to_a
+
+  s.bindir = "bin"
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+end
+
+task :install do
+  sh %{rake package}
+  sh %{gem install pkg/#{NAME}-#{VERS}}
+end

data/bin/atom-cp

@@ -0,0 +1,159 @@
+#!/usr/bin/env ruby
+
+=begin
+Usage: atom-cp [options] source destination
+    copy the contents of an Atom Collection
+
+    'source' and 'destination' can be a path on the local filesystem, the
+  URL of an Atom Collection or '-' for stdin/stdout
+=end
+
+require 'atom/tools'
+include Atom::Tools
+
+def parse_options
+  options = { }
+
+  opts = OptionParser.new do |opts|
+    opts.banner = <<END
+Usage: #{$0} [options] source destination
+    copy an Atom Collection
+
+    'source' and 'destination' can be a path on the local filesystem, the
+  URL of an Atom Collection or '-' for stdin/stdout
+
+END
+
+    opts.on('-c', '--complete', "follow previous and next links in the source feed to obtain the entire logical feed") do
+     options[:complete] = true
+    end
+
+    opts.on('-s', '--infer-slugs', 'try to infer entry slugs') { options[:infer_slugs] = true }
+
+    opts.on('-v', '--verbose') { options[:verbose] = true }
+
+    atom_options opts, options
+  end
+
+  opts.parse!(ARGV)
+
+  if ARGV.length != 2
+    puts opts
+    exit
+  end
+
+  options
+end
+
+# like dir_to_entries, but returns an Array of [slug, entry] pairs
+def dir_to_entries_with_slug path
+  raise ArgumentError, "#{path} is not a directory" unless File.directory? path
+
+  Dir[path+'/*.atom'].map do |e|
+    slug = e.match(/.*\/(.*)\.atom/)[1]
+    slug = nil if slug and slug.match /^0x/
+
+    entry = Atom::Entry.parse(File.read(e))
+
+    [slug, entry]
+  end
+end
+
+# like entries_to_http, but takes an Array of [slug, entry] pairs
+def entries_to_http_with_slug entries, url, http = Atom::HTTP.new
+  coll = Atom::Collection.new url, http
+
+  entries.each do |slug, entry|
+    coll.post! entry, slug
+  end
+end
+
+# like entries_to_dir, but takes an Array of [slug, entry] pairs
+def entries_to_dir_with_slug entries, path
+  if File.exists? path
+    raise "directory #{path} already exists"
+  else
+    Dir.mkdir path
+  end
+
+  entries.each do |slug,entry|
+    e = entry.to_s
+
+    new_filename = if slug
+                     path + '/' + slug + '.atom'
+                   else
+                     path + '/0x' + MD5.new(e).hexdigest[0,8] + '.atom'
+                   end
+
+    File.open(new_filename, 'w') { |f| f.write e }
+  end
+end
+
+def parse_input_with_slug source, options
+  entries = if source.match /^http/
+    http = Atom::HTTP.new
+
+    setup_http http, options
+
+    http_to_entries(source, options[:complete], http).map do |e|
+      [nil, e]
+    end
+  elsif source == '-'
+    stdin_to_entries.map do |e|
+      [nil, e]
+    end
+  else
+    dir_to_entries_with_slug source
+  end
+
+  if options[:verbose]
+    entries.each do |slug,entry|
+      print "got #{entry.title}  "
+      puts (slug ? "(/#{slug})" : '')
+    end
+  end
+
+  if options[:infer_slugs]
+    entries.map! do |slug,entry|
+      slug ||= infer_slug entry
+
+      [slug, entry]
+    end
+  end
+
+  entries
+end
+
+def write_output_with_slug entries, dest, options
+  if dest.match /^http/
+    http = Atom::HTTP.new
+
+    setup_http http, options
+
+    entries_to_http_with_slug entries, dest, http
+  elsif dest == '-'
+    entries_to_stdout entries.map { |s,e| e }
+  else
+    entries_to_dir_with_slug entries, dest
+  end
+end
+
+# make up a slug based on the alternate link
+def infer_slug entry
+  slug = nil
+  alt = e.links.find { |l| l['rel'] == 'alternate' }
+
+  alt and alt['href'].split('/').last
+end
+
+if __FILE__ == $0
+  require 'optparse'
+
+  options = parse_options
+
+  source = ARGV[0]
+  dest = ARGV[1]
+
+  entries = parse_input_with_slug source, options
+  write_output_with_slug entries, dest, options
+end

data/bin/atom-grep

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+
+=begin
+Usage: atom-grep [options] regexp [source]
+    prints a feed containing every entry in the source feed whose
+  text content matches regexp to stdout
+
+    'source' can be a path on the local filesystem, the
+  URL of an Atom Collection or '-' for stdin.
+=end
+
+require 'atom/tools'
+include Atom::Tools
+
+def parse_options
+  options = { :regexp_options => 0 }
+
+  opts = OptionParser.new do |opts|
+    opts.banner = <<END
+Usage: #{$0} [options] regexp [source]
+    prints a feed containing every entry in the source feed whose
+  text content matches regexp to stdout
+
+    'source' can be a path on the local filesystem, the
+  URL of an Atom Collection or '-' for stdin.
+END
+
+    opts.on('-c', '--complete', "follow previous and next links in the source feed to obtain the entire logical feed") do
+     options[:complete] = true
+    end
+
+    opts.on('-v', '--invert-match', 'select only non-matching entries') do
+      options[:invert] = true
+    end
+
+    opts.on('-i', '--ignore-case', 'ignore case distinctions when matching') do
+      options[:regexp_options] |= Regexp::IGNORECASE
+    end
+
+    atom_options opts, options
+  end
+
+  opts.parse!(ARGV)
+
+  if ARGV.length < 1  or ARGV.length > 2
+    puts opts
+    exit
+  end
+
+  options
+end
+
+if __FILE__ == $0
+  require 'optparse'
+
+  options = parse_options
+
+  regexp = Regexp.new(ARGV[0], options[:regexp_options])
+
+  source = ARGV[1]
+  source ||= '-'
+
+  entries = parse_input source, options
+
+  pred = if options[:invert]
+           lambda do |e|
+             (e.title =~ regexp) or (e.content.to_s =~ regexp)
+           end
+         else
+           lambda do |e|
+             (e.title !~ regexp) and (e.content.to_s !~ regexp)
+           end
+         end
+
+  entries.reject! &pred
+
+  entries_to_stdout entries
+end

data/bin/atom-post

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+
+=begin
+Usage: atom-post [options] destination [file]
+  posts an Atom Entry or a file to an Atom Collection
+
+  'destination' is the URL of an Atom Collection
+  'file' is the path to a file to POST (default is stdin)
+=end
+
+require 'rubygems'
+require 'atom/tools'
+include Atom::Tools
+
+def parse_options
+  options = {
+    :mimetype => 'application/atom+xml;type=entry'
+  }
+
+  opts = OptionParser.new do |opts|
+    opts.banner = <<END
+Usage: #{$0} [options] destination [file]
+  posts an Atom Entry or a file to an Atom Collection
+
+  'destination' is the URL of an Atom Collection
+  'file' is the path to a file to POST (default is stdin)
+END
+
+    opts.on('-m', '--mime-type TYPE', 'what to send in the Content-Type header') do |t|
+      options[:mimetype] = t
+    end
+
+    opts.on('-s', '--slug SLUG') do |s|
+      options[:slug] = s
+    end
+
+    atom_options opts, options
+  end
+
+  opts.parse!(ARGV)
+
+  if ARGV.length < 1 or ARGV.length > 2
+    puts opts
+    exit
+  end
+
+  options
+end
+
+if __FILE__ == $0
+  require 'optparse'
+
+  options = parse_options
+
+  dest = ARGV[0]
+
+  data = if ARGV[1]
+           File.read(ARGV[1])
+         else
+           $stdin.read
+         end
+
+  http = Atom::HTTP.new
+  setup_http http, options
+
+  headers = { 'Content-Type' => options[:mimetype] }
+
+  if options[:slug]
+    headers['Slug'] = options[:slug]
+  end
+
+  http.post dest, data, headers
+end

data/bin/atom-purge

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+
+=begin
+Usage: atom-purge [options] collection
+    delete all the entries in an Atom Collection
+
+    'collection' can be a path on the local filesystem, the
+  URL of an Atom Collection or '-' for stdin. the feed is parsed
+  and every Member URI found in it is DELETEd.
+=end
+
+require 'atom/tools'
+include Atom::Tools
+
+def parse_options
+  options = {}
+
+  opts = OptionParser.new do |opts|
+    opts.banner = <<END
+Usage: #{$0} [options] collection
+    delete all the entries in an Atom Collection
+
+    'collection' can be a path on the local filesystem, the
+  URL of an Atom Collection or '-' for stdin. the feed is parsed
+  and every Member URI found in it is DELETEd.
+
+END
+
+    opts.on('-c', '--no-complete', "don't follow previous and next links in the source feed") do
+     options[:complete] = false
+    end
+
+    opts.on('-v', '--verbose') { options[:verbose] = true }
+
+    opts.on('-i', '--interactive', "ask before each DELETE") { options[:interactive] = true }
+
+    atom_options opts, options
+  end
+
+  opts.parse!(ARGV)
+
+  if ARGV.length != 1
+    puts opts
+    exit
+  end
+
+  options
+end
+
+if __FILE__ == $0
+  require 'optparse'
+
+  options = parse_options
+
+  source = ARGV[0]
+  dest = ARGV[1]
+
+  entries = parse_input source, options
+
+  http = Atom::HTTP.new
+  setup_http http, options
+
+  tty = File.open('/dev/tty', 'w+') if options[:interactive]
+
+  uris = entries.each do |e|
+    next unless (uri = e.edit_url)
+
+    puts "deleting #{uri}" if options[:verbose]
+
+    if options[:interactive]
+      tty.puts "delete #{uri}"
+      tty.puts "title: #{e.title}"
+      tty.puts e.content.to_s
+      tty.puts
+      tty.print "? "
+
+      next unless ['y', 'yes'].member? tty.gets.chomp
+    end
+
+    http.delete uri
+  end
+end