Skip to main content

rspack_lightningcss/values/
syntax.rs

1//! CSS syntax strings
2
3use super::ident::Ident;
4use super::number::{CSSInteger, CSSNumber};
5use crate::error::{ParserError, PrinterError};
6use crate::properties::custom::TokenList;
7use crate::stylesheet::ParserOptions;
8use crate::traits::{Parse, ToCss};
9use crate::values;
10#[cfg(feature = "visitor")]
11use crate::visitor::Visit;
12use cssparser::*;
13
14/// A CSS [syntax string](https://drafts.css-houdini.org/css-properties-values-api/#syntax-strings)
15/// used to define the grammar for a registered custom property.
16#[derive(Debug, PartialEq, Clone)]
17#[cfg_attr(
18  feature = "serde",
19  derive(serde::Serialize, serde::Deserialize),
20  serde(tag = "type", content = "value", rename_all = "kebab-case")
21)]
22#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
23#[cfg_attr(feature = "into_owned", derive(rspack_lightningcss_static_self::IntoOwned))]
24pub enum SyntaxString {
25  /// A list of syntax components.
26  Components(Vec<SyntaxComponent>),
27  /// The universal syntax definition.
28  Universal,
29}
30
31/// A [syntax component](https://drafts.css-houdini.org/css-properties-values-api/#syntax-component)
32/// within a [SyntaxString](SyntaxString).
33///
34/// A syntax component consists of a component kind an a multiplier, which indicates how the component
35/// may repeat during parsing.
36#[derive(Debug, PartialEq, Clone)]
37#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
38#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
39#[cfg_attr(feature = "into_owned", derive(rspack_lightningcss_static_self::IntoOwned))]
40pub struct SyntaxComponent {
41  /// The kind of component.
42  pub kind: SyntaxComponentKind,
43  /// A multiplier for the component.
44  pub multiplier: Multiplier,
45}
46
47/// A [syntax component component name](https://drafts.css-houdini.org/css-properties-values-api/#supported-names).
48#[derive(Debug, PartialEq, Clone)]
49#[cfg_attr(
50  feature = "serde",
51  derive(serde::Serialize, serde::Deserialize),
52  serde(tag = "type", content = "value", rename_all = "kebab-case")
53)]
54#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
55#[cfg_attr(feature = "into_owned", derive(rspack_lightningcss_static_self::IntoOwned))]
56pub enum SyntaxComponentKind {
57  /// A `<length>` component.
58  Length,
59  /// A `<number>` component.
60  Number,
61  /// A `<percentage>` component.
62  Percentage,
63  /// A `<length-percentage>` component.
64  LengthPercentage,
65  /// A `<string>` component.
66  String,
67  /// A `<color>` component.
68  Color,
69  /// An `<image>` component.
70  Image,
71  /// A `<url>` component.
72  Url,
73  /// An `<integer>` component.
74  Integer,
75  /// An `<angle>` component.
76  Angle,
77  /// A `<time>` component.
78  Time,
79  /// A `<resolution>` component.
80  Resolution,
81  /// A `<transform-function>` component.
82  TransformFunction,
83  /// A `<transform-list>` component.
84  TransformList,
85  /// A `<custom-ident>` component.
86  CustomIdent,
87  /// A literal component.
88  Literal(String), // TODO: borrow??
89}
90
91/// A [multiplier](https://drafts.css-houdini.org/css-properties-values-api/#multipliers) for a
92/// [SyntaxComponent](SyntaxComponent). Indicates whether and how the component may be repeated.
93#[derive(Debug, PartialEq, Clone)]
94#[cfg_attr(feature = "visitor", derive(Visit))]
95#[cfg_attr(
96  feature = "serde",
97  derive(serde::Serialize, serde::Deserialize),
98  serde(tag = "type", content = "value", rename_all = "kebab-case")
99)]
100#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
101#[cfg_attr(feature = "into_owned", derive(rspack_lightningcss_static_self::IntoOwned))]
102pub enum Multiplier {
103  /// The component may not be repeated.
104  None,
105  /// The component may repeat one or more times, separated by spaces.
106  Space,
107  /// The component may repeat one or more times, separated by commas.
108  Comma,
109}
110
111/// A parsed value for a [SyntaxComponent](SyntaxComponent).
112#[derive(Debug, PartialEq, Clone)]
113#[cfg_attr(feature = "visitor", derive(Visit))]
114#[cfg_attr(feature = "into_owned", derive(rspack_lightningcss_static_self::IntoOwned))]
115#[cfg_attr(
116  feature = "serde",
117  derive(serde::Serialize, serde::Deserialize),
118  serde(tag = "type", content = "value", rename_all = "kebab-case")
119)]
120#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
121pub enum ParsedComponent<'i> {
122  /// A `<length>` value.
123  Length(values::length::Length),
124  /// A `<number>` value.
125  Number(CSSNumber),
126  /// A `<percentage>` value.
127  Percentage(values::percentage::Percentage),
128  /// A `<length-percentage>` value.
129  LengthPercentage(values::length::LengthPercentage),
130  /// A `<string>` value.
131  String(values::string::CSSString<'i>),
132  /// A `<color>` value.
133  Color(values::color::CssColor),
134  /// An `<image>` value.
135  #[cfg_attr(feature = "serde", serde(borrow))]
136  Image(values::image::Image<'i>),
137  /// A `<url>` value.
138  Url(values::url::Url<'i>),
139  /// An `<integer>` value.
140  Integer(CSSInteger),
141  /// An `<angle>` value.
142  Angle(values::angle::Angle),
143  /// A `<time>` value.
144  Time(values::time::Time),
145  /// A `<resolution>` value.
146  Resolution(values::resolution::Resolution),
147  /// A `<transform-function>` value.
148  TransformFunction(crate::properties::transform::Transform),
149  /// A `<transform-list>` value.
150  TransformList(crate::properties::transform::TransformList),
151  /// A `<custom-ident>` value.
152  CustomIdent(values::ident::CustomIdent<'i>),
153  /// A literal value.
154  Literal(Ident<'i>),
155  /// A repeated component value.
156  Repeated {
157    /// The components to repeat.
158    #[cfg_attr(feature = "visitor", skip_type)]
159    components: Vec<ParsedComponent<'i>>,
160    /// A multiplier describing how the components repeat.
161    multiplier: Multiplier,
162  },
163  /// A raw token stream.
164  TokenList(crate::properties::custom::TokenList<'i>),
165}
166
167impl<'i> SyntaxString {
168  /// Parses a syntax string.
169  pub fn parse_string(input: &'i str) -> Result<SyntaxString, ()> {
170    // https://drafts.css-houdini.org/css-properties-values-api/#parsing-syntax
171    let mut input = input.trim_matches(SPACE_CHARACTERS);
172    if input.is_empty() {
173      return Err(());
174    }
175
176    if input == "*" {
177      return Ok(SyntaxString::Universal);
178    }
179
180    let mut components = Vec::new();
181    loop {
182      let component = SyntaxComponent::parse_string(&mut input)?;
183      components.push(component);
184
185      input = input.trim_start_matches(SPACE_CHARACTERS);
186      if input.is_empty() {
187        break;
188      }
189
190      if input.starts_with('|') {
191        input = &input[1..];
192        continue;
193      }
194
195      return Err(());
196    }
197
198    Ok(SyntaxString::Components(components))
199  }
200
201  /// Parses a value according to the syntax grammar.
202  pub fn parse_value<'t>(
203    &self,
204    input: &mut Parser<'i, 't>,
205  ) -> Result<ParsedComponent<'i>, ParseError<'i, ParserError<'i>>> {
206    match self {
207      SyntaxString::Universal => Ok(ParsedComponent::TokenList(TokenList::parse(
208        input,
209        &ParserOptions::default(),
210        0,
211      )?)),
212      SyntaxString::Components(components) => {
213        // Loop through each component, and return the first one that parses successfully.
214        for component in components {
215          let state = input.state();
216          let mut parsed = Vec::new();
217          loop {
218            let value: Result<ParsedComponent<'i>, ParseError<'i, ParserError<'i>>> = input.try_parse(|input| {
219              Ok(match &component.kind {
220                SyntaxComponentKind::Length => ParsedComponent::Length(values::length::Length::parse(input)?),
221                SyntaxComponentKind::Number => ParsedComponent::Number(CSSNumber::parse(input)?),
222                SyntaxComponentKind::Percentage => {
223                  ParsedComponent::Percentage(values::percentage::Percentage::parse(input)?)
224                }
225                SyntaxComponentKind::LengthPercentage => {
226                  ParsedComponent::LengthPercentage(values::length::LengthPercentage::parse(input)?)
227                }
228                SyntaxComponentKind::String => ParsedComponent::String(values::string::CSSString::parse(input)?),
229                SyntaxComponentKind::Color => ParsedComponent::Color(values::color::CssColor::parse(input)?),
230                SyntaxComponentKind::Image => ParsedComponent::Image(values::image::Image::parse(input)?),
231                SyntaxComponentKind::Url => ParsedComponent::Url(values::url::Url::parse(input)?),
232                SyntaxComponentKind::Integer => ParsedComponent::Integer(CSSInteger::parse(input)?),
233                SyntaxComponentKind::Angle => ParsedComponent::Angle(values::angle::Angle::parse(input)?),
234                SyntaxComponentKind::Time => ParsedComponent::Time(values::time::Time::parse(input)?),
235                SyntaxComponentKind::Resolution => {
236                  ParsedComponent::Resolution(values::resolution::Resolution::parse(input)?)
237                }
238                SyntaxComponentKind::TransformFunction => {
239                  ParsedComponent::TransformFunction(crate::properties::transform::Transform::parse(input)?)
240                }
241                SyntaxComponentKind::TransformList => {
242                  ParsedComponent::TransformList(crate::properties::transform::TransformList::parse(input)?)
243                }
244                SyntaxComponentKind::CustomIdent => {
245                  ParsedComponent::CustomIdent(values::ident::CustomIdent::parse(input)?)
246                }
247                SyntaxComponentKind::Literal(value) => {
248                  let location = input.current_source_location();
249                  let ident = input.expect_ident()?;
250                  if *ident != &value {
251                    return Err(location.new_unexpected_token_error(Token::Ident(ident.clone())));
252                  }
253                  ParsedComponent::Literal(ident.into())
254                }
255              })
256            });
257
258            if let Ok(value) = value {
259              match component.multiplier {
260                Multiplier::None => return Ok(value),
261                Multiplier::Space => {
262                  parsed.push(value);
263                  if input.is_exhausted() {
264                    return Ok(ParsedComponent::Repeated {
265                      components: parsed,
266                      multiplier: component.multiplier.clone(),
267                    });
268                  }
269                }
270                Multiplier::Comma => {
271                  parsed.push(value);
272                  match input.next() {
273                    Err(_) => {
274                      return Ok(ParsedComponent::Repeated {
275                        components: parsed,
276                        multiplier: component.multiplier.clone(),
277                      })
278                    }
279                    Ok(&Token::Comma) => continue,
280                    Ok(_) => break,
281                  }
282                }
283              }
284            } else {
285              break;
286            }
287          }
288
289          input.reset(&state);
290        }
291
292        Err(input.new_error_for_next_token())
293      }
294    }
295  }
296
297  /// Parses a value from a string according to the syntax grammar.
298  pub fn parse_value_from_string<'t>(
299    &self,
300    input: &'i str,
301  ) -> Result<ParsedComponent<'i>, ParseError<'i, ParserError<'i>>> {
302    let mut input = ParserInput::new(input);
303    let mut parser = Parser::new(&mut input);
304    self.parse_value(&mut parser)
305  }
306}
307
308impl SyntaxComponent {
309  fn parse_string(input: &mut &str) -> Result<SyntaxComponent, ()> {
310    let kind = SyntaxComponentKind::parse_string(input)?;
311
312    // Pre-multiplied types cannot have multipliers.
313    if kind == SyntaxComponentKind::TransformList {
314      return Ok(SyntaxComponent {
315        kind,
316        multiplier: Multiplier::None,
317      });
318    }
319
320    let multiplier = if input.starts_with('+') {
321      *input = &input[1..];
322      Multiplier::Space
323    } else if input.starts_with('#') {
324      *input = &input[1..];
325      Multiplier::Comma
326    } else {
327      Multiplier::None
328    };
329
330    Ok(SyntaxComponent { kind, multiplier })
331  }
332}
333
334// https://drafts.csswg.org/css-syntax-3/#whitespace
335static SPACE_CHARACTERS: &'static [char] = &['\u{0020}', '\u{0009}'];
336
337impl SyntaxComponentKind {
338  fn parse_string(input: &mut &str) -> Result<SyntaxComponentKind, ()> {
339    // https://drafts.css-houdini.org/css-properties-values-api/#consume-syntax-component
340    *input = input.trim_start_matches(SPACE_CHARACTERS);
341    if input.starts_with('<') {
342      // https://drafts.css-houdini.org/css-properties-values-api/#consume-data-type-name
343      let end_idx = input.find('>').ok_or(())?;
344      let name = &input[1..end_idx];
345      let component = match_ignore_ascii_case! {name,
346        "length" => SyntaxComponentKind::Length,
347        "number" => SyntaxComponentKind::Number,
348        "percentage" => SyntaxComponentKind::Percentage,
349        "length-percentage" => SyntaxComponentKind::LengthPercentage,
350        "string" => SyntaxComponentKind::String,
351        "color" => SyntaxComponentKind::Color,
352        "image" => SyntaxComponentKind::Image,
353        "url" => SyntaxComponentKind::Url,
354        "integer" => SyntaxComponentKind::Integer,
355        "angle" => SyntaxComponentKind::Angle,
356        "time" => SyntaxComponentKind::Time,
357        "resolution" => SyntaxComponentKind::Resolution,
358        "transform-function" => SyntaxComponentKind::TransformFunction,
359        "transform-list" => SyntaxComponentKind::TransformList,
360        "custom-ident" => SyntaxComponentKind::CustomIdent,
361        _ => return Err(())
362      };
363
364      *input = &input[end_idx + 1..];
365      Ok(component)
366    } else if input.starts_with(is_ident_start) {
367      // A literal.
368      let end_idx = input.find(|c| !is_name_code_point(c)).unwrap_or_else(|| input.len());
369      let name = input[0..end_idx].to_owned();
370      *input = &input[end_idx..];
371      Ok(SyntaxComponentKind::Literal(name))
372    } else {
373      return Err(());
374    }
375  }
376}
377
378#[inline]
379fn is_ident_start(c: char) -> bool {
380  // https://drafts.csswg.org/css-syntax-3/#ident-start-code-point
381  c >= 'A' && c <= 'Z' || c >= 'a' && c <= 'z' || c >= '\u{80}' || c == '_'
382}
383
384#[inline]
385fn is_name_code_point(c: char) -> bool {
386  // https://drafts.csswg.org/css-syntax-3/#ident-code-point
387  is_ident_start(c) || c >= '0' && c <= '9' || c == '-'
388}
389
390impl<'i> Parse<'i> for SyntaxString {
391  fn parse<'t>(input: &mut Parser<'i, 't>) -> Result<Self, ParseError<'i, ParserError<'i>>> {
392    let string = input.expect_string_cloned()?;
393    SyntaxString::parse_string(string.as_ref()).map_err(|_| input.new_custom_error(ParserError::InvalidValue))
394  }
395}
396
397impl ToCss for SyntaxString {
398  fn to_css<PrinterT: crate::printer::PrinterTrait>(&self, dest: &mut PrinterT) -> Result<(), PrinterError> {
399    dest.write_char('"')?;
400    match self {
401      SyntaxString::Universal => dest.write_char('*')?,
402      SyntaxString::Components(components) => {
403        let mut first = true;
404        for component in components {
405          if first {
406            first = false;
407          } else {
408            dest.delim('|', true)?;
409          }
410
411          component.to_css(dest)?;
412        }
413      }
414    }
415
416    dest.write_char('"')?;
417
418    Ok(())
419  }
420}
421
422impl ToCss for SyntaxComponent {
423  fn to_css<PrinterT: crate::printer::PrinterTrait>(&self, dest: &mut PrinterT) -> Result<(), PrinterError> {
424    self.kind.to_css(dest)?;
425    match self.multiplier {
426      Multiplier::None => Ok(()),
427      Multiplier::Comma => {
428        dest.write_char('#')?;
429        Ok(())
430      }
431      Multiplier::Space => {
432        dest.write_char('+')?;
433        Ok(())
434      }
435    }
436  }
437}
438
439impl ToCss for SyntaxComponentKind {
440  fn to_css<PrinterT: crate::printer::PrinterTrait>(&self, dest: &mut PrinterT) -> Result<(), PrinterError> {
441    use SyntaxComponentKind::*;
442    let s = match self {
443      Length => "<length>",
444      Number => "<number>",
445      Percentage => "<percentage>",
446      LengthPercentage => "<length-percentage>",
447      String => "<string>",
448      Color => "<color>",
449      Image => "<image>",
450      Url => "<url>",
451      Integer => "<integer>",
452      Angle => "<angle>",
453      Time => "<time>",
454      Resolution => "<resolution>",
455      TransformFunction => "<transform-function>",
456      TransformList => "<transform-list>",
457      CustomIdent => "<custom-ident>",
458      Literal(l) => l,
459    };
460    dest.write_str(s)?;
461    Ok(())
462  }
463}
464
465impl<'i> ToCss for ParsedComponent<'i> {
466  fn to_css<PrinterT: crate::printer::PrinterTrait>(&self, dest: &mut PrinterT) -> Result<(), PrinterError> {
467    use ParsedComponent::*;
468    match self {
469      Length(v) => v.to_css(dest),
470      Number(v) => v.to_css(dest),
471      Percentage(v) => v.to_css(dest),
472      LengthPercentage(v) => v.to_css(dest),
473      String(v) => v.to_css(dest),
474      Color(v) => v.to_css(dest),
475      Image(v) => v.to_css(dest),
476      Url(v) => v.to_css(dest),
477      Integer(v) => v.to_css(dest),
478      Angle(v) => v.to_css(dest),
479      Time(v) => v.to_css(dest),
480      Resolution(v) => v.to_css(dest),
481      TransformFunction(v) => v.to_css(dest),
482      TransformList(v) => v.to_css(dest),
483      CustomIdent(v) => v.to_css(dest),
484      Literal(v) => v.to_css(dest),
485      Repeated { components, multiplier } => {
486        let mut first = true;
487        for component in components {
488          if first {
489            first = false;
490          } else {
491            match multiplier {
492              Multiplier::Comma => dest.delim(',', false)?,
493              Multiplier::Space => dest.write_char(' ')?,
494              Multiplier::None => unreachable!(),
495            }
496          }
497
498          component.to_css(dest)?;
499        }
500        Ok(())
501      }
502      TokenList(t) => t.to_css(dest, false),
503    }
504  }
505}
506
507#[cfg(test)]
508mod tests {
509  use crate::values::color::RGBA;
510
511  use super::*;
512
513  fn test(source: &str, test: &str, expected: ParsedComponent) {
514    let parsed = SyntaxString::parse_string(source).unwrap();
515
516    let mut input = ParserInput::new(test);
517    let mut parser = Parser::new(&mut input);
518    let value = parsed.parse_value(&mut parser).unwrap();
519    assert_eq!(value, expected);
520  }
521
522  fn parse_error_test(source: &str) {
523    let res = SyntaxString::parse_string(source);
524    match res {
525      Ok(_) => unreachable!(),
526      Err(_) => {}
527    }
528  }
529
530  fn error_test(source: &str, test: &str) {
531    let parsed = SyntaxString::parse_string(source).unwrap();
532    let mut input = ParserInput::new(test);
533    let mut parser = Parser::new(&mut input);
534    let res = parsed.parse_value(&mut parser);
535    match res {
536      Ok(_) => unreachable!(),
537      Err(_) => {}
538    }
539  }
540
541  #[test]
542  fn test_syntax() {
543    test(
544      "foo | <color>+ | <integer>",
545      "foo",
546      ParsedComponent::Literal("foo".into()),
547    );
548
549    test("foo|<color>+|<integer>", "foo", ParsedComponent::Literal("foo".into()));
550
551    test("foo | <color>+ | <integer>", "2", ParsedComponent::Integer(2));
552
553    test(
554      "foo | <color>+ | <integer>",
555      "red",
556      ParsedComponent::Repeated {
557        components: vec![ParsedComponent::Color(values::color::CssColor::RGBA(RGBA {
558          red: 255,
559          green: 0,
560          blue: 0,
561          alpha: 255,
562        }))],
563        multiplier: Multiplier::Space,
564      },
565    );
566
567    test(
568      "foo | <color>+ | <integer>",
569      "red blue",
570      ParsedComponent::Repeated {
571        components: vec![
572          ParsedComponent::Color(values::color::CssColor::RGBA(RGBA {
573            red: 255,
574            green: 0,
575            blue: 0,
576            alpha: 255,
577          })),
578          ParsedComponent::Color(values::color::CssColor::RGBA(RGBA {
579            red: 0,
580            green: 0,
581            blue: 255,
582            alpha: 255,
583          })),
584        ],
585        multiplier: Multiplier::Space,
586      },
587    );
588
589    error_test("foo | <color>+ | <integer>", "2.5");
590
591    error_test("foo | <color>+ | <integer>", "25px");
592
593    error_test("foo | <color>+ | <integer>", "red, green");
594
595    test(
596      "foo | <color># | <integer>",
597      "red, blue",
598      ParsedComponent::Repeated {
599        components: vec![
600          ParsedComponent::Color(values::color::CssColor::RGBA(RGBA {
601            red: 255,
602            green: 0,
603            blue: 0,
604            alpha: 255,
605          })),
606          ParsedComponent::Color(values::color::CssColor::RGBA(RGBA {
607            red: 0,
608            green: 0,
609            blue: 255,
610            alpha: 255,
611          })),
612        ],
613        multiplier: Multiplier::Comma,
614      },
615    );
616
617    error_test("foo | <color># | <integer>", "red green");
618
619    test(
620      "<length>",
621      "25px",
622      ParsedComponent::Length(values::length::Length::Value(values::length::LengthValue::Px(25.0))),
623    );
624
625    test(
626      "<length>",
627      "calc(25px + 25px)",
628      ParsedComponent::Length(values::length::Length::Value(values::length::LengthValue::Px(50.0))),
629    );
630
631    test(
632      "<length> | <percentage>",
633      "25px",
634      ParsedComponent::Length(values::length::Length::Value(values::length::LengthValue::Px(25.0))),
635    );
636
637    test(
638      "<length> | <percentage>",
639      "25%",
640      ParsedComponent::Percentage(values::percentage::Percentage(0.25)),
641    );
642
643    error_test("<length> | <percentage>", "calc(100% - 25px)");
644
645    test("foo | bar | baz", "bar", ParsedComponent::Literal("bar".into()));
646
647    test(
648      "<string>",
649      "'foo'",
650      ParsedComponent::String(values::string::CSSString("foo".into())),
651    );
652
653    test(
654      "<custom-ident>",
655      "hi",
656      ParsedComponent::CustomIdent(values::ident::CustomIdent("hi".into())),
657    );
658
659    parse_error_test("<transform-list>#");
660    parse_error_test("<color");
661    parse_error_test("color>");
662  }
663}