# class URI::GID

### Constants

COMPONENT
PATH_REGEXP

  Extracts #model_name and #model_id from the URI path.

### Attributes

model_id[R]
model_name[R]
params[R]

### Public Class Methods

build(args) click to toggle source

Create a new URI::GID from components with argument check.

The allowed components are app, #model_name, #model_id and params, which can be either a hash or an array.

Using a hash:

    URI::GID.build(app: 'bcx', model_name: 'Person', model_id: '1', params: { key: 'value' })

Using an array, the arguments must be in order [app, #model_name, #model_id, params]:

    URI::GID.build(['bcx', 'Person', '1', key: 'value'])

Calls superclass method

    # File lib/global_id/uri/gid.rb, line 83
    def build(args)
      parts = Util.make_components_hash(self, args)
      parts[:host] = parts[:app]
      parts[:path] = "/#{parts[:model_name]}/#{CGI.escape(parts[:model_id].to_s)}"

      if parts[:params] && !parts[:params].empty?
        parts[:query] = URI.encode_www_form(parts[:params])
      end

      super parts
    end

create(app, model, params = nil) click to toggle source

Shorthand to build a URI::GID from an app, a model and optional params.

    URI::GID.create('bcx', Person.find(5), database: 'superhumans')

    # File lib/global_id/uri/gid.rb, line 67
    def create(app, model, params = nil)
      build app: app, model_name: model.class.name, model_id: model.id, params: params
    end

parse(uri) click to toggle source

Create a new URI::GID by parsing a gid string with argument check.

    URI::GID.parse 'gid://bcx/Person/1?key=value'

This differs from URI() and URI.parse which do not check arguments.

    URI('gid://bcx')             # => URI::GID instance
    URI.parse('gid://bcx')       # => URI::GID instance
    URI::GID.parse('gid://bcx/') # => raises URI::InvalidComponentError

    # File lib/global_id/uri/gid.rb, line 59
    def parse(uri)
      generic_components = URI.split(uri) << nil << true # nil parser, true arg_check
      new(*generic_components)
    end

validate_app(app) click to toggle source

Validates `app`'s as URI hostnames containing only alphanumeric characters and hyphens. An ArgumentError is raised if `app` is invalid.

    URI::GID.validate_app('bcx')     # => 'bcx'
    URI::GID.validate_app('foo-bar') # => 'foo-bar'

    URI::GID.validate_app(nil)       # => ArgumentError
    URI::GID.validate_app('foo/bar') # => ArgumentError

    # File lib/global_id/uri/gid.rb, line 43
    def validate_app(app)
      parse("gid://#{app}/Model/1").app
    rescue URI::Error
      raise ArgumentError, 'Invalid app name. ' \
        'App names must be valid URI hostnames: alphanumeric and hyphen characters only.'
    end

### Public Instance Methods

to_s() click to toggle source

    # File lib/global_id/uri/gid.rb, line 96
    def to_s
      # Implement #to_s to avoid no implicit conversion of nil into string when path is nil
      "gid://#{app}#{path}#{'?' + query if query}"
    end

### Protected Instance Methods

query=(query) click to toggle source

Ruby 2.2 uses query= instead of set_query

Calls superclass method

    # File lib/global_id/uri/gid.rb, line 108
    def query=(query)
      set_params parse_query_params(query)
      super
    end

set_params(params) click to toggle source

    # File lib/global_id/uri/gid.rb, line 119
    def set_params(params)
      @params = params
    end

set_path(path) click to toggle source
Calls superclass method

    # File lib/global_id/uri/gid.rb, line 102
    def set_path(path)
      set_model_components(path) unless defined?(@model_name) && @model_id
      super
    end

set_query(query) click to toggle source

Ruby 2.1 or less uses set_query to assign the query

Calls superclass method

    # File lib/global_id/uri/gid.rb, line 114
    def set_query(query)
      set_params parse_query_params(query)
      super
    end

### Private Instance Methods

check_host(host) click to toggle source
Calls superclass method

    # File lib/global_id/uri/gid.rb, line 129
    def check_host(host)
      validate_component(host)
      super
    end

check_path(path) click to toggle source

    # File lib/global_id/uri/gid.rb, line 134
    def check_path(path)
      validate_component(path)
      set_model_components(path, true)
    end

check_scheme(scheme) click to toggle source
Calls superclass method

    # File lib/global_id/uri/gid.rb, line 139
    def check_scheme(scheme)
      if scheme == 'gid'
        super
      else
        raise URI::BadURIError, "Not a gid:// URI scheme: #{inspect}"
      end
    end

parse_query_params(query) click to toggle source

    # File lib/global_id/uri/gid.rb, line 171
    def parse_query_params(query)
      Hash[URI.decode_www_form(query)].with_indifferent_access if query
    end

set_model_components(path, validate = false) click to toggle source

    # File lib/global_id/uri/gid.rb, line 147
    def set_model_components(path, validate = false)
      _, model_name, model_id = path.match(PATH_REGEXP).to_a
      model_id = CGI.unescape(model_id) if model_id

      validate_component(model_name) && validate_model_id(model_id, model_name) if validate

      @model_name = model_name
      @model_id = model_id
    end

validate_component(component) click to toggle source

    # File lib/global_id/uri/gid.rb, line 157
    def validate_component(component)
      return component unless component.blank?

      raise URI::InvalidComponentError,
        "Expected a URI like gid://app/Person/1234: #{inspect}"
    end

validate_model_id(model_id, model_name) click to toggle source

    # File lib/global_id/uri/gid.rb, line 164
    def validate_model_id(model_id, model_name)
      return model_id unless model_id.blank?

      raise MissingModelIdError, "Unable to create a Global ID for " \
        "#{model_name} without a model id."
    end