url-static 0.1.4

Simple macro for compile-time URL validation
Documentation

url-static

A simple macro for compile-time URL validation.

Features

  • Validate literal URL strings at compile time
  • Usable in static contexts (with caveats, see below)
  • Basic support for values from certain other macros that resolve to string literals (env! and concat! so far, see below)
  • 100% safe (as in #![forbid(unsafe_code)])

Installation

To use the macro, install both the url-static and url crates as dependencies. You can do this using cargo like so:

cargo add url url-static

Examples

use url_static::url;

let api = url!("https://api.example.com/");
let crate_repository = url!(env!("CARGO_PKG_REPOSITORY"));

Use with static

To use this macro in static contexts, wrap the value with std::sync::LazyLock:

use std::sync::LazyLock;
use url::Url;
use url_static::url;

static API: LazyLock<Url> = LazyLock::new(|| url!("https://api.example.com"));

This is a technical restriction of the url crate. The only public constructors for url::Url aren't available in const contexts. As a result, this macro can only ensure that a value won't cause the URL parser to panic at runtime 🤷‍♀️Actually creating the URL must happen in a non-const context.

Macros

Due to technical limitations of proc-macros in Rust, url! can only resolve certain specific macro expressions. So far, these include:

This restriction is more relaxed in +nightly builds. When using the unstable crate feature, we use TokenStream::expand_expr to have the compiler expand macros for us.

License

Licensed under either of

Contributions

Issues and pull requests are welcome at git.average.name. You may create an account there to contribute, or use an existing Codeberg or GitHub account.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.