Module parcel_css::properties

Expand description

CSS property values.

Each property provides parsing and serialization support using the Parse and ToCss traits. Properties are fully parsed as defined by the CSS spec, and printed in their canonical form. For example, most CSS properties are case-insensitive, and may be written in various orders, but when printed they are lower cased as appropriate and in a standard order.

CSS properties often also contain many implicit values that are automatically filled in during parsing when omitted. These are also omitted when possible during serialization. Many properties also implement the Default trait, which returns the initial value for the property.

Shorthand properties are represented as structs containing fields for each of the sub-properties. If some of the sub-properties are not specified in the shorthand, their default values are filled in.

The Property enum contains the values of all properties, and can be used to parse property values by name. The PropertyId enum represents only property names, and not values and is used to refer to known properties.

Example

This example shows how the background shorthand property is parsed and serialized. The parse_string function parses the background into a structure with all missing fields filled in with their default values. When printed using the to_css_string function, the components are in their canonical order, and default values are removed.

use smallvec::smallvec;
use parcel_css::{
  properties::{Property, PropertyId, background::*},
  values::{url::Url, image::Image, color::CssColor, position::*, length::*},
  stylesheet::{ParserOptions, PrinterOptions},
  dependencies::Location,
};

let background = Property::parse_string(
  PropertyId::from("background"),
  "url('img.png') repeat fixed 20px 10px / 50px 100px",
  ParserOptions::default()
).unwrap();

assert_eq!(
  background,
  Property::Background(smallvec![Background {
    image: Image::Url(Url {
      url: "img.png".into(),
      loc: Location { line: 1, column: 1 }
    }),
    color: CssColor::RGBA(cssparser::RGBA {
      red: 0,
      green: 0,
      blue: 0,
      alpha: 0
    }),
    position: BackgroundPosition {
      x: HorizontalPosition::Length(LengthPercentage::px(20.0)),
      y: VerticalPosition::Length(LengthPercentage::px(10.0)),
    },
    repeat: BackgroundRepeat {
      x: BackgroundRepeatKeyword::Repeat,
      y: BackgroundRepeatKeyword::Repeat,
    },
    size: BackgroundSize::Explicit {
      width: LengthPercentageOrAuto::LengthPercentage(LengthPercentage::px(50.0)),
      height: LengthPercentageOrAuto::LengthPercentage(LengthPercentage::px(100.0)),
    },
    attachment: BackgroundAttachment::Fixed,
    origin: BackgroundOrigin::PaddingBox,
    clip: BackgroundClip::BorderBox,
  }])
);

assert_eq!(
  background.to_css_string(false, PrinterOptions::default()).unwrap(),
  r#"background: url("img.png") 20px 10px / 50px 100px fixed"#
);

If you have a cssparser::Parser already, you can also use the parse and to_css methods instead, rather than parsing from a string.

Unparsed and custom properties

Custom and unknown properties are represented by the CustomProperty struct, and the Property::Custom variant. The value of these properties is not parsed, and is stored as a raw TokenList, with the name as a string.

If a known property is unable to be parsed, e.g. it contains var() references, then it is represented by the UnparsedProperty struct, and the Property::Unparsed variant. The value is stored as a raw TokenList, with a PropertyId as the name.