= 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 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].

== 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].