Class: Scribd::Resource Abstract

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

Overview

This class is abstract.

Describes a remote object that the Scribd API lets you interact with. All such objects are modeled after the Active Record 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:

<pre><code>

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

</code></pre>

The specific attributes that a Document or a User or any other resource has are not saved 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:

<pre><code>

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.

</code></pre>

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

Category, Collection, Document, User

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Resource

Initializes instance variables.

Parameters:

  • options (Hash) (defaults to: {}) —

    Initial attributes for the new object.



43
44
45
46
47
 
# File 'lib/scribd/resource.rb', line 43

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:

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

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



155
156
157
158
159
160
161
162
 
# File 'lib/scribd/resource.rb', line 155

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 = {}) ⇒ Scribd::Resource

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.

Parameters:

  • options (Hash) (defaults to: {}) —

    Initial attributes for the new object.

Returns:



61
62
63
64
65
 
# File 'lib/scribd/resource.rb', line 61

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

.find(options) ⇒ Object

This method is abstract.

This method is implemented by subclasses.

Raises:

  • (NotImplementedError) 


75
76
77
 
# File 'lib/scribd/resource.rb', line 75

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

Instance Method Details

#created? ⇒ true, false

corresponds to something on the Scribd website.

Returns:

  • (true, false) —

    Whether this resource has been created remotely, and



95
96
97
 
# File 'lib/scribd/resource.rb', line 95

def created?
  @created
end

#destroy ⇒ Object

This method is abstract.

This method is implemented by subclasses.

Raises:

  • (NotImplementedError) 


81
82
83
 
# File 'lib/scribd/resource.rb', line 81

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

#inspect ⇒ Object 



165
166
167
 
# File 'lib/scribd/resource.rb', line 165

def inspect
  "#<#{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) ⇒ String?

Returns the value of an attribute.

Parameters:

  • attribute (#to_sym) —

    The attribute to read.

Returns:

  • (String) —

    The value of the attribute.

  • (nil) —

    If the attribute could not be read.

Raises:

  • (ArgumentError) —

    If an invalid value for @attribute@ is given.



106
107
108
109
 
# File 'lib/scribd/resource.rb', line 106

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) ⇒ Hash<Symbol -> String

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

Parameters:

  • attributes (Enumerable<String, Symbol>) —

    The attributes to read.

Returns:

  • (Hash<Symbol -> String) —

    The attribute values.

Raises:

  • (ArgumentError) —

    If an invalid value for @attributes@ is provided.



118
119
120
121
122
123
124
 
# File 'lib/scribd/resource.rb', line 118

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

This method is abstract.

This method is implemented by subclasses.

Raises:

  • (NotImplementedError) 


69
70
71
 
# File 'lib/scribd/resource.rb', line 69

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

#saved? ⇒ true, false

remotely, and thus their local values reflect the remote values.

Returns:

  • (true, false) —

    Whether this resource’s attributes have been updated



88
89
90
 
# File 'lib/scribd/resource.rb', line 88

def saved?
  @saved
end

#scribd_id ⇒ Object

Return the Scribd ID for a resource, so as not to conflict with object.id



50
51
52
 
# File 'lib/scribd/resource.rb', line 50

def scribd_id
  @attributes[:id]
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-writable attributes are ignored.

values.

Parameters:

  • ] (Hash<#to_sym -> #to_s) —

    values The values to update and their new

Raises:

  • (ArgumentError) —

    If an invalid value for @values@ is provided.



134
135
136
137
138
 
# File 'lib/scribd/resource.rb', line 134

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