1Linkify
2=======
3
4Linkify is a Rust library to find links such as URLs and email addresses in
5plain text. It's smart about where a link ends, such as with trailing
6punctuation.
7
8[![Documentation](https://docs.rs/linkify/badge.svg)](https://docs.rs/linkify)
9[![Crate](https://img.shields.io/crates/v/linkify.svg)](https://crates.io/crates/linkify)
10[![ci](https://github.com/robinst/linkify/workflows/ci/badge.svg)](https://github.com/robinst/linkify/actions?query=workflow%3Aci)
11[![codecov](https://codecov.io/gh/robinst/linkify/branch/main/graph/badge.svg)](https://codecov.io/gh/robinst/linkify)
12
13## Introduction
14
15Your reaction might be: "Do I need a library for this? Why not a regex?".
16Let's look at a few cases:
17
18* In `http://example.com/.` the link should not include the trailing dot
19* `http://example.com/,` should not include the trailing comma
20* `(http://example.com/)` should not include the parens
21
22Seems simple enough. But then we also have these cases:
23
24* `https://en.wikipedia.org/wiki/Link_(The_Legend_of_Zelda)` should include the trailing paren
25* `http://üñîçøðé.com/ä` should also work for Unicode (including Emoji and Punycode)
26* `<http://example.com/>` should not include angle brackets
27
28This library behaves as you'd expect in the above cases and many more.
29It uses a simple scan with linear runtime.
30
31In addition to URLs, it can also find email addresses.
32
33## Demo ��‍��
34
35Try it out on the demo playground (Rust compiled to WebAssembly):
36https://robinst.github.io/linkify/
37
38## Usage
39
40Basic usage:
41
42```rust
43extern crate linkify;
44
45use linkify::{LinkFinder, LinkKind};
46
47let input = "Have you seen http://example.com?";
48let finder = LinkFinder::new();
49let links: Vec<_> = finder.links(input).collect();
50
51assert_eq!(1, links.len());
52let link = &links[0];
53
54assert_eq!("http://example.com", link.as_str());
55assert_eq!(14, link.start());
56assert_eq!(32, link.end());
57assert_eq!(&LinkKind::Url, link.kind());
58```
59
60Restrict the kinds of links:
61
62```rust
63use linkify::{LinkFinder, LinkKind};
64
65let input = "http://example.com and foo@example.com";
66let mut finder = LinkFinder::new();
67finder.kinds(&[LinkKind::Email]);
68let links: Vec<_> = finder.links(input).collect();
69
70assert_eq!(1, links.len());
71let link = &links[0];
72assert_eq!("foo@example.com", link.as_str());
73assert_eq!(&LinkKind::Email, link.kind());
74```
75
76See full documentation on [docs.rs](https://docs.rs/linkify).
77
78## Conformance
79
80This crates makes an effort to respect the various standards, namely:
81
82* [RFC 3986] and [RFC 3987] for URLs
83* [RFC 5321] and [RFC 6531] for email addresses (except IP addresses and quoting)
84
85At the same time, it does not guarantee that the returned links are valid.
86If in doubt, it rather returns a link than skipping it.
87
88If you need to validate URLs, e.g. for checking TLDs, use another library on
89the returned links.
90
91## Contributing
92
93Pull requests, issues and comments welcome! Make sure to add tests for
94new features and bug fixes.
95
96## License
97
98Linkify is distributed under the terms of both the MIT license and the
99Apache License (Version 2.0). See [LICENSE-APACHE](LICENSE-APACHE) and
100[LICENSE-MIT](LICENSE-MIT) for details. Opening a pull requests is
101assumed to signal agreement with these licensing terms.
102
103[RFC 3986]: https://tools.ietf.org/search/rfc3986
104[RFC 3987]: https://tools.ietf.org/search/rfc3987
105[RFC 5321]: https://tools.ietf.org/search/rfc5321
106[RFC 6531]: https://tools.ietf.org/search/rfc6531
107