class OEmbed::Provider

An OEmbed::Provider has information about an individual oEmbed enpoint.

def <<(url)

@provider << %r{^http://my.service.com/((help)|(faq))/\d+[#\?].*}
@provider << "http://*.service.com/photo/*/slideshow"
@provider << "http://my.service.com/video/*"
For example:

or a Regexp.
with an asterisk, (see http://oembed.com/#section2.1 for details),
The url scheme can be either a String, containing wildcards specified
Adds the given url scheme to this Provider instance. 
def <<(url)
  if !url.is_a?(Regexp)
    full, scheme, domain, path = *url.match(%r{([^:]*)://?([^/?]*)(.*)})
    domain = Regexp.escape(domain).gsub("\\*", "(.*?)").gsub("(.*?)\\.", "([^\\.]+\\.)?")
    path = Regexp.escape(path).gsub("\\*", "(.*?)")
    url = Regexp.new("^#{Regexp.escape(scheme)}://#{domain}#{path}")
  end
  @urls << url
end

def build(url, query = {})

Deprecated:
  • *Note*: This method will be made private in the future.
def build(url, query = {})
  raise OEmbed::NotFound, url unless include?(url)
  query.delete(:timeout)
  query.delete(:max_redirects)
  query = query.merge(@required_query_params)
  query = query.merge({:url => ::CGI.escape(url)})
  # TODO: move this code exclusively into the get method, once build is private.
  this_format = (query[:format] ||= @format.to_s).to_s
  endpoint = @endpoint.clone
  if endpoint.include?("{format}")
    endpoint["{format}"] = this_format
    query.delete(:format)
  end
  base = endpoint.include?('?') ? '&' : '?'
  query = base + query.inject("") do |memo, (key, value)|
    "#{key}=#{value}&#{memo}"
  end.chop
  URI.parse(endpoint + query).instance_eval do
    @format = this_format
    def format
      @format
    end
    self
  end
end

def format 

def format
  @format
end

def get(url, query = {})

:max_redirects:: the number of times this request will follow 3XX redirects before throwing an error. Default: 4
:url:: will be ignored, replaced by the url param.
:format:: overrides this Provider's default request format.
:timeout:: specifies the timeout (in seconds) for the http request.
following special cases apply to the query Hash:
sent as query parameters in this request to the Provider endpoint. The
The query parameter should be a Hash of values which will be

given url and return the appropriate OEmbed::Response.
Send a request to the Provider endpoint to get information about the 
def get(url, query = {})
  query[:format] ||= @format
  OEmbed::Response.create_for(raw(url, query), self, url, query[:format].to_s)
end

def include?(url)

It will always return false of a provider has required_query_params that are not set.
against the Provider's URL schemes.
Determine whether the given url is supported by this Provider by matching 
def include?(url)
  return false unless required_query_params_set?
  @urls.empty? || !!@urls.detect{ |u| u =~ url }
end

def initialize(endpoint, positional_format = OEmbed::Formatter.default, format: nil, required_query_params: {})

@provider_with_auth.access_token = @my_access_token
# You can optionally override the value from `ENV['MY_SERVICE_ACCESS_TOKEN']`
@provider_with_auth = OEmbed::Provider.new("http://my.service.com/oembed", required_query_params: { access_token: 'MY_SERVICE_ACCESS_TOKEN' })
# If the endpoint requires an `access_token` be specified:

@xml_provider = OEmbed::Provider.new("http://my.service.com/oembed.{format}", format: :xml)
# "http://my.service.com/oembed.xml"
# If requests should be sent to:

@provider = OEmbed::Provider.new("http://my.service.com/oembed")
# "http://my.service.com/oembed?format=#{OEmbed::Formatter.default}"
# If requests should be sent to:
For example:

and the optional name of an environment variable (i.e. ENV) whose value will be used
representing query params that will be appended to the endpoint on each request
The `required_query_params:` option should be a Hash

# @deprecated *Note*: The `positional_format` is deprecated. Please used the named argument instead.

to this Provider (e.g. 'json'). Defaults to OEmbed::Formatter.default
The `format:` option should be the name of the default format for all request

representing the request format (e.g. "json").
In actual requests to this Provider, this string will be replaced with a String
oEmbed endpoint. The endpoint String may also contain a {format} portion.
The endpoint should be a String representing the http URI of the Provider's

endpoint.
Construct a new OEmbed::Provider instance, pointing at a specific oEmbed 
def initialize(endpoint, positional_format = OEmbed::Formatter.default, format: nil, required_query_params: {})
  endpoint_uri = URI.parse(endpoint.gsub(/[\{\}]/,'')) rescue nil
  raise ArgumentError, "The given endpoint isn't a valid http(s) URI: #{endpoint.to_s}" unless endpoint_uri.is_a?(URI::HTTP)
  @required_query_params = {}
  required_query_params.each do |param, default_env_var|
    param = param.to_sym
    @required_query_params[param] = nil
    set_required_query_params(param, ENV[default_env_var]) if default_env_var
    # Define a getter and a setter for each required_query_param
    define_singleton_method("#{param}") { @required_query_params[param] } unless respond_to?("#{param}")
    define_singleton_method("#{param}=") { |val| set_required_query_params(param, val) } unless respond_to?("#{param}=")
  end
  required_query_params_set?(reset_cache: true)
  @endpoint = endpoint
  @urls = []
  @format = format || positional_format
end

def raw(url, query = {})

Deprecated:
  • *Note*: This method will be made private in the future.
def raw(url, query = {})
  uri = build(url, query)
  http_get(uri, query)
rescue OEmbed::UnknownFormat
  # raise with format to be backward compatible
  raise OEmbed::UnknownFormat, format
end

def required_query_params_set?(reset_cache: false)

Returns true if all of this provider's required_query_params have a value 
def required_query_params_set?(reset_cache: false)
  return @all_required_query_params_set unless reset_cache || @all_required_query_params_set.nil?
  @all_required_query_params_set = !@required_query_params.values.include?(nil)
end

def set_required_query_params(param, val)

during instantiation.
Raises an ArgumentError if the given param is not listed with required_query_params
with requests to this provider's endpoint.
store that value internally, so that it can be sent along
Given the name of a required_query_param and a value 
def set_required_query_params(param, val)
  raise ArgumentError.new("This provider does NOT have a required_query_param named #{param.inspect}") unless @required_query_params.has_key?(param)
  @required_query_params[param] = val.nil? ? nil : ::CGI.escape(val.to_s)
  required_query_params_set?(reset_cache: true)
  @required_query_params[param]
end