restfully 0.3.2 → 0.4.0

data/CHANGELOG

@@ -0,0 +1,6 @@
+0.4.0
+* removed 'root_path' option: 'base_uri' must point to the starting resource;
+* objects can now be pretty printed using 'pp object';
+* Restfully::Collection now include the Enumerable module;
+* Restfully::Collection inherits from Restfully::Resource;
+* 'object.uid' is no longer valid. Use 'object["uid"]' instead;

data/README.rdoc

@@ -10,105 +10,95 @@ Alpha work.
 == Usage
 === Command line
   $ export RUBYOPT="-rubygems"
-  $ restfully base_uri [root_path] [-u username] [-p password]
+  $ restfully base_uri [-u username] [-p password]
   
 e.g., for the Grid5000 API:
-  $ restfully https://api.grid5000.fr/sid /grid5000 -u username -p password
-
-If the connection was successful, you should get a prompt. Call the +root+ function to see what are the available resources. <tt>@property</tt> means that you can call the +property+ method on the object. Other properties are available via the <tt>[]</tt> function.
-e.g.:
-  irb(main):005:0> root
-  => #<Restfully::Resource:0x8848de
-      	------------ META ------------
-      	@uri: #<URI::Generic:0x11091a8 URL:/grid5000>
-      	@uid: "grid5000"
-      	@type: "grid"
-      	@environments: Restfully::Collection
-      	@sites: Restfully::Collection
-      	@version: Restfully::Resource
-      	@versions: Restfully::Collection
-      	------------ PROPERTIES ------------
-      	"version" => "4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8">
-    
-   irb(main):006:0> root.uri
-   => #<URI::Generic:0x11091a8 URL:/grid5000>
-   
-   irb(main):007:0> root.sites
-   => #<Restfully::Collection:0x881f6c
-       	------------ META ------------
-       	@uri: "/grid5000/sites"
-       	@offset: 0
-       	@total: 9
-       	@version: Restfully::Resource
-       	@versions: Restfully::Collection
-       	------------ PROPERTIES ------------
-       	"version" => "4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8"
-       	------------ ITEMS ------------
-       	Restfully::Resource
-       	Restfully::Resource
-       	Restfully::Resource
-       	Restfully::Resource
-       	Restfully::Resource
-       	Restfully::Resource
-       	Restfully::Resource
-       	Restfully::Resource
-       	Restfully::Resource>
-   
-   irb(main):008:0> root.sites.by_uid('rennes').clusters.by_uid('paradent').nodes.by_uid('paradent-1').metrics.by_uid('mem_free', 'cpu_idle', 'bytes_in')
-   => [#<Restfully::Resource:0x4259a
-       	------------ META ------------
-       	@uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/mem_free"
-       	@uid: "mem_free"
-       	@type: "metric"
-       	@parent: Restfully::Resource
-       	@timeseries: Restfully::Resource
-       	------------ PROPERTIES ------------
-       	"last_update" => -901639018
-       	"step" => 15
-       	"timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>, #<Restfully::Resource:0x12444
-       	------------ META ------------
-       	@uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/cpu_idle"
-       	@uid: "cpu_idle"
-       	@type: "metric"
-       	@parent: Restfully::Resource
-       	@timeseries: Restfully::Resource
-       	------------ PROPERTIES ------------
-       	"last_update" => -901639018
-       	"step" => 15
-       	"timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>, #<Restfully::Resource:0xe4c870
-       	------------ META ------------
-       	@uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/bytes_in"
-       	@uid: "bytes_in"
-       	@type: "metric"
-       	@parent: Restfully::Resource
-       	@timeseries: Restfully::Resource
-       	------------ PROPERTIES ------------
-       	"last_update" => -901639018
-       	"step" => 15
-       	"timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>]
-   
-   irb(main):009:0> root.version
-   => #<Restfully::Resource:0x8facf0
-        ------------ META ------------
-        @uri: "/grid5000/versions/ee1f8111c8835496a9e4a6f7c9491c0238ee9827"
-        @uid: "ee1f8111c8835496a9e4a6f7c9491c0238ee9827"
-        @type: "version"
-        @parent: Restfully::Resource
-        ------------ PROPERTIES ------------
-        "author" => "Cyril Constantin <>"
-        "date" => "Fri, 11 Sep 2009 14:32:48 GMT"
-        "message" => "[environments] update of environments on sites">
-
-You may also prefer to use a configuration file to avoid entering the command line options:
+  $ restfully https://api.grid5000.fr/sid/grid5000 -u username -p password
+
+If the connection was successful, you should get a prompt. You may enter
+  irb(main):001:0> pp root
+
+to get back a pretty-printed output of the root resource:
+#<Restfully::Resource:0x91f08c
+  @uri=#<URI::HTTP:0x123e30c URL:http://api.local/sid/grid5000>
+  LINKS
+    @environments=#<Restfully::Collection:0x917666>,
+    @sites=#<Restfully::Collection:0x9170d0>,
+    @version=#<Restfully::Resource:0x91852a>,
+    @versions=#<Restfully::Collection:0x917e68>
+  PROPERTIES
+    "uid"=>"grid5000",
+    "type"=>"grid",
+    "version"=>"4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8">
+
+You can see the LINKS and PROPERTIES headers that respectively indicate what links you can follow from there (by calling +root.link_name+) and what properties are available (by calling +root[property_name]+).
+
+Let's say you want to access the collection of +sites+, you would enter:
+  irb(main):002:0> pp root.sites
+
+and get back:
+  #<Restfully::Collection:0x9170d0
+    @uri=#<URI::HTTP:0x122e128 URL:http://api.local/sid/grid5000/sites>
+    LINKS
+      @version=#<Restfully::Resource:0x8f553e>,
+      @versions=#<Restfully::Collection:0x8f52be>
+    PROPERTIES
+      "total"=>9,
+      "version"=>"4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8",
+      "offset"=>0
+    ITEMS (0..9)/9
+      #<Restfully::Resource:0x9058bc uid="bordeaux">,
+      #<Restfully::Resource:0x903d0a uid="grenoble">,
+      #<Restfully::Resource:0x901cc6 uid="lille">,
+      #<Restfully::Resource:0x8fff0c uid="lyon">,
+      #<Restfully::Resource:0x8fe288 uid="nancy">,
+      #<Restfully::Resource:0x8fc4a6 uid="orsay">,
+      #<Restfully::Resource:0x8fa782 uid="rennes">,
+      #<Restfully::Resource:0x8f8bb2 uid="sophia">,
+      #<Restfully::Resource:0x8f6c9a uid="toulouse">>
+
+A Restfully::Collection is a special kind of Resource, which includes the Enumerable module, which means you can call all of its methods on the Restfully::Collection object. For example:
+  irb(main):003:0> pp root.sites.find{|s| s['uid'] == 'rennes'}
+  #<Restfully::Resource:0x8fa782
+    @uri=#<URI::HTTP:0x11f4e64 URL:http://api.local/sid/grid5000/sites/rennes>
+    LINKS
+      @environments=#<Restfully::Collection:0x8f9ab2>,
+      @parent=#<Restfully::Resource:0x8f981e>,
+      @deployments=#<Restfully::Collection:0x8f935a>,
+      @clusters=#<Restfully::Collection:0x8f9d46>,
+      @version=#<Restfully::Resource:0x8fa354>,
+      @versions=#<Restfully::Collection:0x8fa0b6>,
+      @status=#<Restfully::Collection:0x8f95ee>
+    PROPERTIES
+      "name"=>"Rennes",
+      "latitude"=>48.1,
+      "location"=>"Rennes, France",
+      "security_contact"=>"rennes-staff@lists.grid5000.fr",
+      "uid"=>"rennes",
+      "type"=>"site",
+      "user_support_contact"=>"rennes-staff@lists.grid5000.fr",
+      "version"=>"4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8",
+      "description"=>"",
+      "longitude"=>-1.6667,
+      "compilation_server"=>false,
+      "email_contact"=>"rennes-staff@lists.grid5000.fr",
+      "web"=>"http://www.irisa.fr",
+      "sys_admin_contact"=>"rennes-staff@lists.grid5000.fr">
+
+or:
+  irb(main):006:0> root.sites.map{|s| s['uid']}.grep(/re/)
+  => ["grenoble", "rennes"]
+
+
+To enter the command-line options, you may prefer to use a configuration file to avoid re-entering the options every time you use the client:
   $ echo '
-  base_uri: https://api.grid5000.fr/sid
-  root_path: /grid5000
+  base_uri: https://api.grid5000.fr/sid/grid5000
   username: MYLOGIN
   password: MYPASSWORD
-  ' > ~/somewhere/api.grid5000.fr.yml
+  ' > ~/.restfully/api.grid5000.fr.yml && chmod 600 ~/.restfully/api.grid5000.fr.yml
 
 And then:
-  $ restfully -c ~/somewhere/api.grid5000.fr.yml
+  $ restfully -c ~/.restfully/api.grid5000.fr.yml
 
 === As a library
 See the +examples+ directory for examples.

data/Rakefile

@@ -11,6 +11,7 @@ begin
     gem.homepage = "http://github.com/crohr/restfully"
     gem.authors = ["Cyril Rohr"]
     gem.add_dependency "rest-client", '>= 1.0'
+    gem.add_dependency "backports"
     gem.rubyforge_project = 'restfully'
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end

data/VERSION

@@ -1 +1 @@
-0.3.2
+0.4.0

data/bin/restfully

@@ -1,19 +1,26 @@
 #!/usr/bin/env ruby
 # The command line Restfully client
 
-$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib' unless $LOAD_PATH.include? File.dirname(__FILE__) + '/../lib'
 
 require 'restfully'
 require 'optparse'
 require 'logger'
 require 'yaml'
+require 'pp'
 
 
 logger = Logger.new(STDOUT)
 logger.level = Logger::WARN
 @options = {:logger => logger}
 option_parser = OptionParser.new do |opts|
-  opts.banner = "Usage: restfully base_uri [root_path] [options]"
+  opts.banner = <<BANNER
+* Description
+  Restfully #{Restfully::VERSION} - Access REST APIs effortlessly
+* Usage
+  restfully [base_uri] [root_path] [options]
+* Options
+BANNER
 
   opts.on("-u=", "--username=", "Sets the username") do |u|
     @options[:username] = u
@@ -43,7 +50,6 @@ end
 option_parser.parse!
 
 @options[:base_uri] = ARGV.shift
-@options[:root_path] = ARGV.shift || "/"
 
 def session
   @session ||= Restfully::Session.new(@options)
@@ -51,52 +57,10 @@ end
 
 def root 
   @root ||= session.root.load
-rescue Restfully::HTTP::Error => e
-  puts "#{e.class.name}: #{e.message}"
 end
 
 require 'irb'
 require 'irb/completion'
 ARGV.clear
 IRB.start
-exit!  
-
-
-# if (config_filename = @options.delete('configuration_file')) && File.exists?(File.expand_path(config_filename))
-#   config = YAML.load_file(File.expand_path(config_filename))
-#   @base_uri = config.delete('base_uri') || @base_uri
-#   @root_path = config.delete('root_path') || @root_path
-#   @options.merge!(config)
-# end
-# 
-# unless @base_uri
-#   $stderr.puts option_parser.help
-#   exit(-1)
-# else
-#   if (log_file=@options.delete('log'))
-#     @logger = Logger.new(File.expand_path(log_file))
-#   else
-#     @logger = Logger.new(STDOUT)
-#   end
-#   if @options.delete('verbose')
-#     @logger.level = Logger::DEBUG
-#   else
-#     @logger.level = Logger::WARN
-#   end
-# 
-#   def session
-#     @session ||= Restfully::Session.new(@base_uri, @options.merge('root_path' => @root_path, 'logger' => @logger))
-#   end
-#   def root 
-#     @root ||= Restfully::Resource.new(session.root_path, session).load
-#   end
-#   
-#   root # preloads
-#   
-#   require 'irb'
-#   require 'irb/completion'
-#   
-#   ARGV.clear
-#   IRB.start
-#   exit!
-# end
+exit!

data/examples/grid5000.rb

@@ -5,12 +5,12 @@ require 'pp'
 require File.dirname(__FILE__)+'/../lib/restfully'
 
 logger = Logger.new(STDOUT)
-logger.level = Logger::INFO
+logger.level = Logger::WARN
 
 # Restfully.adapter = Restfully::HTTP::RestClientAdapter
 # Restfully.adapter = Patron::Session
 RestClient.log = 'stdout'
-Restfully::Session.new(:base_uri => 'http://api.local/sid', :root_path => '/grid5000', :logger => logger) do |grid, session|
+Restfully::Session.new(:base_uri => 'http://api.local/sid/grid5000', :logger => logger) do |grid, session|
   grid_stats = {'hardware' => {}, 'system' => {}}
   grid.sites.each do |site|
     site_stats = site.status.inject({'hardware' => {}, 'system' => {}}) {|accu, node_status|
@@ -20,9 +20,9 @@ Restfully::Session.new(:base_uri => 'http://api.local/sid', :root_path => '/grid
     } rescue {'hardware' => {}, 'system' => {}}
     grid_stats['hardware'].merge!(site_stats['hardware']) { |key,oldval,newval| oldval+newval }
     grid_stats['system'].merge!(site_stats['system']) { |key,oldval,newval| oldval+newval }
-    p [site.uid, site_stats]
+    p [site['uid'], site_stats]
   end
   p [:total, grid_stats]
   puts "Getting status of a few nodes in rennes:"
-  pp grid.sites.by_uid('rennes').status(:query => {:only => ['paradent-1', 'paradent-10', 'paramount-3']})
-end
+  pp grid.sites.find{|s| s['uid'] == 'rennes'}.status(:query => {:only => ['paradent-1', 'paradent-10', 'paramount-3']})
+end

data/lib/restfully.rb

@@ -1,3 +1,4 @@
+require 'backports'
 require 'restfully/error'
 require 'restfully/parsing'
 require 'restfully/http'
@@ -12,9 +13,9 @@ require 'restfully/collection'
 
 
 module Restfully
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
   class << self
     attr_accessor :adapter
   end
   self.adapter = Restfully::HTTP::Adapters::RestClientAdapter
-end
+end

data/lib/restfully/collection.rb

@@ -1,161 +1,86 @@
-require 'delegate'
 
 module Restfully
-  # Resource and Collection classes should clearly include a common module to deal with links, attributes, associations and loading
-  class Collection < DelegateClass(Array)
-    
-    attr_reader :state, :raw, :uri, :session, :title, :offset, :total, :items
+  # This includes the <tt>Enumerable</tt> module, but does not have all the
+  # methods that you could expect from an <tt>Array</tt>.
+  # Remember that this class inherits from a <tt>Restfully::Resource</tt> and
+  # as such, the <tt>#[]</tt> method gives access to Resource properties, and
+  # not to an item in the collection.
+  # If you want to operate on the array of items, you MUST call <tt>#to_a</tt>
+  # first (or <tt>#items</tt>) on the Restfully::Collection.
+  class Collection < Resource
+    include Enumerable
+    attr_reader :items
     
+    # See Resource#new
     def initialize(uri, session, options = {})
-      options = options.symbolize_keys
-      @uri = uri
-      @title = options[:title]
-      @session = session
-      reset
-      super(@items)
+      super(uri, session, options)
     end
-    
-    def loaded?;    @state == :loaded;    end
-    
+
+    # See Resource#reset
     def reset
-      @last_request_hash = nil
-      @associations = {}
-      @attributes = {}
-      @indexes = {}
-      @items = []
-      @raw = nil
-      @state = :unloaded
+      super
+      @items = Array.new
+      @indexes = Hash.new
+      self
     end
     
-    def [](key)
-      if key.is_a? Symbol
-        by_uid(key.to_s)
-      else
-        super(key)
-      end
+    # Iterates over the collection of items
+    def each(*args, &block)
+      @items.each(*args, &block)
     end
-    
-    def method_missing(method, *args)
-      load
-      if association = @associations[method.to_s]
-        session.logger.debug "Loading association #{method}, args=#{args.inspect}"
-        association.load(*args)
-      elsif method.to_s =~ /^by_(.+)$/
-        key = $1
-        @indexes[method.to_s] ||= self.inject({}) { |accu, item| 
-          accu[item.has_key?(key) ? item[key] : item.send(key.to_sym)] = item
-          accu
-        }
-        if args.empty?
-          @indexes[method.to_s]
-        elsif args.length == 1
-          @indexes[method.to_s][args.first]
-        else
-          @indexes[method.to_s].values_at(*args)
-        end
-      else
-        super(method, *args)
-      end
-    end
-    
-    def load(options = {})
-      options = options.symbolize_keys
-      force_reload = !!options.delete(:reload)
-      request_hash = [:get, options].hash
-      if loaded? && !force_reload && request_hash == @last_request_hash
-        self
-      else
-        reset
-        @last_request_hash = request_hash
-        @raw = options[:raw]
-        if raw.nil? || force_reload
-          response = session.get(uri, options)
-          @raw = response.body
-        end
-        raw.each do |key, value|
-          case key
-          when "total", "offset"
-            instance_variable_set("@#{key}".to_sym, value)
-          when "links"
-            value.each{|link| define_link(Link.new(link))}
-          when "items"
-            value.each do |item|
-              self_link = (item['links'] || []).map{|link| Link.new(link)}.detect{|link| link.self?}
-              if self_link && self_link.valid?
-                self.push Resource.new(self_link.href, session).load(:raw => item)
-              else
-                session.logger.warn "Resource #{key} does not have a 'self' link. skipped."
-              end
-            end
+
+    def populate_object(key, value)
+      case key
+      when "links"
+        value.each{|link| define_link(Link.new(link))}
+      when "items"
+        value.each do |item|
+          self_link = (item['links'] || []).
+            map{|link| Link.new(link)}.detect{|link| link.self?}
+          if self_link && self_link.valid?
+            @items.push Resource.new(uri.merge(self_link.href), session).load(:body => item)
           else
-            case value
-            when Hash
-              @attributes.store(key, SpecialHash.new.replace(value)) unless @associations.has_key?(key)
-            when Array
-              @attributes.store(key, SpecialArray.new(value))
-            else
-              @attributes.store(key, value)
-            end
+            session.logger.warn "Resource #{key} does not have a 'self' link. skipped."
           end
         end
-        @state = :loaded
-        self
+      else
+        case value
+        when Hash
+          @properties.store(key, SpecialHash.new.replace(value)) unless @links.has_key?(key)
+        when Array
+          @properties.store(key, SpecialArray.new(value))
+        else
+          @properties.store(key, value)
+        end
       end
+    end    
+
+    def inspect
+      @items.inspect
     end
     
-    def respond_to?(method, *args)
-      @associations.has_key?(method.to_s) || super(method, *args)
+    # Returns the current number of items (not the total number) 
+    # in the collection.
+    def length
+      @items.length
     end
     
-    # Removed: use `y resource` to get pretty output
-    # def inspect(options = {:space => "\t"})
-    #   output = "#<#{self.class}:0x#{self.object_id.to_s(16)}"
-    #   if loaded?
-    #     output += "\n#{options[:space]}------------ META ------------"
-    #     output += "\n#{options[:space]}@uri: #{uri.inspect}"
-    #     output += "\n#{options[:space]}@offset: #{offset.inspect}"
-    #     output += "\n#{options[:space]}@total: #{total.inspect}"
-    #     @associations.each do |title, assoc|
-    #       output += "\n#{options[:space]}@#{title}: #{assoc.class.name}"
-    #     end
-    #     unless @attributes.empty?
-    #       output += "\n#{options[:space]}------------ PROPERTIES ------------"
-    #       @attributes.each do |key, value|
-    #         output += "\n#{options[:space]}#{key.inspect} => #{value.inspect}"
-    #       end
-    #     end
-    #     unless self.empty?        
-    #       output += "\n#{options[:space]}------------ ITEMS ------------"
-    #       self.each do |value|
-    #         output += "\n#{options[:space]}#{value.class.name}"
-    #       end
-    #     end
-    #   end
-    #   output += ">"
-    # end
-    
-    protected
-    def define_link(link)
-      if link.valid?
-        case link.rel
-        when 'parent'
-          @associations['parent'] = Resource.new(link.href, session)
-        when 'collection'
-          raw_included = link.resolved? ? raw[link.title] : nil
-          @associations[link.title] = Collection.new(link.href, session, 
-            :raw => raw_included,
-            :title => link.title)
-        when 'member'
-          raw_included = link.resolved? ? raw[link.title] : nil
-          @associations[link.title] = Resource.new(link.href, session, 
-            :title => link.title,
-            :raw => raw_included)
-        when 'self'
-          # we do nothing
+    def pretty_print(pp)
+      super(pp) do |pp|
+        if @items.length > 0
+          pp.breakable
+          pp.text "ITEMS (#{self["offset"]}..#{self["offset"]+@items.length})/#{self["total"]}"
+          pp.nest 2 do
+            @items.each_with_index do |item, i|
+              pp.breakable
+              pp.text "#<#{item.class}:0x#{item.object_id.to_s(16)} uid=#{item['uid'].inspect}>"            
+              pp.text "," if i < @items.length-1
+            end
+          end
         end
-      else 
-        session.logger.warn link.errors.join("\n")
       end
     end
+    
+    alias_method :size, :length
   end
 end