Class: WSDSL::Response::Element

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

Overview

The Response element class describing each element of a service response. Instances are usually not instiated directly but via the Response#element accessor.

See Also:

Since:

  • 0.0.3

Direct Known Subclasses

Vector

Defined Under Namespace

Classes: Attribute, MetaAttribute

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, type = nil) ⇒ Element

param [String, Symbol] name The name of the element param [String, Symbol] type The optional type of the element

Since:

  • 0.0.3



147
148
149
150
151
152
153
154
155
156
157
158
# File 'lib/response.rb', line 147

def initialize(name, type=nil)
  # sets a documentation placeholder since the response doc is defined at the same time
  # the response is defined.
  @doc        = Documentation::ElementDoc.new(name)
  @name       = name
  @type       = type
  @attributes = []
  @meta_attributes = []
  @vectors    = []
  @key        = nil
  # we don't need to initialize the nested elements, by default they should be nil
end

Instance Attribute Details

#attributesArray<WSDSL::Response::Element::Attribute> (readonly) Also known as: properties

Returns An array of attributes.

Returns:

Since:

  • 0.0.3



121
122
123
# File 'lib/response.rb', line 121

def attributes
  @attributes
end

#docWSDSL::Documentation::ElementDoc (readonly)

Returns Response element documentation.

Returns:

Since:

  • 0.0.3



133
134
135
# File 'lib/response.rb', line 133

def doc
  @doc
end

#elementsNilClass, Array<WSDSL::Response::Element> (readonly) Also known as: objects

Returns The optional nested elements.

Returns:

Since:

  • 0.0.3



136
137
138
# File 'lib/response.rb', line 136

def elements
  @elements
end

#key(name = nil, opts = {}) ⇒ Object (readonly)

Getter/setter for the key meta attribute. A key name can be used to lookup an object by a primary key for instance.

Parameters:

  • name (Symbol, String) (defaults to: nil)

    the name of the key attribute.

  • opts (Hash) (defaults to: {})

    the options attached with the key.

Since:

  • 0.0.3



117
118
119
# File 'lib/response.rb', line 117

def key
  @key
end

#meta_attributesArray<WSDSL::Response::Element::MetaAttribute> (readonly)

Returns An array of meta attributes.

Returns:

Since:

  • 0.0.3



125
126
127
# File 'lib/response.rb', line 125

def meta_attributes
  @meta_attributes
end

#nameString, #to_s (readonly)

Returns The name of the element.

Returns:

  • (String, #to_s)

    The name of the element

Since:

  • 0.0.3



111
112
113
# File 'lib/response.rb', line 111

def name
  @name
end

#type(name = nil, opts = {}) ⇒ Object (readonly)

Getter/setter for the type meta attribute.

Parameters:

  • name (Symbol, String) (defaults to: nil)

    the name of the type attribute.

  • opts (Hash) (defaults to: {})

    the options attached with the key.

Since:

  • 0.0.3



114
115
116
# File 'lib/response.rb', line 114

def type
  @type
end

#vectorsArray (readonly)

Returns An array of vectors/arrays.

Returns:

  • (Array)

    An array of vectors/arrays

Since:

  • 0.0.3



129
130
131
# File 'lib/response.rb', line 129

def vectors
  @vectors
end

Instance Method Details

#array(name, type = nil) {|Vector| ... } ⇒ Array<WSDSL::Response::Vector>

Defines an array aka vector of elements.

Examples:

Defining an element array called ‘player_creation_rating’

element.array 'player_creation_rating', 'PlayerCreationRating' do |a|
  a.attribute :comments  => :string
  a.attribute :player_id => :integer
  a.attribute :rating    => :integer
  a.attribute :username  => :string
end

Parameters:

  • name (String, Symbol)

    The name of the array element.

  • type (String, Symbol) (defaults to: nil)

    Optional type information, useful to store the represented object types for instance.

  • &block (Proc)

    A block to execute against the newly created array.

Yields:

  • (Vector)

    the newly created array/vector instance

Returns:

See Also:

Since:

  • 0.0.3



232
233
234
235
236
# File 'lib/response.rb', line 232

def array(name, type=nil)
  vector = Vector.new(name, type)
  yield(vector) if block_given?
  @vectors << vector
end

#arraysArray<WSDSL::Response::Vector>

Returns the arrays/vectors contained in the response. This is an alias to access @vectors

Returns:

See Also:

  • @vectors

Since:

  • 0.0.3



244
245
246
# File 'lib/response.rb', line 244

def arrays
  @vectors
end

#attribute(opts, extra_opts = {}) ⇒ Array<WSDSL::Response::Attribute>

sets a new attribute and returns the entire list of attributes

Examples:

Creation of a response attribute called ‘best_lap_time’

service.response do |response|
 response.element(:name => "my_stats", :type => 'Leaderboard') do |e|
   e.attribute "best_lap_time"       => :float,    :doc => "Best lap time in seconds."
 end
end

Parameters:

  • opts (Hash)

    An element’s attribute options

Options Hash (opts):

  • attribute_name (String, Symbol)

    The name of the attribute, the value being the type

  • :doc (String, Symbol)

    The attribute documentation

  • :mock (String, Symbol)

    An optional mock value used by service related tools

Returns:

  • (Array<WSDSL::Response::Attribute>)

Raises:

  • (ArgumentError)

Since:

  • 0.0.3



176
177
178
179
180
181
182
183
184
185
186
# File 'lib/response.rb', line 176

def attribute(opts, extra_opts={})
  raise ArgumentError unless opts.is_a?(Hash) && extra_opts.is_a?(Hash)
  new_attribute = Attribute.new(opts, extra_opts)
  @attributes << new_attribute
  # document the attribute if description available
  # we might want to have a placeholder message when a response attribute isn't defined
  if opts.merge!(extra_opts).has_key?(:doc)
    @doc.attribute(new_attribute.name, opts[:doc])
  end
  @attributes
end

#boolean(name = nil, opts = {}) ⇒ Object

Shortcut to create a string attribute

Parameters:

  • name (Symbol, String) (defaults to: nil)

    the name of the attribute.

  • opts (Hash) (defaults to: {})

    the attribute options.

Since:

  • 0.0.3



324
325
326
# File 'lib/response.rb', line 324

def boolean(name=nil, opts={})
  attribute({name => :boolean}, opts)
end

#datetime(name = nil, opts = {}) ⇒ Object

Shortcut to create a string attribute

Parameters:

  • name (Symbol, String) (defaults to: nil)

    the name of the attribute.

  • opts (Hash) (defaults to: {})

    the attribute options.

Since:

  • 0.0.3



332
333
334
# File 'lib/response.rb', line 332

def datetime(name=nil, opts={})
  attribute({name => :datetime}, opts)
end

#element(opts = {}) {|WSDSL::Response::Element| ... } ⇒ Array<WSDSL::Response::Element>

Defines a new element and yields the content of an optional block Each new element is then stored in the elements array.

Examples:

create an element called ‘my_stats’.

service.response do |response|
 response.element(:name => "my_stats", :type => 'Leaderboard')
end

Parameters:

  • opts (Hash) (defaults to: {})

    Options used to define the element

Options Hash (opts):

  • :name (String, Symbol)

    The element name

  • :type (String, Symbol)

    The optional type

Yields:

Returns:

Since:

  • 0.0.3



263
264
265
266
267
268
269
# File 'lib/response.rb', line 263

def element(opts={})
  el = Element.new(opts[:name], opts[:type])
  yield(el) if block_given?
  @elements ||= []
  @elements << el
  el
end

#float(name = nil, opts = {}) ⇒ Object

Shortcut to create a string attribute

Parameters:

  • name (Symbol, String) (defaults to: nil)

    the name of the attribute.

  • opts (Hash) (defaults to: {})

    the attribute options.

Since:

  • 0.0.3



316
317
318
# File 'lib/response.rb', line 316

def float(name=nil, opts={})
  attribute({name => :float}, opts)
end

#integer(name = nil, opts = {}) ⇒ Object

Shortcut to create a string attribute

Parameters:

  • name (Symbol, String) (defaults to: nil)

    the name of the attribute.

  • opts (Hash) (defaults to: {})

    the attribute options.

Since:

  • 0.0.3



308
309
310
# File 'lib/response.rb', line 308

def integer(name=nil, opts={})
  attribute({name => :integer}, opts)
end

#meta_attribute(opts) ⇒ Array<WSDSL::Response::MetaAttribute>

sets a new meta attribute and returns the entire list of meta attributes

Examples:

Creation of a response attribute called ‘best_lap_time’

service.response do |response|
 response.element(:name => "my_stats", :type => 'Leaderboard') do |e|
   e.meta_attribute "id"       => :key
 end
end

Parameters:

  • opts (Hash)

    An element’s attribute options

Options Hash (opts):

  • attribute_name (String, Symbol)

    The name of the attribute, the value being the type

  • :mock (String, Symbol)

    An optional mock value used by service related tools

Returns:

  • (Array<WSDSL::Response::MetaAttribute>)

Raises:

  • (ArgumentError)

Since:

  • 0.0.3



203
204
205
206
207
208
209
# File 'lib/response.rb', line 203

def meta_attribute(opts)
  raise ArgumentError unless opts.is_a?(Hash)
  # extract the documentation part and add it where it belongs
  new_attribute = MetaAttribute.new(opts)
  @meta_attributes << new_attribute
  @meta_attributes
end

#object(name, opts = {}, &block) ⇒ Object

Shortcut to create a new element.

Parameters:

  • name (Symbol, String)

    the name of the element.

  • opts (Hash) (defaults to: {})

    the options for the newly created element.

Since:

  • 0.0.3



275
276
277
# File 'lib/response.rb', line 275

def object(name, opts={}, &block)
  element(opts.merge(:name => name), &block)
end

#string(name = nil, opts = {}) ⇒ Object

Shortcut to create a string attribute

Parameters:

  • name (Symbol, String) (defaults to: nil)

    the name of the attribute.

  • opts (Hash) (defaults to: {})

    the attribute options.

Since:

  • 0.0.3



300
301
302
# File 'lib/response.rb', line 300

def string(name=nil, opts={})
  attribute({name => :string}, opts)
end

#to_hashHash

Converts an element into a hash representation

Returns:

  • (Hash)

    the element attributes formated in a hash

Since:

  • 0.0.3



339
340
341
342
343
344
345
346
347
348
# File 'lib/response.rb', line 339

def to_hash
  attrs = {}
  attributes.each{ |attr| attrs[attr.name] = attr.type }
  elements.each{ |el| attrs[el.name] = el.to_hash } if elements
  if self.class == Vector
    name ? {name => [attrs]} : [attrs]
  else
    name ? {name => attrs} : attrs
  end
end

#to_htmlObject

Since:

  • 0.0.3



350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
# File 'lib/response.rb', line 350

def to_html
  output = ""
  if name
    output << "<li>"
    output << "<span class='label notice'>#{name}</span> of type <span class='label success'>#{self.is_a?(Vector) ? 'Array' : 'Object'}</span>"
  end
  if self.is_a? Vector
    output << "<h6>Properties of each array item:</h6>"
  else
    output << "<h6>Properties:</h6>"
  end
  output << "<ul>"
  properties.each do |prop|
    output << "<li><span class='label notice'>#{prop.name}</span> of type <span class='label success'>#{prop.type}</span> #{'(Can be blank or missing) ' if prop.opts && prop.opts.respond_to?(:[]) && prop.opts[:null]} "
    output <<  prop.doc unless prop.doc.blank?
    output << "</li>"
  end
  arrays.each{ |arr| output << arr.html }
  elements.each {|el| output << el.to_html } if elements
  output << "</ul>"
  output << "</li>" if name
  output
end