1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
use std::{
collections::HashMap,
path::{Path, PathBuf},
};
use crate::{builtin::Builtin, Fs, StdFs};
/// Configuration for Sass compilation
///
/// The simplest usage is `grass::Options::default()`; however, a builder pattern
/// is also exposed to offer more control.
#[derive(Debug)]
pub struct Options<'a> {
pub(crate) fs: &'a dyn Fs,
pub(crate) style: OutputStyle,
pub(crate) load_paths: Vec<PathBuf>,
pub(crate) allows_charset: bool,
pub(crate) unicode_error_messages: bool,
pub(crate) quiet: bool,
pub(crate) input_syntax: Option<InputSyntax>,
pub(crate) custom_fns: HashMap<String, Builtin>,
}
impl Default for Options<'_> {
#[inline]
fn default() -> Self {
Self {
fs: &StdFs,
style: OutputStyle::Expanded,
load_paths: Vec::new(),
allows_charset: true,
unicode_error_messages: true,
quiet: false,
input_syntax: None,
custom_fns: HashMap::new(),
}
}
}
impl<'a> Options<'a> {
/// This option allows you to control the file system that Sass will see.
///
/// By default, it uses [`StdFs`], which is backed by [`std::fs`],
/// allowing direct, unfettered access to the local file system.
#[must_use]
#[inline]
pub fn fs(mut self, fs: &'a dyn Fs) -> Self {
self.fs = fs;
self
}
/// `grass` currently offers 2 different output styles
///
/// - [`OutputStyle::Expanded`] writes each selector and declaration on its own line.
/// - [`OutputStyle::Compressed`] removes as many extra characters as possible
/// and writes the entire stylesheet on a single line.
///
/// By default, output is expanded.
#[must_use]
#[inline]
pub const fn style(mut self, style: OutputStyle) -> Self {
self.style = style;
self
}
/// This flag tells Sass not to emit any warnings
/// when compiling. By default, Sass emits warnings
/// when deprecated features are used or when the
/// `@warn` rule is encountered. It also silences the
/// `@debug` rule.
///
/// By default, this value is `false` and warnings are emitted.
#[must_use]
#[inline]
pub const fn quiet(mut self, quiet: bool) -> Self {
self.quiet = quiet;
self
}
/// All Sass implementations allow users to provide
/// load paths: paths on the filesystem that Sass
/// will look in when locating modules. For example,
/// if you pass `node_modules/susy/sass` as a load path,
/// you can use `@import "susy"` to load `node_modules/susy/sass/susy.scss`.
///
/// Imports will always be resolved relative to the current
/// file first, though. Load paths will only be used if no
/// relative file exists that matches the module's URL. This
/// ensures that you can't accidentally mess up your relative
/// imports when you add a new library.
///
/// This method will append a single path to the list.
#[must_use]
#[inline]
pub fn load_path<P: AsRef<Path>>(mut self, path: P) -> Self {
self.load_paths.push(path.as_ref().to_owned());
self
}
/// Append multiple loads paths
///
/// Note that this method does *not* remove existing load paths
///
/// See [`Options::load_path`](Options::load_path) for more information about
/// load paths
#[must_use]
#[inline]
pub fn load_paths<P: AsRef<Path>>(mut self, paths: &[P]) -> Self {
for path in paths {
self.load_paths.push(path.as_ref().to_owned());
}
self
}
/// This flag tells Sass whether to emit a `@charset`
/// declaration or a UTF-8 byte-order mark.
///
/// By default, Sass will insert either a `@charset`
/// declaration (in expanded output mode) or a byte-order
/// mark (in compressed output mode) if the stylesheet
/// contains any non-ASCII characters.
#[must_use]
#[inline]
pub const fn allows_charset(mut self, allows_charset: bool) -> Self {
self.allows_charset = allows_charset;
self
}
/// This flag tells Sass only to emit ASCII characters as
/// part of error messages.
///
/// By default Sass will emit non-ASCII characters for
/// these messages.
///
/// This flag does not affect the CSS output.
#[must_use]
#[inline]
pub const fn unicode_error_messages(mut self, unicode_error_messages: bool) -> Self {
self.unicode_error_messages = unicode_error_messages;
self
}
/// This option forces Sass to parse input using the given syntax.
///
/// By default, Sass will attempt to read the file extension to determine
/// the syntax. If this is not possible, it will default to [`InputSyntax::Scss`].
///
/// This flag only affects the first file loaded. Files that are loaded using
/// `@import`, `@use`, or `@forward` will always have their syntax inferred.
#[must_use]
#[inline]
pub const fn input_syntax(mut self, syntax: InputSyntax) -> Self {
self.input_syntax = Some(syntax);
self
}
/// Add a custom function accessible from within Sass
///
/// See the [`Builtin`] documentation for additional information
#[must_use]
#[inline]
#[cfg(any(feature = "custom-builtin-fns", doc))]
#[cfg_attr(doc_cfg, doc(cfg(feature = "custom-builtin-fns")))]
pub fn add_custom_fn<S: Into<String>>(mut self, name: S, func: Builtin) -> Self {
self.custom_fns.insert(name.into(), func);
self
}
pub(crate) fn is_compressed(&self) -> bool {
matches!(self.style, OutputStyle::Compressed)
}
}
/// Useful when parsing Sass from sources other than the file system
///
/// See [`Options::input_syntax`] for additional information
#[non_exhaustive]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum InputSyntax {
/// The CSS-superset SCSS syntax.
Scss,
/// The whitespace-sensitive indented syntax.
Sass,
/// The plain CSS syntax, which disallows special Sass features.
Css,
}
impl InputSyntax {
pub(crate) fn for_path(path: &Path) -> Self {
match path
.extension()
.and_then(|ext| ext.to_str())
.map(str::to_ascii_lowercase)
.as_deref()
{
Some("css") => Self::Css,
Some("sass") => Self::Sass,
_ => Self::Scss,
}
}
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum OutputStyle {
/// This mode writes each selector and declaration on its own line.
///
/// This is the default output.
Expanded,
/// Ideal for release builds, this mode removes as many extra characters as
/// possible and writes the entire stylesheet on a single line.
Compressed,
}