rustedbones / capturl   0.3.0

Apache License 2.0 GitHub

Scala/Java library for Internationalized Resource Identifier (IRIs) support

Scala versions: 2.13 2.12 2.11


Continuous Integration Maven Central Software License

Capturl is a Scala/Java library that provide parsers and models to work with Internationalized Resource Identifier aka IRIs.

The implementation is strongly inspired by the great akka-http Uri model with modularity and simplicity in mind.


Add to your build.sbt:

libraryDependencies += "fr.davit" %% "capturl" % "<version>"


All the apply/create methods accepting String input will be validated against RFC 3987 compliant parsers to create the model classes.

Warning: Exception is made for spaces in path, query and fragment which are allowed at the moment (see TODOs)

If you are sure about your input, and want to skip validation for efficiency reason, you can construct the models using the implementation classes. eg:

Scheme("b@d_scheme") // throws a parsing exception
Scheme.Protocol("b@d_scheme") // this is very wrong but will create your scheme


Those are the IRI normalization steps:

  • Scheme
    • lower case normalization
  • Hosts
    • NamedHost are lower cased and decoded (punycode)
    • IPv4 and IPv6 are normalized
  • Path
    • collapse current folder
    • collapse parent folder
  • Query
    • spaces are replaced by '+'
  • Iri
    • omit custom port if matches the scheme default port
    • root path is added for absolute / host relative iris
    • default port is hidden
  • General
    • all encoded characters are decoded

IRI string interpolation

Add to your build.sbt:

libraryDependencies += "fr.davit" %% "capturl-contextual" % <version>

This sub module provides compile time string interpolation to create IRIs:

val iri = iri"http://localhost:8080/path?key#identifier"

If iri string is not valid, the scala compiler will notify you:

val iri = iri"http://user{[email protected]/"
[error] Invalid IRI http://user{[email protected]/
[error]     iri"http://user{[email protected]/"
[error]         ^
[error] one error found


  • provide strict / relax parser mode
  • provide more normalization options
  • support holes in interpolation


Add to your build.sbt:

libraryDependencies += "fr.davit" %% "capturl-akka-http" % <version>

This sub module provides all the necessary implicits in UriConverters to go from an Iri to the akka Uri model.


  • provide converters for akka-http javadsl model