Module: Praxis::ResourceDefinition::ClassMethods

Defined in:
lib/praxis/resource_definition.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#actions ⇒ Object (readonly)

Returns the value of attribute actions.



50
51
52
 
# File 'lib/praxis/resource_definition.rb', line 50

def actions
  @actions
end

#controller ⇒ Object

Returns the value of attribute controller.



61
62
63
 
# File 'lib/praxis/resource_definition.rb', line 61

def controller
  @controller
end

#metadata ⇒ Object (readonly)

opaque hash of user-defined medata, used to decorate the definition, and also available in the generated JSON documents



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

def metadata
  @metadata
end

#parent_prefix ⇒ Object (readonly)

Returns the value of attribute parent_prefix.



55
56
57
 
# File 'lib/praxis/resource_definition.rb', line 55

def parent_prefix
  @parent_prefix
end

#responses ⇒ Object (readonly)

Returns the value of attribute responses.



51
52
53
 
# File 'lib/praxis/resource_definition.rb', line 51

def responses
  @responses
end

#routing_prefix ⇒ Object 



160
161
162
163
164
 
# File 'lib/praxis/resource_definition.rb', line 160

def routing_prefix
  return @routing_prefix if @routing_prefix

  @routing_prefix = parent_prefix + prefix
end

#traits ⇒ Object (readonly)

Returns the value of attribute traits.



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

def traits
  @traits
end

#version_options ⇒ Object (readonly)

Returns the value of attribute version_options.



52
53
54
 
# File 'lib/praxis/resource_definition.rb', line 52

def version_options
  @version_options
end

#version_prefix ⇒ Object (readonly)

Returns the value of attribute version_prefix.



54
55
56
 
# File 'lib/praxis/resource_definition.rb', line 54

def version_prefix
  @version_prefix
end

Instance Method Details

#action(name, &block) ⇒ Object

Raises:

  • (ArgumentError) 


263
264
265
266
267
 
# File 'lib/praxis/resource_definition.rb', line 263

def action(name, &block)
  raise ArgumentError, "can not create ActionDefinition without block" unless block_given?
  raise ArgumentError, "Action names must be defined using symbols (Got: #{name} (of type #{name.class}))" unless name.is_a? Symbol
  @actions[name] = ActionDefinition.new(name, self, &block)
end

#action_defaults(&block) ⇒ Object 



227
228
229
230
231
232
233
 
# File 'lib/praxis/resource_definition.rb', line 227

def action_defaults(&block)
  if block_given?
    @action_defaults.instance_eval(&block)
  end

  @action_defaults
end

#canonical_path(action_name = nil) ⇒ Object 



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/praxis/resource_definition.rb', line 184

def canonical_path(action_name=nil)
  if action_name
    raise "Canonical path for #{self.name} is already defined as: '#{@canonical_action_name}'. 'canonical_path' can only be defined once." if @canonical_action_name
    @canonical_action_name = action_name
  else
    # Resolution of the actual action definition needs to be done lazily, since we can use the `canonical_path` stanza
    # at the top of the resource, well before the actual action is defined.
    unless @canonical_action
      href_action = @canonical_action_name || DEFAULT_RESOURCE_HREF_ACTION
      @canonical_action = actions.fetch(href_action) do
        raise "Error: trying to set canonical_href of #{self.name}. Action '#{href_action}' does not exist"
      end
    end
    return @canonical_action
  end
end

#describe(context: nil) ⇒ Object 



278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/praxis/resource_definition.rb', line 278

def describe(context: nil)
  {}.tap do |hash|
    hash[:description] = description
    hash[:media_type] = media_type.describe(true) if media_type
    hash[:actions] = actions.values.collect{|action| action.describe(context: context)}
    hash[:name] = self.name
    hash[:parent] = self.parent.id if self.parent
    hash[:display_name] = self.display_name
    hash[:metadata] = metadata
    hash[:traits] = self.traits
  end
end

#description(text = nil) ⇒ Object 



269
270
271
272
 
# File 'lib/praxis/resource_definition.rb', line 269

def description(text=nil)
  @description = text if text
  @description
end

#display_name(string = nil) ⇒ Object 



63
64
65
66
67
68
 
# File 'lib/praxis/resource_definition.rb', line 63

def display_name( string=nil )
  unless string
    return  @display_name ||= self.name.split("::").last  # Best guess at a display name?
  end
  @display_name = string
end

#headers(**opts, &block) ⇒ Object 



249
250
251
252
253
254
 
# File 'lib/praxis/resource_definition.rb', line 249

def headers(**opts, &block)
  warn 'DEPRECATED: ResourceDefinition.headers is deprecated. Use action_defaults instead.'
  action_defaults do
    headers **opts, &block
  end
end

#id ⇒ Object 



274
275
276
 
# File 'lib/praxis/resource_definition.rb', line 274

def id
  self.name.gsub('::'.freeze,'-'.freeze)
end

#inherit_params_from_parent(parent_action, **mapping) ⇒ Object 



143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/praxis/resource_definition.rb', line 143

def inherit_params_from_parent(parent_action, **mapping)
  actions.each do |name, action|
    action.params do
      mapping.each do |parent_name, name|
        next if action.params && action.params.attributes.key?(name)

        parent_attribute = parent_action.params.attributes[parent_name]

        attribute name, parent_attribute.type, parent_attribute.options
      end
    end
  end

end

#media_type(media_type = nil) ⇒ Object 



92
93
94
95
96
97
98
99
 
# File 'lib/praxis/resource_definition.rb', line 92

def media_type(media_type=nil)
  return @media_type if media_type.nil?

  if media_type.kind_of?(String)
    media_type = SimpleMediaType.new(media_type)
  end
  @media_type = media_type
end

#nodoc! ⇒ Object 



291
292
293
 
# File 'lib/praxis/resource_definition.rb', line 291

def nodoc!
  metadata[:doc_visibility] = :none
end

#on_finalize ⇒ Object 



70
71
72
73
74
75
76
 
# File 'lib/praxis/resource_definition.rb', line 70

def on_finalize
  if block_given?
    @on_finalize << Proc.new
  end

  @on_finalize
end

#params(type = Attributor::Struct, **opts, &block) ⇒ Object 



235
236
237
238
239
240
 
# File 'lib/praxis/resource_definition.rb', line 235

def params(type=Attributor::Struct, **opts, &block)
  warn 'DEPRECATED: ResourceDefinition.params is deprecated. Use it in action_defaults instead.'
  action_defaults do
    params type, **opts, &block
  end
end

#parent(parent = nil, **mapping) ⇒ Object 



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/praxis/resource_definition.rb', line 102

def parent(parent=nil, **mapping)
  return @parent if parent.nil?

  @routing_prefix = nil # reset routing_prefix

  parent_action = parent.canonical_path
  parent_route = parent_action.primary_route.path

  # if a mapping is passed, it *must* resolve any param name conflicts
  unless mapping.any?
    # assume last capture is the relevant one to replace
    # if not... then I quit.
    parent_param_name = parent_route.names.last

    # more assumptions about names
    parent_name = parent.name.demodulize.underscore.singularize

    # put it together to find what we should call this new param
    param = "#{parent_name}_#{parent_param_name}".to_sym
    mapping[parent_param_name.to_sym] = param
  end

  # complete the mapping and massage the route
  parent_route.names.collect(&:to_sym).each do |name|
    if mapping.key?(name)
      param = mapping[name]
      # FIXME: this won't handle URI Template type paths, ie '/{parent_id}'
      prefixed_path = parent_action.primary_route.prefixed_path
      @parent_prefix = prefixed_path.gsub(/(:)(#{name})(\W+|$)/, "\\1#{param.to_s}\\3")
    else
      mapping[name] = name
    end
  end

  self.on_finalize do
    self.inherit_params_from_parent(parent_action, **mapping)
  end

  @parent = parent
end

#parse_href(path) ⇒ Object 



205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/praxis/resource_definition.rb', line 205

def parse_href(path)
  if path.kind_of?(::URI::Generic)
    path = path.path
  end
  param_values = canonical_path.primary_route.path.params(path)
  attrs = canonical_path.params.attributes
  param_values.each_with_object({}) do |(key,value),hash|
    hash[key.to_sym] = attrs[key.to_sym].load(value,[key])
  end
rescue => e
  raise Praxis::Exception.new("Error parsing or coercing parameters from href: #{path}\n"+e.message)
end

#payload(type = Attributor::Struct, **opts, &block) ⇒ Object 



242
243
244
245
246
247
 
# File 'lib/praxis/resource_definition.rb', line 242

def payload(type=Attributor::Struct, **opts, &block)
  warn 'DEPRECATED: ResourceDefinition.payload is deprecated. Use action_defaults instead.'
  action_defaults do
    payload type, **opts, &block
  end
end

#prefix(prefix = nil) ⇒ Object 



86
87
88
89
90
 
# File 'lib/praxis/resource_definition.rb', line 86

def prefix(prefix=nil)
  return @prefix if prefix.nil?
  @routing_prefix = nil # reset routing_prefix
  @prefix = prefix
end

#response(name, **args) ⇒ Object 



256
257
258
259
260
261
 
# File 'lib/praxis/resource_definition.rb', line 256

def response(name, **args)
  warn 'DEPRECATED: ResourceDefinition.response is deprecated. Use action_defaults instead.'
  action_defaults do
    response name, **args
  end
end

#routing(&block) ⇒ Object

FIXME: this is inconsistent with the rest of the magic DSL convention.



79
80
81
82
83
84
 
# File 'lib/praxis/resource_definition.rb', line 79

def routing(&block)
  warn "DEPRECATED: ResourceDefinition.routing is deprecated use prefix directly instead."

  # eval this assuming it will only call #prefix
  self.instance_eval(&block)
end

#to_href(params) ⇒ Object 



201
202
203
 
# File 'lib/praxis/resource_definition.rb', line 201

def to_href( params )
  canonical_path.primary_route.path.expand(params)
end

#trait(trait_name) ⇒ Object Also known as: use 



218
219
220
221
222
223
224
 
# File 'lib/praxis/resource_definition.rb', line 218

def trait(trait_name)
  unless ApiDefinition.instance.traits.has_key? trait_name
    raise Exceptions::InvalidTrait.new("Trait #{trait_name} not found in the system")
  end
  trait = ApiDefinition.instance.traits.fetch(trait_name)
  @traits << trait_name
end

#version(version = nil, options = nil) ⇒ Object 



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/praxis/resource_definition.rb', line 167

def version(version=nil, options=nil)
  return @version unless version

  @version = version

  unless options.nil?
    warn 'DEPRECATED: ResourceDefinition.version with options is no longer supported. Define in api global info instead.'

    @version_options = options
    version_using = Array(@version_options[:using])
    if version_using.include?(:path)
      @version_prefix = "#{Praxis::Request::path_version_prefix}#{self.version}"
    end
  end
end