Class: Scribd::Resource

Inherits:
Object
  • Object
show all
Defined in:
lib/scribdresource.rb

Overview

Describes a remote object that the Scribd API lets you interact with. All such objects are modeled after the ActiveRecord ORM approach.

The Resource superclass is never directly used; you will interact with actual Scribd entities like Document and User, which inherit functionality from this superclass.

Objects have one or more attributes (also called fields) that can be accessed directly through synonymous methods. For instance, if your resource has an attribute title, you can get and set the title like so:

obj.title #=> "Title"
obj.title = "New Title"

The specific attributes that a Document or a User or any other resource has are not stored locally. They are downloaded remotely whenever a resource is loaded from the remote server. Thus, you can modify any attribute you want, though it may or may not have any effect:

doc = Scribd::Document.find(:text => 'foo').first
doc.self_destruct_in = 5.seconds #=> Does not produce error
doc.save #=> Has no effect, since that attribute doesn't exist. Your document does not explode.

As shown above, when you make changes to an attribute, these changes are not immediately reflected remotely. They are only stored locally until such time as save is called. When you call save, the remote object is updated to reflect the changes you made in its API instance.

Direct Known Subclasses

Document, User

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Resource

Initializes instance variables.



35
36
37
38
39
 
# File 'lib/scribdresource.rb', line 35

def initialize(options={})
  @saved = false
  @created = false
  @attributes = Hash.new
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(meth, *args) ⇒ Object

Gets or sets attributes for the resource. Any named attribute can be retrieved for changed through a method call, even if it doesn’t exist. Such attributes will be ignored and purged when the document is saved:

doc = Scribd::Document.new
doc.foobar #=> Returns nil
doc.foobar = 12
doc.foobar #=> Returns 12
doc.save
doc.foobar #=> Returns nil

Because of this, no Scribd resource will ever raise NoMethodError.



126
127
128
129
130
131
132
133
 
# File 'lib/scribdresource.rb', line 126

def method_missing(meth, *args)
  if meth.to_s =~ /(\w+)=/ then
    raise ArgumentError, "Only one parameter can be passed to attribute=" unless args.size == 1
    @attributes[$1.to_sym] = args[0]
  else
    @attributes[meth]
  end
end

Class Method Details

.create(options = {}) ⇒ Object

Creates a new instance with the given attributes, saves it immediately, and returns it. You should call its created? method if you need to verify that the object was saved successfully.



45
46
47
48
49
 
# File 'lib/scribdresource.rb', line 45

def self.create(options={})
  obj = new(options)
  obj.save
  obj
end

.find(options) ⇒ Object

Throws NotImplementedError by default.

Raises:

  • (NotImplementedError) 


59
60
61
 
# File 'lib/scribdresource.rb', line 59

def self.find(options)
  raise NotImplementedError, "Cannot find #{self.class.to_s} objects"
end

Instance Method Details

#created? ⇒ Boolean

Returns true if this document has been created remotely, and corresponds to a document on the Scribd website.

Returns:

  • (Boolean) 


79
80
81
 
# File 'lib/scribdresource.rb', line 79

def created?
  @created
end

#destroy ⇒ Object

Throws NotImplementedError by default.

Raises:

  • (NotImplementedError) 


65
66
67
 
# File 'lib/scribdresource.rb', line 65

def destroy
  raise NotImplementedError, "Cannot destroy #{self.class.to_s} objects"
end

#inspect ⇒ Object

Pretty-print for debugging output of Scribd resources.



137
138
139
 
# File 'lib/scribdresource.rb', line 137

def inspect #:nodoc:
  "#<#{self.class.to_s} #{@attributes.select { |k, v| not v.nil? }.collect { |k,v| k.to_s + '=' + v.to_s }.join(', ')}>"
end

#read_attribute(attribute) ⇒ Object

Returns the value of an attribute, referenced by string or symbol, or nil if the attribute cannot be read.

Raises:

  • (ArgumentError) 


86
87
88
89
 
# File 'lib/scribdresource.rb', line 86

def read_attribute(attribute)
  raise ArgumentError, "Attribute must respond to to_sym" unless attribute.respond_to? :to_sym
  @attributes[attribute.to_sym]
end

#read_attributes(attributes) ⇒ Object

Returns a map of attributes to their values, given an array of attributes, referenced by string or symbol. Attributes that cannot be read are ignored.

Raises:

  • (ArgumentError) 


95
96
97
98
99
100
101
 
# File 'lib/scribdresource.rb', line 95

def read_attributes(attributes)
  raise ArgumentError, "Attributes must be listed in an Enumeration" unless attributes.kind_of?(Enumerable)
  raise ArgumentError, "All attributes must respond to to_sym" unless attributes.all? { |a| a.respond_to? :to_sym }
  keys = attributes.map(&:to_sym)
  values = @attributes.values_at(*keys)
  keys.zip(values).to_hsh
end

#save ⇒ Object

Throws NotImplementedError by default.

Raises:

  • (NotImplementedError) 


53
54
55
 
# File 'lib/scribdresource.rb', line 53

def save
  raise NotImplementedError, "Cannot save #{self.class.to_s} objects"
end

#saved? ⇒ Boolean

Returns true if this document’s attributes have been updated remotely, and thus their local values reflect the remote values.

Returns:

  • (Boolean) 


72
73
74
 
# File 'lib/scribdresource.rb', line 72

def saved?
  @saved
end

#write_attributes(values) ⇒ Object

Assigns values to attributes. Takes a hash that specifies the attribute-value pairs to update. Does not perform a save. Non-writeable attributes are ignored.

Raises:

  • (ArgumentError) 


107
108
109
110
111
 
# File 'lib/scribdresource.rb', line 107

def write_attributes(values)
  raise ArgumentError, "Values must be specified through a hash of attributes" unless values.kind_of? Hash
  raise ArgumentError, "All attributes must respond to to_sym" unless values.keys.all? { |a| a.respond_to? :to_sym }
  @attributes.update values.map { |k,v| [ k.to_sym, v ] }.to_hsh
end