Class: MusicBrainz::Model::MBID

Inherits:
Object
  • Object
show all
Defined in:
lib/rbrainz/model/mbid.rb

Overview

Represents a MusicBrainz identifier.

A MusicBrainz identifier is an URI identifying a resource like an artist or a track. It consists of an URI prefix, the entity type it refers to and an UUID that identifies the referenced entity.

Example:

http://musicbrainz.org/artist/6a2ca1ac-408d-49b0-a7f6-cd608f2f684f
See

musicbrainz.org/doc/MusicBrainzIdentifier

Defined Under Namespace

Modules: PATTERN

Constant Summary collapse

UUID_REGEXP =

A regular expression describing the format of a UUID.

Regexp.new('^' + PATTERN::UUID + '$')
ENTITY_TYPE_REGEXP =

A regular expression to test if a string is a valid entity type.

Regexp.new('^' + PATTERN::ENTITY_TYPE + '$')
ENTITY_URI_REGEXP =

A regular expression describing a MusicBrainz identifier URI.

Regexp.new('^' + PATTERN::ENTITY_URI + '$')
ENTITY_URI =

The general format of a MusicBrainz identifier URI.

'http://musicbrainz.org/%s/%s'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(str, entity_type = nil) ⇒ MBID

Create a new MBID.

str can be either a complete identifier or just the UUID part of it. In the latter case the entity type (:artist, :label, :release_group, :release or :track) has to be specified as well.

Examples:

require 'rbrainz'
include MusicBrainz
id = Model::MBID.new('http://musicbrainz.org/artist/10bf95b6-30e3-44f1-817f-45762cdc0de0')
id = Model::MBID.new('10bf95b6-30e3-44f1-817f-45762cdc0de0', :artist)
Raises

UnknownEntityError, EntityTypeNotMatchingError, InvalidMBIDError



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/rbrainz/model/mbid.rb', line 104

def initialize(str, entity_type=nil)
  str = str.to_s if str.respond_to? :to_s
  unless is_valid_entity_type_or_nil(entity_type)
    raise UnknownEntityError, entity_type
  end
  entity_type = Utils.entity_type_to_symbol(entity_type)
  
  if str =~ ENTITY_URI_REGEXP
    @entity = Utils.entity_type_to_symbol($1)
    @uuid = $2.downcase
    unless entity_type.nil? || @entity == entity_type
      raise EntityTypeNotMatchingError, "#{@entity}, #{entity_type}"
    end
  elsif str =~ UUID_REGEXP
    unless entity_type
      raise UnknownEntityError, "nil is not a valid entity type"
    end
    @entity = entity_type
    @uuid = str.downcase
  else
    raise InvalidMBIDError, str
  end
end

Instance Attribute Details

#entity ⇒ Object (readonly)

The entity type (:artist, :label, :release_group, :release, :track) this MBID references.



50
51
52
 
# File 'lib/rbrainz/model/mbid.rb', line 50

def entity
  @entity
end

#uuid ⇒ Object (readonly)

The UUID of the referenced entity.



53
54
55
 
# File 'lib/rbrainz/model/mbid.rb', line 53

def uuid
  @uuid
end

Class Method Details

.parse(str, entity_type = nil) ⇒ Object

Tries to convert str into a MBID using its to_mbid method.

If str does not respond to to_mbid a new MBID is created using the given parameters.

See

new

See

String#to_mbid, URI::HTTP#to_mbid

Raises

UnknownEntityError, EntityTypeNotMatchingError, InvalidMBIDError



81
82
83
84
85
86
87
 
# File 'lib/rbrainz/model/mbid.rb', line 81

def self.parse(str, entity_type=nil)
  if str.respond_to? :to_mbid
    str.to_mbid(entity_type)
  else
    MBID.new(str, entity_type)
  end
end

Instance Method Details

#==(other) ⇒ Object

Compares this MBID with another one.

Two MBIDs are considered equal if both their entity type and their UUID are equal.



150
151
152
153
 
# File 'lib/rbrainz/model/mbid.rb', line 150

def ==(other)
  other = other.to_mbid if other.respond_to? :to_mbid
  self.entity == other.entity and self.uuid == other.uuid
end

#to_mbid(entity_type = nil) ⇒ Object

Returns self.

If entity_type is given it must match the entity type of the MBID or an EntityTypeNotMatchingError will be raised.

Raises

EntityTypeNotMatchingError



134
135
136
137
138
139
 
# File 'lib/rbrainz/model/mbid.rb', line 134

def to_mbid(entity_type=nil)
  unless entity_type.nil? || @entity == entity_type
    raise EntityTypeNotMatchingError, "#{self.entity}, #{entity_type}"
  end
  self
end

#to_s ⇒ Object

Returns the string representation of the MBID (that is the complete URI).



142
143
144
 
# File 'lib/rbrainz/model/mbid.rb', line 142

def to_s
  ENTITY_URI % [Utils.entity_type_to_string(entity), uuid]
end