url-static 0.1.4

Simple macro for compile-time URL validation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

# 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](https://www.rust-lang.org/tools/install) like so:

```sh
cargo add url url-static
```

## Examples

```rust
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`](https://doc.rust-lang.org/std/sync/struct.LazyLock.html):
```rust
use std::sync::LazyLock;
use url::Url;
use url_static::url;

static API: LazyLock<Url> = LazyLock::new(|| url!("https://api.example.com"));
```
<!-- TODO: Can we make this easier with another macro? -->

This is a technical restriction of the [`url`](https://crates.io/crates/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:
- [`env!`](https://doc.rust-lang.org/std/macro.env.html)
- [`concat!`](https://doc.rust-lang.org/std/macro.concat.html)

This restriction is more relaxed in `+nightly` builds. When using the `unstable` crate feature, we use [`TokenStream::expand_expr`](https://doc.rust-lang.org/stable/proc_macro/struct.TokenStream.html#method.expand_expr) to have the compiler expand macros for us.

## License

Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/license/MIT>)

## Contributions

Issues and pull requests are welcome at [git.average.name](https://git.average.name/AverageHelper/url-static-rust). You may create an account there to contribute, or use an existing [Codeberg](https://codeberg.org/) or [GitHub](https://github.com/) 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.