Class: Doze::MediaType

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

Constant Summary collapse

NAME_LOOKUP = 
{}
BY_EXTENSION = 
{}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, options = {}) ⇒ MediaType

name: primary name for the media type options:

:aliases      :: extra names to add to #names
:output_name  :: defaults to name
:also_matches :: extra names to add to matches_names, in addition to names and output_name
:entity_class
:plus_suffix
:extension



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/doze/media_type.rb', line 76

def initialize(name, options={})
  @names = [name]
  @names.push(*options[:aliases]) if options[:aliases]

  @output_name = options[:output_name]

  @matches_names = @names.dup
  @matches_names << @output_name if @output_name
  @matches_names.push(*options[:also_matches]) if options[:also_matches]
  @matches_names.uniq!

  @entity_class = options[:entity_class] || Doze::Entity
  @plus_suffix = options[:plus_suffix]

  @extension = options[:extension]
end

Instance Attribute Details

#entity_class ⇒ Object (readonly)

Media types may be configured to use a different entity class to the default (Doze::Entity) for an entity of that media type



27
28
29
 
# File 'lib/doze/media_type.rb', line 27

def entity_class
  @entity_class
end

#extension ⇒ Object (readonly)

Media type may be associated with a particular file extension, eg image/jpeg with .jpeg Registered media types may be looked up by extension, eg this is used when :media_type_extensions is enabled on the application.

If you register more than one media type with the same extension the most recent one will take priority, ie probably best not to do this.



40
41
42
 
# File 'lib/doze/media_type.rb', line 40

def extension
  @extension
end

#matches_names ⇒ Object (readonly)

Media type strings which this media type matches. Matching means this media type is acceptable in reponse to a request for the media type string in question. Eg application/xhtml+xml is acceptable in response to a request for application/xml or text/xml, so text/xml and application/xml may be listed under the matches_names of application/xhtml+xml



17
18
19
 
# File 'lib/doze/media_type.rb', line 17

def matches_names
  @matches_names
end

#names ⇒ Object (readonly)

Names for this media type. Names should uniquely identify the media type, so eg [audio/x-mpeg3, audio/mp3] might both be names of one media type, but application/xml is not a name of application/xhtml+xml; see matches_names



8
9
10
 
# File 'lib/doze/media_type.rb', line 8

def names
  @names
end

#plus_suffix ⇒ Object (readonly)

Some serialization media types have a plus suffix which can be used to create derived types, eg application/xml, with plus_suffix ‘xml’, could have application/xhtml+xml as a derived type see register_derived_type



32
33
34
 
# File 'lib/doze/media_type.rb', line 32

def plus_suffix
  @plus_suffix
end

Class Method Details

.[](name) ⇒ Object 



64
65
66
 
# File 'lib/doze/media_type.rb', line 64

def self.[](name)
  NAME_LOOKUP[name] || new(name)
end

.register(name, options = {}) ⇒ Object

Creates and registers a media_type instance by its names for lookup via []. This means this instance will be used when a client submits an entity with any of the given names. You’re recommended to register any media types that are frequently used as well, even if you don’t need any special options or methods for them.



47
48
49
 
# File 'lib/doze/media_type.rb', line 47

def self.register(name, options={})
  new(name, options).register!
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql?

Equality override to help in case multiple temporary instances of a media type of a given name are compared.



126
127
128
 
# File 'lib/doze/media_type.rb', line 126

def ==(other)
  super || (other.is_a?(Doze::MediaType) && other.name == name)
end

#hash ⇒ Object 



132
133
134
 
# File 'lib/doze/media_type.rb', line 132

def hash
  name.hash
end

#major ⇒ Object 



93
94
95
 
# File 'lib/doze/media_type.rb', line 93

def major
  @major ||= name.split('/', 2)[0]
end

#matches_prefix?(prefix) ⇒ Boolean

Returns:

  • (Boolean) 


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

def matches_prefix?(prefix)
  @matches_names.any? {|name| name.start_with?(prefix)}
end

#minor ⇒ Object 



97
98
99
 
# File 'lib/doze/media_type.rb', line 97

def minor
  @major ||= name.split('/', 2)[1]
end

#name ⇒ Object

The primary name for this media type.



11
 
# File 'lib/doze/media_type.rb', line 11

def name; @names.first; end

#new_entity(options, &b) ⇒ Object

Create a new entity of this media_type. Uses entity_class



113
114
115
 
# File 'lib/doze/media_type.rb', line 113

def new_entity(options, &b)
  @entity_class.new(self, options, &b)
end

#output_name ⇒ Object

The name used to describe this media type to clients (sometimes we want to use a more detailed media type internally). Defaults to name



21
22
23
 
# File 'lib/doze/media_type.rb', line 21

def output_name
  @output_name || @names.first
end

#register! ⇒ Object 



51
52
53
54
55
56
57
58
 
# File 'lib/doze/media_type.rb', line 51

def register!
  names.each do |n|
    raise "Attempt to register media_type name #{n} twice" if NAME_LOOKUP.has_key?(n)
    NAME_LOOKUP[n] = self
  end
  register_extension!
  self
end

#register_derived_type(name_prefix, options = {}) ⇒ Object

Helper to derive eg application/vnd.foo+json from application/json and name_prefix application/vnd.foo



102
103
104
105
106
107
108
109
110
 
# File 'lib/doze/media_type.rb', line 102

def register_derived_type(name_prefix, options={})
  options = {
    :also_matches => [],
    :entity_class => @entity_class
  }.merge!(options)
  options[:also_matches].push(*self.matches_names)
  name = @plus_suffix ? "#{name_prefix}+#{plus_suffix}" : name_prefix
  self.class.register(name, options)
end

#register_extension! ⇒ Object 



60
61
62
 
# File 'lib/doze/media_type.rb', line 60

def register_extension!
  BY_EXTENSION[@extension] = self if @extension
end

#subtype?(other) ⇒ Boolean

Returns:

  • (Boolean) 


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

def subtype?(other)
  @matches_names.include?(other.name)
end