csscolorparser/lib.rs
1//! # Overview
2//!
3//! Rust library for parsing CSS color string as defined in the W3C's [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/).
4//!
5//! ## Supported Color Format
6//!
7//! * [Named colors](https://www.w3.org/TR/css-color-4/#named-colors)
8//! * RGB hexadecimal (with and without `#` prefix)
9//! + Short format `#rgb`
10//! + Short format with alpha `#rgba`
11//! + Long format `#rrggbb`
12//! + Long format with alpha `#rrggbbaa`
13//! * `rgb()` and `rgba()`
14//! * `hsl()` and `hsla()`
15//! * `hwb()`
16//! * `lab()`
17//! * `lch()`
18//! * `hwba()`, `hsv()`, `hsva()` - not in CSS standard.
19//!
20//! ### Example Color Format
21//!
22//! <details>
23//! <summary>Click to expand!</summary>
24//!
25//! ```text
26//! transparent
27//! gold
28//! rebeccapurple
29//! lime
30//! #0f0
31//! #0f0f
32//! #00ff00
33//! #00ff00ff
34//! rgb(0,255,0)
35//! rgb(0% 100% 0%)
36//! rgb(0 255 0 / 100%)
37//! rgba(0,255,0,1)
38//! hsl(120,100%,50%)
39//! hsl(120deg 100% 50%)
40//! hsl(-240 100% 50%)
41//! hsl(-240deg 100% 50%)
42//! hsl(0.3333turn 100% 50%)
43//! hsl(133.333grad 100% 50%)
44//! hsl(2.0944rad 100% 50%)
45//! hsla(120,100%,50%,100%)
46//! hwb(120 0% 0%)
47//! hwb(480deg 0% 0% / 100%)
48//! hsv(120,100%,100%)
49//! hsv(120deg 100% 100% / 100%)
50//! ```
51//! </details>
52//!
53//! ## Usage
54//!
55//! Add this to your `Cargo.toml`
56//!
57//! ```toml
58//! csscolorparser = "0.7.0"
59//! ```
60//!
61//! ## Examples
62//!
63//! Using [`csscolorparser::parse()`](fn.parse.html) function.
64//!
65//! ```rust
66//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
67//! let c = csscolorparser::parse("rgb(100%,0%,0%)")?;
68//!
69//! assert_eq!(c.to_array(), [1.0, 0.0, 0.0, 1.0]);
70//! assert_eq!(c.to_rgba8(), [255, 0, 0, 255]);
71//! assert_eq!(c.to_hex_string(), "#ff0000");
72//! assert_eq!(c.to_rgb_string(), "rgb(255,0,0)");
73//! # Ok(())
74//! # }
75//! ```
76//!
77//! Using `parse()` method on `&str`.
78//!
79//! ```rust
80//! use csscolorparser::Color;
81//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
82//!
83//! let c = "#ff00007f".parse::<Color>()?;
84//!
85//! assert_eq!(c.to_rgba8(), [255, 0, 0, 127]);
86//! assert_eq!(c.to_hex_string(), "#ff00007f");
87//! # Ok(())
88//! # }
89//! ```
90//!
91//! ## Default Feature
92//!
93//! * `named-colors`: Enables parsing from [named colors](https://www.w3.org/TR/css-color-4/#named-colors). Requires [`phf`](https://crates.io/crates/phf).
94//!
95//! ## Optional Features
96//!
97//! * `lab`: Enables parsing `lab()` and `lch()` color format.
98//! * `rust-rgb`: Enables converting from [`rgb`](https://crates.io/crates/rgb) crate types into `Color`.
99//! * `cint`: Enables converting [`cint`](https://crates.io/crates/cint) crate types to and from `Color`.
100//! * `serde`: Enables serializing (into HEX string) and deserializing (from any supported string color format) using [`serde`](https://serde.rs/) framework.
101
102#![forbid(unsafe_code)]
103#![warn(missing_docs)]
104
105mod color;
106pub use color::Color;
107
108mod parser;
109pub use parser::{parse, ParseColorError};
110
111#[cfg(feature = "named-colors")]
112mod named_colors;
113#[cfg(feature = "named-colors")]
114pub use named_colors::NAMED_COLORS;
115
116#[cfg(feature = "cint")]
117mod cint;
118
119mod utils;