= UriFormatValidator

image:https://img.shields.io/gem/v/uri_format_validator.svg[ Gem Version, link="https://rubygems.org/gems/uri_format_validator"] image:https://img.shields.io/travis/riboseinc/uri_format_validator/master.svg[ Build Status, link="https://travis-ci.org/riboseinc/uri_format_validator"] image:https://img.shields.io/codeclimate/github/riboseinc/uri_format_validator.svg[ "Code Climate", link="https://codeclimate.com/github/riboseinc/uri_format_validator"] image:https://img.shields.io/codecov/c/github/riboseinc/uri_format_validator.svg[ "Test Coverage", link="https://codecov.io/gh/riboseinc/uri_format_validator"]

== Introduction

This gem provides URI field validator for Rails' Active Model.

UriFormatValidator requires Active Model 4+. It is tested against MRI 2.2.2+, JRuby, and Rubinius in their recent versions.

== Getting started

Add this line to your application's Gemfile:

[source,ruby]

gem 'uri_format_validator'

Then install by executing bundle install. You may now define validations in your models, like that:

[source,ruby]

class User < ActiveRecord::Base validates :home_site_url, uri: true end

For Rails 6, you may need to specify the namespace like that:

[source,ruby]

class User < ActiveRecord::Base validates :home_site_url, 'uri_format_validator/validators/uri': true, end

For your convenience, an old-fashioned validation helper is also provided:

[source,ruby]

class User < ActiveRecord::Base validates_uri_format_of :home_site_url end

== Validation options

=== URI component constraints

You can specify constraints on URI components: scheme, authority, path, query, and fragment.

[source,ruby]

validates :home_site_url, uri: { scheme: /https?/ } validates :home_site_url, uri: { scheme: %w[ssh telnet] }

validates :home_site_url, uri: { authority: /.example./ } validates :home_site_url, uri: { authority: %w[example.com example.test] }

require path component (/ is not enough)

validates :home_site_url, uri: { path: true }

disallow presence of path component

validates :home_site_url, uri: { path: false }

match path against regular expression

validates :home_site_url, uri: { path: /regexp/ }

require query component

validates :home_site_url, uri: { query: true }

disallow presence of query component

validates :home_site_url, uri: { query: false }

require fragment component

validates :home_site_url, uri: { fragment: true }

disallow presence of fragment component

validates :home_site_url, uri: { fragment: false }

When scheme option is unspecified, only http and https are allowed.

=== Relative URIs

By default, only absolute URIs are valid. Specify authority: false option to allow relative and disallow absolute URLs:

[source,ruby]

validates :home_site_url, uri: { authority: false }

=== Reachable URLs

With retrievable options, you can ensure that URL indeed points to some resource. A HTTP HEAD request will be performed to that URL, and it must result with 2xx status code. Otherwise, given value is considered invalid.

[source,ruby]

validates :home_site_url, uri: { retrievable: true }

=== Error messages

You can also override the default error message:

[source,ruby]

validates :my_url_attribute, uri: true, message: 'is not a valid URL'

Alternatively, you can provide your own localization string for errors.messages.invalid_uri key.

== Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to https://rubygems.org[rubygems.org].

Documentation for this gem is hosted at Relish[https://relishapp.com/ribose/uri-format-validator/docs].

To upload documentation, run relish push ribose/uri-format-validator.

== Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/riboseinc/uri_format_validator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the http://contributor-covenant.org[Contributor Covenant] code of conduct.

== License

The gem is available as open source under the terms of the http://opensource.org/licenses/MIT[MIT License].