sass.language.txt

                                  ┏━━━━━━━━━━┓
                                  ┃   SASS   ┃
                                  ┗━━━━━━━━━━┛

ALTERNATIVES ==>              #See PostCSS

GENERAL ==>                   #Server-side CSS preprocessor.
                              #Is a Ruby GEM (version 3.4.11)
                              #In short can:
                              #  - nest rules
                              #  - inherit rules (@extend)
                              #  - use variables
                              #  - use mixins, functions and structures
                              #  - make calculation (#{EXPR})
                              #  - better @import
                              #  - standard library for native types manipulation: color, string, number, obj, arr, selectors
                              #Two syntaxes:
                              #  - CSS is compatible SCSS but not SASS
                              #  - SASS is more concise but older and deprecated (this doc uses SCSS)
                              #  - .scss and .sass file extensions
                              #  - can convert between each other with sass-convert
                              #Syntax:
                              #  - SassScript: all except SELECTORS { RULES } related interpolations.
                              #  - Some output syntax is only valid during the temporary preprocessing, but not in CSS: marked
                              #    "invalid CSS"
                              #Doc syntax:
                              #  - SELECTOR: e.g. .myclass:hover
                              #  - SELECTORS: SELECTOR,...
                              #  - RULE: "PROP: VAL", e.g. color: red;
                              #  - RULES: RULE...
                              #  - arg means argument named $arg, but TYPE means argument of TYPE
                              #  - FUNC()
                              #  - #MIXIN(): MIXIN as opposed to FUNC()
                              #  - ##MIXIN(): MIXIN with a { ... } block (CONTENT)

DIFFERENCE SASS/LESS ==>      #See Less doc.

                                  ┌──────────────────┐
                                  │   COMMAND LINE   │
                                  └──────────────────┘

sass [FILE] [FILE2]           #Def. FILE is stdin, def. FILE2 is stdout
--scss                        #Forces SCSS syntax (def: auto according to file extension, or SASS if none)
--interactive                 #Interactive mode (for SassScript)
--check                       #Dry-run

--style STR                   #For whitespaces, according to:
                              #  - nested (def): unnested rules are indented
                              #  - expanded: unnested rules are not indented. Also different braces style.
                              #  - compact: one line per ruleset
                              #  - compressed: minify
--sourcemap=TYPE              #Creates sourcemap CSS_FILE.map and adds a comment in CSS_FILE pointing to CSS_FILE.map:
                              #  - auto (def): relative|absolute URI, depending on case
                              #  - file: absolute URI
                              #  - inline: include full SCSS in CSS
                              #  - none
--line-numbers                #Put original line numbers in CSS comments.

-E ENCODING                   #Otherwise respect @charset or def to UTF-8
--unix-newlines               #Forces Unix newlines even on Window

--require MODULE              #Require a Ruby module

--watch
INPUT_FILE|DIR:OUTPUT_FILE|DIR#Watch mode. Can add --stop-on-error
--poll                        #For --watch, trigger with --update, not automatically.
                              #With --update --force, also work if CSS is newer than SCSS file

CACHING ==>                   #Write temp files to cache input -> output translation at ./.sass-cache/ (can be changed with
                              #--cache-location DIR)
                              #Can be disabled with --no-cache


GULP-SASS([OBJ])              #OBJ:
                              #  - out FILE
                              #  - outputStyle STR: like sass --style
                              #  - onSuccess(CSS_STR)
                              #  - onError(ERROR)
                              #  - errLogToConsole BOOL: if true (def: false), uses console.error instead of throwing error
                              #  - includePaths STR_ARR: like sass -I
                              #  - indentedSyntax BOOL: if true, uses .sass, not .scss
                              #  - sourceComments BOOL
                              #Sourcemaps:
                              #  - in OBJ:
                              #     - sourceMapEmbed BOOL
                              #     - sourceMapContents BOOL
                              #     - omitSourceMapUrl BOOL
                              #  - should use SOURCEMAPS.init() before and SOURCEMAPS.write() after (see Gulp-Uglify)
                              #Version 1.3.1

                                  ┌───────────────────────┐
                                  │   SELECTORS & RULES   │
                                  └───────────────────────┘

// COMMENT                    #Never kept
/* COMMENT */                 #Kept except in --style compressed
/* !COMMENT */                #Always kept

SELECTORS {                   #  SELECTORS { RULES }
  RULES                       #  SELECTORS SELECTORS2 { RULES2 }
  SELECTORS2 { RULES2 }       #If a SELECTOR2 starts with &, & is replaced with SELECTORS and uses instead:
}                             #  SELECTORS { RULES }
                              #  SELECTORS2 { RULES2 }

PROP1: { PROP2: VAL ... }     #  PROP1-PROP2: VAL ...
PROP1: VAL1 {PROP2: VAL2 ...} #  PROP1: VAL1; PROP1-PROP2: VAL2 ...

@at-root [(without: WORD...)] #Unnest { SELECTORS { ... } } by detaching from parent (according to WORD... (space-separated)):
{ SELECTORS { ... } }         #  - rule (def): SELECTORS except @DIRECTIVE
                              #  - DIRECTIVE: @DIRECTIVE
                              #  - all: all @DIRECTIVE + SELECTORS
@at-root (with: WORD...)
{ SELECTORS { ... } }         #Like (with: all), except WORD...
@at-root (...) SELECTORS {...}#Same as @at-root (...) { SELECTORS { ... } }

[@media MEDIAQUERY... {
  RULES1]
  SELECTORS {
    RULES2
    @media MEDIAQUERY2... {
      RULES3
    }                         #  [@media MEDIAQUERY... { RULES1 }]
  }                           #  [@media MEDIAQUERY...] { SELECTORS { RULES2 } }
}                             #  [@media MEDIAQUERY...] MEDIAQUERY2... { SELECTORS { RULES3 } }
@OTHER                        #e.g. @keyframe, @font-face, etc.
                              #Are put out of their parent SELECTOR (but not parent MEDIAQUERY), without any change.

@extend SELECTORS [!optional] #Inheritance:
                              #  - RULE adding current SELECTOR to any selector matching SELECTORS (even if not exactly equal),
                              #    meaning current ruleset "inherits" from SELECTORS rulesets.
                              #  - SELECTORS can't be:
                              #     - .CLASS.CLASS2
                              #  - error if SELECTORS doesn't match anything unless !optional
                              #  - in a @ directive, only match SELECTORS within that directive
%CLASS                        #Like .CLASS in SELECTORS but:
                              #  - whole ruleset not compiled to CSS
                              #  - can only be used through %CLASS in SELECTORS of @extend SELECTORS

@import FILE,...              #Treat it as SCSS/SASS files to import and merge into single CSS output unless:
                              #  - CSS file not SCSS/SASS
                              #  - URL not FILE
                              #  - has media query (@import FILE STR)
                              #Note:
                              #  - .scss|sass can be ommitted from FILE
                              #  - FILE (in filesystem) can start with _ and it will mean FILE will be not used in final output (CSS "partial")
                              #    _ can be ommitted from FILE (in @import rule)
                              #Can be used as a RULE:
                              #  - FILE content will be merged with current SELECTORS and RULES
                              #  - FILE content cannot use @ directives
                              #  - Cannot be nested
                              #Search path is $PWD, but can add with -I DIR
                             ##Can use globbing (including **). Sort alphabetically (careful about import order).
                             ##Must use Ruby module sass-globbing

                                  ┌────────────────┐
                                  │   SASSSCRIPT   │
                                  └────────────────┘

#{EXPR}                       #Interpolates SassScript expression ($VAR, NUM + NUM2, etc.) anywhere, including inside a STR,
                              #SELECTOR, PROP, etc.
                              # #{null} -> ""
@debug EXPR                   #Prints to stdout when compiling
@warn EXPR                    #Same to stderr, with stack trace
                              #Can be removed with --quiet
@error EXPR                   #Same but stops compilation

SCOPE ==>                     #$VAR|MIXIN|FUNC:
                              #  - No variable hoisting.
                              #  - Declaring twice overwrites previous declaration.
                              #  - caller/callee cannot access each other (aside from arguments)
                              #@content has scope of caller, not current MIXIN

$VAR: VAL [!default];         #Declaration + assignment.
                              #If !default, don't redefine if already declared, unless null.
$VAR                          #Usage

VARIABLES ==>                 #Are scoped. Can declare global by putting out of scope, or use $VAR: VAL !global;
                              #Types (on right is CSS type):
                              #  - STR: STR, VAR, URANGE, POSITION (STR_ARR), SHAPE, URI, IMAGE, GRADIENT, FUNC
                              #     - CSS require some of them to have or not have quotes around: must respect this in final
                              #       output, even if SCSS STR can have either (e.g. no quotes for VAR)
                              #     - STR + STR2: concatenation
                              #        - "STR" + STR2 -> "STR3"
                              #  - NUM: NUM, LEN, LENP, PERC, ANGLE, TIME
                              #     - + - * / %
                              #     - Can square/divide units, e.g. 10px*10px -> 10px*px (invalid CSS)
                              #     - division must be surrounded by parenthesis, i.e. (NUM/NUM2), unless NUM[2] is a SCSS
                              #       function or variable, or used in a more complex function, like NUM3 + NUM/NUM2
                              #     - to prevent operation, can use #{NUM}, e.g. #{$VAR}/NUM -> "VAL/NUM"
                              #     - number of digits of floats depend on --precision NUM (def: 5)
                              #  - COLOR: COLOR
                              #     - includes new color names
                              #     - + - * /
                              #        - must have same alpha value, which is not affected by operation
                              #  - BOOL:
                              #     - or, and, not
                              #     - for any VAL: == !=
                              #     - for NUM: < <= => >
                              #  - null
                              #  - OBJ:
                              #     - (KEY: VAL,...)
                              #     - empty OBJ: ()
                              #     - can auto. transtype to STR_ARR_ARR (KEY VAL,...)
                              #     - only valid SCSS not CSS
VAL_ARR                       #Array:
                              #  - flatten to VAL VAL2 ... when converted to CSS
                              #  - space or comma-separated
                              #  - Can be nested (VAL_ARR_ARR) by:
                              #     - switching from space to comma: VAL VAL2, VAL3 VAL4
                              #     - using parenthesis: (VAL VAL2) (VAL3 VAL4)
                              #     - to represent equivalent of [ [ VAL VAL2 ... ] ], use (VAL VAL2,)
                              #  - can be empty, e.g. (), (invalid CSS)
SELECTORS                     #Is STR_ARR[_ARR], e.g. "a b, c" -> (a b, c)
                              #Second depth level can be ommitted if none.
                              #Can use STR instead of STR_ARR[_ARR], e.g. "a b" or "a b, c" directly

&                             #Replaced by parent SELECTORS. If no parent, null.

@if BOOL { ... }
@else if BOOL { ... }
...
@else { ... }                 #
if(CONDITION,IF-TRUE,IF-FALSE)#

@for $VAR
from NUM to|through NUM2
{ ... }                       #to is like through NUM2 - 1

@each $VAR in STR_ARR|OBJ
{ ... }                       #
@each $VAR,... in STR_ARR_ARR
{ ... }                       #Can use OBJ which will convert to STR_ARR_ARR

@while EXPR { ... }           #

@mixin MIXIN                  #Declaration of a MIXIN (macro)
[($VAR[: VAL],...)] { ... }   #Can use other MIXIN2 (@include MIXIN2) or themselves (@include MIXIN, recursion)
                              #Can have arguments $VAR,...:
                              #  - VAL are default values.
                              #  - Last argument can be variadic as $VAR... (with three dots) (will be an ARR)
                              #     - can be used to augment another mixin, by passing $VAR... around
@include MIXIN[(VAL,...)];    #Usage. Top-level or as a RULE.
                              #Can use:
                              #  - named arguments with MIXIN($PARAM: VAL, ...) too
                              #  - $VAR... (with three dots) meaning it flattens an ARR or an OBJ values to several arguments
                              #    For OBJ, will use named arguments $KEY: VAL, ...
@content                      #Can be used in a MIXIN block, in which case:
                              #  - must be used as @include MIXIN[(VAL,...)] { SELECTORS { RULES } }
                              #  - SELECTORS { RULES } will replace @content in the mixin.
                              #    SELECTORS will merge with @content selectors.

@function FUNC(...)           #Similar to mixins, except:
{ @return VAL; }              #  - use return value, not whole mixin block
FUNC(...)                     #  - can be used anywhere as a VAL, not just as a RULE or top-level.

                                  ┌───────────────┐
                                  │   FUNCTIONS   │
                                  └───────────────┘

rgb(red, green, blue)
rgba(red, green, blue, alpha)
rgba(color, alpha)            #Returns COLOR. RED|GREEN|BLUE are from 1 to 255. ALPHA from 0 to 1.
red|green|blue(color)         #NUM from 1 to 255
alpha|opacity(color)          #NUM from 0 to 1
opacify|fade-in(color, amount)#Adds opacity
transparentize|fade-out
(color, amount)               #Removes opacity

hsl(hue, saturation,lightness)#Returns COLOR.
                              #HUE is ANGLE, SATURATION|LIGHTNESS percentages.
hsla(hue,saturation,lightness,
alpha)                        #
hue|saturation|lightness(colr)#Returns ANGLE or percentage.
adjust-hue(color, degrees)    #
lighten|darken(color, amount) #
[de]saturate(color, amount)   #Returns COLOR2 with new hue|saturation|lightness
complement(color)             #Like adjust-hue(COLOR, 180deg)
invert(color)                 #Invert hue and lightness.
grayscale(color)              #Like desaturate(COLOR, 100)

mix(color, color2[, weight])  #WEIGHT is first COLOR's weight, percentage or float (def: 50%). Returns COLOR3.
adjust|scale|change-color
([red,][green,][blue,][hue,]
[saturation,][lightness,]     #Returns COLOR2 with new properties.
[alpha])                      #adjust use absolute NUM increment, scale relative percentages, change

[un]quote(STRING)             #
str-length(STRING)            #
str-insert
(STRING, STRING2, INDEX)      #Inserts STRING2 at position INDEX of STRING
str-index(STRING, STRING2)    #Returns index of substring STRING2 inside STRING, null if none.
str-slice
(STRING, START-AT[, END-AT])  #START|END-AT can be negative (from end of STRING). END-AT def: -1. Index starts at 1.
to-upper|lower-case(STRING)   #

percentage(NUMBER)            #Multiply by 100 and returns as percentage
round|ceil|floor(NUMBER)      #
abs(NUMBER)                   #
min|max(NUMBERS...)           #
random([LIMIT])               #Returns float between [0;1) or (if LIMIT) integer between [1;LIMIT]

nth(ARR, NUM)                 #Returns NUM[ARR] (index starts at 1)
index(ARR, N)                 #Returns position of value N, or null if not found.
length(ARR)                   #
join(ARR, ARR2[, SEPARATOR])  #Concanate as uni-dimensional ARR. Separate used is (in order):
                              #  - if SEPARATOR "comma|space", use it
                              #  - if both ARR and ARR2 have same, use it
                              #  - if ARR and ARR2 have 0 or 1 item, use "space"
                              #  - if different, use ARR's
append(ARR, VAL[, SEPARATOR]) #Same as join() with a VAL instead of ARR
zip(ARR...)                   #Concanate as multi-dimensional ARR_ARR
list-separator(ARR)           #Returns "space|comma" (def: "space" if 0 or 1 element)

map-get(OBJ, KEY)             #Returns OBJ[KEY]
map-has-key(OBJ, KEY)         #
map-keys(OBJ)                 #Returns STR_ARR
map-values(OBJ)               #Returns VAL_ARR
map-merge(OBJ1, OBJ2)         #OBJ2 has priority.
map-remove(OBJ, KEYS...)      #
keywords(OBJ)                 #Removes leading "$" from keys. Used to @debug($args) in a @mixin MIXIN($args...)

SELECTORS ==>                 #Can include %CLASS but not &
selector-nest(SELECTORS...)   #Returns a single SELECTORS by joining with spaces (meaning descendants).
                              #Not-first selector can include & as a macro referencing to previous selector.
selector-append(SELECTORS...) #Same but with nothing in-between (meaning combination).
selector-extend
(SELECTORS,EXTENDEE, EXTENDER)#Returns SELECTORS2 that would come from SELECTORS { ... } EXTENDER { @extend EXTENDEE }
selector-replace(SELECTORS,
ORIGINAL, REPLACEMENT)        #Replace instances of ORIGINAL by REPLACEMENT inside SELECTOR
selector-unify
(SELECTORS1, SELECTORS2)      #Returns SELECTORS3 that match both SELECTORS1 and SELECTORS2 at same time
is-superselector(SUPER, SUB)  #Returns true if SUPER matches anything that match SUB (subselector)
simple-selectors(SELECTOR)    #Returns as ARR, by separating CLASS.CLASS2 -> (CLASS,CLASS2), CLASS#CLASS2 -> (CLASS,CLASS2),
                              #etc.
selector-parse(SELECTOR)      #Returns as ARR_ARR, by separating commas into first dimension, and spaces into second.

[global-]variable-exists(NAME)#Returns true if $NAME exists [globally]
function-exists(NAME)         #
mixin-exists(NAME)            #Same for FUNC and MIXIN
feature-exists(FEATURE)       #Returns true if current SASS supports this FEATURE: global-variable-shadowing (!global),
                              #extend-selector-pseudoclass (@extend recognize CSS pseudoclass), units-level-3 (Units CSS3),
                              #at-error (@error)
inspect(VALUE)                #Retuns EXPR VALUE parsed.
type-of(VALUE)                #Returns "number|string|bool|color|null|map|list"
unit(NUMBER)                  #Returns "|px|em|px*px|..."
unitless(NUMBER)              #Returns unit(NUMBER) == ""
comparable(NUMBER1, NUMBER2)  #Returns if can use + - == != according to units.

call(NAME, ARGS...)           #Fire NAME_FUNC(ARGS...)

unique-id()                   #Returns random [[:lower:][:digit:]], 9 characters (32 bits of entropy) (time-based + counter)