@@ -89,24 +89,36 @@ pub use serializer::{ToCss, CssStringWriter, serialize_identifier, serialize_str
8989pub use parser:: { Parser , Delimiter , Delimiters , SourcePosition } ;
9090pub use unicode_range:: UnicodeRange ;
9191
92-
93- /**
94-
95- This macro is equivalent to a `match` expression on an `&str` value,
96- but matching is case-insensitive in the ASCII range.
97-
98- Usage example:
99-
100- ```{rust,ignore}
101- match_ignore_ascii_case! { string,
102- "foo" => Some(Foo),
103- "bar" => Some(Bar),
104- "baz" => Some(Baz),
105- _ => None
106- }
107- ```
108-
109- */
92+ /// Expands to an expression equivalent to a `match` with string patterns,
93+ /// but matching is case-insensitive in the ASCII range.
94+ ///
95+ /// Requirements:
96+ ///
97+ /// * The `cssparser_macros` crate must also be imported at the crate root
98+ /// * The patterns must not contain ASCII upper case letters. (They must be already be lower-cased.)
99+ ///
100+ /// # Example
101+ ///
102+ /// ```rust
103+ /// #[macro_use] extern crate cssparser;
104+ /// #[macro_use] extern crate cssparser_macros;
105+ ///
106+ /// # fn main() {} // Make doctest not wrap everythig in its own main
107+ /// # fn dummy(function_name: &String) { let _ =
108+ /// match_ignore_ascii_case! { &function_name,
109+ /// "rgb" => parse_rgb(..),
110+ /// "rgba" => parse_rgba(..),
111+ /// "hsl" => parse_hsl(..),
112+ /// "hsla" => parse_hsla(..),
113+ /// _ => Err("unknown function")
114+ /// }
115+ /// # ;}
116+ /// # use std::ops::RangeFull;
117+ /// # fn parse_rgb(_: RangeFull) -> Result<(), &'static str> { Err("") }
118+ /// # fn parse_rgba(_: RangeFull) -> Result<(), &'static str> { Err("") }
119+ /// # fn parse_hsl(_: RangeFull) -> Result<(), &'static str> { Err("") }
120+ /// # fn parse_hsla(_: RangeFull) -> Result<(), &'static str> { Err("") }
121+ /// ```
110122#[ macro_export]
111123macro_rules! match_ignore_ascii_case {
112124 // parse the last case plus the fallback
@@ -138,6 +150,38 @@ macro_rules! match_ignore_ascii_case {
138150 } ;
139151}
140152
153+ /// Define a placeholder type `$Name`
154+ /// with a method `fn get(input: &str) -> Option<&'static $ValueType>`.
155+ ///
156+ /// This method uses finds a match for the input string
157+ /// in a [`phf` map](https://github.com/sfackler/rust-phf).
158+ /// Matching is case-insensitive in the ASCII range.
159+ ///
160+ /// Requirements:
161+ ///
162+ /// * The `phf` and `cssparser_macros` crates must also be imported at the crate root
163+ /// * The keys must not contain ASCII upper case letters. (They must be already be lower-cased.)
164+ /// * The values must be given a strings that contain Rust syntax for a constant expression.
165+ ///
166+ /// ## Example:
167+ ///
168+ /// ```rust
169+ /// extern crate phf;
170+ /// #[macro_use] extern crate cssparser;
171+ /// #[macro_use] extern crate cssparser_macros;
172+ ///
173+ /// # fn main() {} // Make doctest not wrap everythig in its own main
174+ ///
175+ /// fn color_rgb(input: &str) -> Option<(u8, u8, u8)> {
176+ /// ascii_case_insensitive_phf_map! {
177+ /// KEYWORDS: Map<(u8, u8, u8)> = {
178+ /// "red" => "(255, 0, 0)",
179+ /// "green" => "(0, 255, 0)",
180+ /// "blue" => "(0, 0, 255)",
181+ /// }
182+ /// }
183+ /// KEYWORDS::get(input).cloned()
184+ /// }
141185#[ macro_export]
142186macro_rules! ascii_case_insensitive_phf_map {
143187 ( $Name: ident : Map <$ValueType: ty> = {
@@ -162,7 +206,14 @@ macro_rules! ascii_case_insensitive_phf_map {
162206 }
163207}
164208
209+ /// Implementation detail of match_ignore_ascii_case! and ascii_case_insensitive_phf_map! macros.
210+ ///
211+ /// * Check at compile-time that none of the `$string`s contain ASCII uppercase letters
212+ /// * Define a local variable named `$output`
213+ /// to the result of calling `_match_ignore_ascii_case__to_lowercase`
214+ /// with a stack-allocated buffer as long as the longest `$string`.
165215#[ macro_export]
216+ #[ doc( hidden) ]
166217macro_rules! _cssparser_internal__max_len {
167218 ( $input: expr => $output: ident, $( $string: expr) ,+) => {
168219 #[ derive( cssparser__match_ignore_ascii_case__max_len) ]
@@ -183,7 +234,10 @@ macro_rules! _cssparser_internal__max_len {
183234}
184235
185236
186- /// Implementation detail of macros.
237+ /// Implementation detail of match_ignore_ascii_case! and ascii_case_insensitive_phf_map! macros.
238+ ///
239+ /// Return `input`, lower-cased, unless larger than `buffer`
240+ /// which is used temporary space for lower-casing a copy of `input` if necessary.
187241#[ doc( hidden) ]
188242#[ allow( non_snake_case) ]
189243pub fn _match_ignore_ascii_case__to_lowercase < ' a > ( buffer : & ' a mut [ u8 ] , input : & ' a str ) -> Option < & ' a str > {
0 commit comments