Class: Ur::Weblink

Inherits:
Object
  • Object
show all
Includes:
JSI::Util::Private::FingerprintHash::Immutable
Defined in:
lib/ur/weblink.rb

Overview

a RFC5988 Web Link

https://tools.ietf.org/html/rfc5988

Defined Under Namespace

Classes: Error, NoContextError, ParseError

Constant Summary collapse

ATTR_CHAR =

defined in https://tools.ietf.org/html/rfc5987#section-3.2.1

/[a-zA-Z0-9!#\$&+\-.^_`|~]/.freeze
PTOKEN = 
%r([a-zA-Z0-9!#\$%&'()*+\-./:<=>?@\[\]^_`{|}~]).freeze
QUOTED_STRING = 
/"([^"]*)"/.freeze
ATTRIBUTE_PAIR =

attributes: semicolon, some attr_chars, an optional asterisk, equals, and a quoted string or series of unquoted ptokens

/\s*;\s*(#{ATTR_CHAR.source}+\*?)\s*=\s*(?:#{QUOTED_STRING.source}|(#{PTOKEN.source}+))\s*/.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(target_uri, attributes, context_uri = nil) ⇒ Weblink

Returns a new instance of Weblink.



63
64
65
66
67
68
 
# File 'lib/ur/weblink.rb', line 63

def initialize(target_uri, attributes, context_uri=nil)
  @target_uri = JSI::Util.uri(target_uri)
  @attributes = attributes
  @context_uri = JSI::Util.uri(context_uri)
  freeze
end

Instance Attribute Details

#attributes ⇒ Object (readonly)

link attributes



96
97
98
 
# File 'lib/ur/weblink.rb', line 96

def attributes
  @attributes
end

#context_uri ⇒ Object (readonly) Also known as: context_iri

the context uri of the link, as an Addressable URI. this URI must be absolute, and the target_uri may be resolved against it. this is most typically the request URI of a request to a service



72
73
74
 
# File 'lib/ur/weblink.rb', line 72

def context_uri
  @context_uri
end

#target_uri ⇒ Object (readonly) Also known as: target_iri

returns the target URI as an Addressable::URI



78
79
80
 
# File 'lib/ur/weblink.rb', line 78

def target_uri
  @target_uri
end

Class Method Details

parses an array of Web Links from the value an HTTP Link header, as described in https://tools.ietf.org/html/rfc5988#section-5

returns an Array of Weblink objects



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/ur/weblink.rb', line 35

def self.parse_link_value(link_value, context_uri=nil)
  links = []

  return links unless link_value

  ss = StringScanner.new(link_value)
  parse_fail = proc do
    raise ParseError, "Unable to parse link value: #{link_value} " +
      "around character #{ss.pos}: #{ss.peek(link_value.length - ss.pos)}"
  end

  while !ss.eos?
    # get the target_uri, within some angle brackets
    ss.scan(/\s*<([^>]+)>/) || parse_fail.call
    target_uri = JSI::Util.uri(ss[1].freeze)
    attributes = {}
    while ss.scan(ATTRIBUTE_PAIR)
      attributes[ss[1].freeze] = (ss[2] || ss[3]).freeze
    end
    links << new(target_uri, attributes.freeze, context_uri)
    unless ss.eos?
      # either the string ends or has a comma followed by another link
      ss.scan(/\s*,\s*/) || parse_fail.call
    end
  end
  links.freeze
end

Instance Method Details

#[](attribute_key) ⇒ Object

subscript returns an attribute of this Link, if defined, otherwise nil



99
100
101
 
# File 'lib/ur/weblink.rb', line 99

def [](attribute_key)
  @attributes[attribute_key]
end

#absolute_target_uri ⇒ Object

attempts to make target_uri absolute, using context_uri if available. raises if there is not information available to make an absolute target URI



85
86
87
88
89
90
91
92
93
 
# File 'lib/ur/weblink.rb', line 85

def absolute_target_uri
  if target_uri.absolute?
    target_uri
  elsif context_uri
    context_uri + target_uri
  else
    raise NoContextError, "Target URI is relative but no Context URI given - cannot determine absolute target URI"
  end
end

#jsi_fingerprint ⇒ Object 



124
125
126
127
128
129
130
131
 
# File 'lib/ur/weblink.rb', line 124

def jsi_fingerprint
  {
    class: Weblink,
    target_uri: @target_uri,
    attributes: @attributes,
    context_uri: @context_uri,
  }.freeze
end

#rel ⇒ Object Also known as: relation_type

link rel attribute



104
105
106
 
# File 'lib/ur/weblink.rb', line 104

def rel
  self['rel']
end

#rel?(other_rel) ⇒ Boolean

compares relation types in a case-insensitive manner as mandated in https://tools.ietf.org/html/rfc5988#section-4.1

Returns:

  • (Boolean) 


112
113
114
 
# File 'lib/ur/weblink.rb', line 112

def rel?(other_rel)
  rel && other_rel && rel.downcase == other_rel.downcase
end

#to_s ⇒ Object

a string of this weblink, appropriate for adding to a Link header



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

def to_s
  "<#{target_uri}>" + attributes.map { |k,v| %Q(; #{k}="#{v}") }.join('')
end