values.combine()
Last updated
Was this helpful?
Last updated
Was this helpful?
The values.combine()
function combines multiple into the list. By default, the function use append method to combine . The parameters of the list (bracketed
, delimiter
, method
, null
, separator
) can be changed by providing map value eg. (method: join).
// Sass.
@use 'sass:list';
@use 'sass:meta';
// Functions.
@use '../list/list.join.function' as *;
// Modules.
@use '../map';
// The `values.combine()` function.
@function combine($values...) {
$parameters: (
bracketed: map.get(list.nth($values, 1), bracketed, auto),
delimiter: null,
method: append,
null: false,
separator: map.get(list.nth($values, 1), separator, auto),
);
$result: list.join((), (), map.pick($parameters, separator, bracketed)...);
@each $value in $values {
$allow: true;
$method: map.get($parameters, method);
@if type-of($value) ==
map and
map.has-keys($value, any, append, join, map.keys($parameters)...)
{
$parameters: map.merge($parameters, map.remove($value, append, join));
@if map.has-keys($value, any, append, join) {
@each $use-method, $use-value in $value {
$method: $use-method;
$value: $use-value;
}
} @else {
$allow: false;
}
}
@if not map.get($parameters, null) and not $value {
$allow: false;
}
@if $allow {
$result: meta.call(
meta.get-function($method),
$result,
$value,
map.pick(
$parameters,
if($method == join, (separator, bracketed), separator)...
)...
);
}
}
@if map.get($parameters, delimiter) {
$result: join((), $result, map.pick($parameters, separator, delimiter)...);
}
@return $result;
}
$values...
Arbitrary values to combine into the returned list.
The return value is the list
combined by the specified method, with a separator, and/or delimiter.
// Use.
@use '@angular-package/sass/values';
// Examples.
// The default append method + separator auto.
@debug values.combine('&', layout sidebar, primary dark, extra small); // "&" (layout sidebar) (primary dark) (extra small)
@debug values.combine(('&', dark), layout sidebar, primary dark, extra small); // ("&", dark) (layout sidebar) (primary dark) (extra small)
// Join method + separator auto.
@debug values.combine((method: join), '&', layout sidebar, primary dark, extra small); // "&" layout sidebar primary dark extra small
@debug values.combine((method: join), ('&', dark), layout sidebar, primary dark, extra small); // "&", dark, layout, sidebar, primary, dark, extra, small
@debug values.combine((method: join), '&' dark, layout sidebar, primary dark, extra small); // "&" dark layout sidebar primary dark extra small
// Append method + separator space and comma.
@debug values.combine((separator: space), '&', layout sidebar, primary dark, extra small); // "&" (layout sidebar) (primary dark) (extra small)
@debug values.combine((separator: comma), '&', layout sidebar, primary dark, extra small); // "&", layout sidebar, primary dark, extra small
// Join method + separator space and comma.
@debug values.combine((separator: space, method: join), '&', layout sidebar, primary dark, extra small); // "&" layout sidebar primary dark extra small
@debug values.combine((separator: comma, method: join), '&', layout sidebar, primary dark, extra small); // "&", layout, sidebar, primary, dark, extra, small
// Combine with `append` or `join` key.
@debug values.combine((append: first append), '&', layout sidebar, primary dark, extra small); // (first append) "&" (layout sidebar) (primary dark) (extra small)
@debug values.combine((append: (first, append)), '&', layout sidebar, primary dark, extra small); // (first, append) "&" (layout sidebar) (primary dark) (extra small)
@debug values.combine((join: first append), '&', layout sidebar, primary dark, extra small); // first append "&" layout sidebar primary dark extra small
@debug values.combine((join: (first, append)), '&', layout sidebar, primary dark, extra small); // first, append, "&", layout, sidebar, primary, dark, extra, small
@debug values.combine((method: join), '&', layout sidebar, (append: first append), primary dark, extra small); // "&" layout sidebar (first append) primary dark extra small
@debug values.combine('&', layout sidebar, (join: first join), primary dark, extra small); // "&" (layout sidebar) first join (primary dark) (extra small)
@debug values.combine((method: join, separator: comma), '&', layout sidebar, (append: first append), primary dark, extra small); // "&", layout, sidebar, first append, primary, dark, extra, small
@debug values.combine((separator: comma), '&', layout sidebar, (join: first join), primary dark, extra small); // "&", layout sidebar, first, join, primary dark, extra small
// Bracketed.
@debug values.combine((bracketed: true), '&', layout sidebar, primary dark, extra small); // ["&" (layout sidebar) (primary dark) (extra small)]
// Bracketed + separator.
@debug values.combine((bracketed: true, separator: comma), '&', layout sidebar, primary dark, extra small); // ["&", layout sidebar, primary dark, extra small]
// Bracketed + join method.
@debug values.combine((bracketed: true, method: join), '&', layout sidebar, primary dark, extra small); // ["&" layout sidebar primary dark extra small]
// Bracketed + separator + join method
@debug values.combine((method: join, separator: comma, bracketed: true), '&', layout sidebar, primary dark, extra small); // ["&", layout, sidebar, primary, dark, extra, small]
// Change method.
@debug values.combine((one, two), three, (four, five), (six seven), primary dark, extra small); // (one, two) three (four, five) (six seven) (primary dark) (extra small)
@debug values.combine((one, two), three, (method: join), (four, five), (six seven), primary dark, extra small); // (one, two) three four five six seven primary dark extra small
@debug values.combine((one, two), three, (method: join), (four, five), (six seven), (method: append), primary dark, extra small); // (one, two) three four five six seven (primary dark) (extra small)
// method (join: value) (append: value)
@debug values.combine((join: (one, two)), (join: three), (four, five), (six seven), primary dark, extra small); // one two three (four, five) (six seven) (primary dark) (extra small)
@debug values.combine((join: one two), three, (four, five), (six seven), (append: (primary dark extra small))); // one two three (four, five) (six seven) (primary dark extra small)
// Add delimiter + add null values.
@debug values.combine(['a' 1], 'b' 2, ['c' 3], null, (separator: comma, null: true, delimiter: '-'), null, null, (append: 1 2 3), age 32, first name ); // ["a" 1], "-", "b" 2, "-", ["c" 3], "-", null, "-", null, "-", 1 2 3, "-", age 32, "-", first name
@debug values.combine((method: join, delimiter: separator), 'a' 1 , 'b' 2, 'c' 3); // "a" separator 1 separator "b" separator 2 separator "c" separator 3
@debug values.combine((method: join, separator: comma, delimiter: separator basic), 'a' 1 , 'b' 2, 'c' 3); // "a", separator basic, 1, separator basic, "b", separator basic, 2, separator basic, "c", separator basic, 3
// Sass.
@use 'sass:list';
@use 'sass:meta';
// Functions.
@use '../list/list.append.function' as *;
@use '../list/list.has.function' as *;
@use '../list/list.join.function' as *;
// Modules.
@use '../map';
// Status: TODO: join on if
// The `values.combine()` function combines multiple `$values` into the list. By default, the function use append method
// to combine `$values`. The parameters of the list (bracketed, delimiter, method, null, separator) can be changed by
// providing map value eg. (method: join).
// @arbitrary `$values...` Arbitrary values to combine into the returned list.
// @return The return value is the list combined by the specified method, with a separator, and/or delimiter.
@function combine($values...) {
$allowed-parameters: (
bracketed: (auto, bool),
delimiter: (string, number),
method: (append, join),
null: bool,
separator: (auto, comma, space, slash)
);
$parameters: map.merge-allowed((
bracketed: auto,
delimiter: null,
method: append,
null: false,
separator: auto
),
list.nth($values, 1),
$allowed-parameters
);
$result: list.join((), (), map.pick($parameters, separator, bracketed)...);
@each $value in $values {
$allow: true;
$method: map.get($parameters, method);
@if type-of($value) == map and list.length(map.keys(map.remove($value, append, join, map.keys($parameters)...))) == 0 {
$parameters: map.merge-allowed($parameters, map.remove($value, append, join), $allowed-parameters);
@if has(map.keys($value), any, '==', append, join) { // Append/Join the value.
@each $use-method, $use-value in map.pick($value, append, join) {
@if $use-value {
$method: $use-method;
$value: $use-value;
}
}
} @else {
$allow: false;
}
}
@if not map.get($parameters, null) and not $value {
$allow: false;
}
@if $allow {
$result: meta.call(
meta.get-function($method),
$result,
$value,
map.pick($parameters, if($method == join, (separator, bracketed), separator)...)...
);
}
}
@if map.get($parameters, delimiter) {
$result: join((), $result, map.pick($parameters, separator, delimiter)...);
}
@return $result;
}
// Examples.
// The default append method + separator auto.
// @debug combine('&', layout sidebar, primary dark, extra small); // "&" (layout sidebar) (primary dark) (extra small)
// @debug combine(('&', dark), layout sidebar, primary dark, extra small); // ("&", dark) (layout sidebar) (primary dark) (extra small)
// Join method + separator auto.
// @debug combine((method: join), '&', layout sidebar, primary dark, extra small); // "&" layout sidebar primary dark extra small
// @debug combine((method: join), ('&', dark), layout sidebar, primary dark, extra small); // "&", dark, layout, sidebar, primary, dark, extra, small
// @debug combine((method: join), '&' dark, layout sidebar, primary dark, extra small); // "&" dark layout sidebar primary dark extra small
// Append method + separator space and comma.
// @debug combine((separator: space), '&', layout sidebar, primary dark, extra small); // "&" (layout sidebar) (primary dark) (extra small)
// @debug combine((separator: comma), '&', layout sidebar, primary dark, extra small); // "&", layout sidebar, primary dark, extra small
// Join method + separator space and comma.
// @debug combine((separator: space, method: join), '&', layout sidebar, primary dark, extra small); // "&" layout sidebar primary dark extra small
// @debug combine((separator: comma, method: join), '&', layout sidebar, primary dark, extra small); // "&", layout, sidebar, primary, dark, extra, small
// Combine with `append` or `join` key.
// @debug combine((append: first append), '&', layout sidebar, primary dark, extra small); // (first append) "&" (layout sidebar) (primary dark) (extra small)
// @debug combine((append: (first, append)), '&', layout sidebar, primary dark, extra small); // (first, append) "&" (layout sidebar) (primary dark) (extra small)
// @debug combine((join: first append), '&', layout sidebar, primary dark, extra small); // first append "&" layout sidebar primary dark extra small
// @debug combine((join: (first, append)), '&', layout sidebar, primary dark, extra small); // first, append, "&", layout, sidebar, primary, dark, extra, small
// @debug combine((method: join), '&', layout sidebar, (append: first append), primary dark, extra small); // "&" layout sidebar (first append) primary dark extra small
// @debug combine('&', layout sidebar, (join: first join), primary dark, extra small); // "&" (layout sidebar) first join (primary dark) (extra small)
// @debug combine((method: join, separator: comma), '&', layout sidebar, (append: first append), primary dark, extra small); // "&", layout, sidebar, first append, primary, dark, extra, small
// @debug combine((separator: comma), '&', layout sidebar, (join: first join), primary dark, extra small); // "&", layout sidebar, first, join, primary dark, extra small
// Bracketed.
// @debug combine((bracketed: true), '&', layout sidebar, primary dark, extra small); // ["&" (layout sidebar) (primary dark) (extra small)]
// Bracketed + separator.
// @debug combine((bracketed: true, separator: comma), '&', layout sidebar, primary dark, extra small); // ["&", layout sidebar, primary dark, extra small]
// Bracketed + join method.
// @debug combine((bracketed: true, method: join), '&', layout sidebar, primary dark, extra small); // ["&" layout sidebar primary dark extra small]
// Bracketed + separator + join method
// @debug combine((method: join, separator: comma, bracketed: true), '&', layout sidebar, primary dark, extra small); // ["&", layout, sidebar, primary, dark, extra, small]
// Change method.
// @debug combine((one, two), three, (four, five), (six seven), primary dark, extra small); // (one, two) three (four, five) (six seven) (primary dark) (extra small)
// @debug combine((one, two), three, (method: join), (four, five), (six seven), primary dark, extra small); // (one, two) three four five six seven primary dark extra small
// @debug combine((one, two), three, (method: join), (four, five), (six seven), (method: append), primary dark, extra small); // (one, two) three four five six seven (primary dark) (extra small)
// method (join: value) (append: value)
// @debug combine((join: (one, two)), (join: three), (four, five), (six seven), primary dark, extra small); // one two three (four, five) (six seven) (primary dark) (extra small)
// @debug combine((join: one two), three, (four, five), (six seven), (append: (primary dark extra small))); // one two three (four, five) (six seven) (primary dark extra small)
// Add delimiter + add null values.
// @debug combine(['a' 1], 'b' 2, ['c' 3], null, (separator: comma, null: true, delimiter: '-'), null, null, (append: 1 2 3), age 32, first name ); // ["a" 1], "-", "b" 2, "-", ["c" 3], "-", null, "-", null, "-", 1 2 3, "-", age 32, "-", first name
// @debug combine((method: join, delimiter: separator), 'a' 1 , 'b' 2, 'c' 3); // "a" separator 1 separator "b" separator 2 separator "c" separator 3
// @debug combine((method: join, separator: comma, delimiter: separator basic), 'a' 1 , 'b' 2, 'c' 3); // "a", separator basic, 1, separator basic, "b", separator basic, 2, separator basic, "c", separator basic, 3
// Provide separator
// @debug combine(1, 2, (delimiter: '-', separator: space), 3, 4);
// @debug combine(1, 2, (separator: comma), (prefix: spectre, separator: '-', suffix: end), 4, 5);