中文
内建函数(Build-in Funcitons)
颜色函数
red(color[, value])
返回给定color
的红色分量,或将红色分量设置为可选的第二个value
参数。
red(#c00)
// => 204
red(#000, 255)
// => #f00
red(#c00)
// => 204
red(#000, 255)
// => #f00
green(color[, value])
返回给定color
的绿色分量,或将绿色分量设置为可选的第二个value
参数。
green(#0c0)
// => 204
green(#000, 255)
// => #0f0
green(#0c0)
// => 204
green(#000, 255)
// => #0f0
blue(color[, value])
返回给定color
的蓝色分量,或将蓝色分量设置为可选的第二个value
参数。
blue(#00c)
// => 204
blue(#000, 255)
// => #00f
blue(#00c)
// => 204
blue(#000, 255)
// => #00f
alpha(color[, value])
返回给定color
的alpha分量,或将alpha分量设置为可选的第二个value
参数。
alpha(#fff)
// => 1
alpha(rgba(0,0,0,0.3))
// => 0.3
alpha(#fff, 0.5)
// => rgba(255,255,255,0.5)
alpha(#fff)
// => 1
alpha(rgba(0,0,0,0.3))
// => 0.3
alpha(#fff, 0.5)
// => rgba(255,255,255,0.5)
dark(color)
检查color
是否是暗色:
dark(black)
// => true
dark(#005716)
// => true
dark(white)
// => false
dark(black)
// => true
dark(#005716)
// => true
dark(white)
// => false
light(color)
检查color
是否是亮色:
light(black)
// => false
light(white)
// => true
light(#00FF40)
// => true
light(black)
// => false
light(white)
// => true
light(#00FF40)
// => true
hue(color[, value])
返回给定color
的色调,或将色调设置为可选的第二个value
参数
hue(hsl(50deg, 100%, 80%))
// => 50deg
hue(#00c, 90deg)
// => #6c0
hue(hsl(50deg, 100%, 80%))
// => 50deg
hue(#00c, 90deg)
// => #6c0
saturation(color[, value])
返回给定color
的饱和度,或将饱和度分量设置为可选的第二个value
参数。
saturation(hsl(50deg, 100%, 80%))
// => 100%
saturation(#00c, 50%)
// => #339
saturation(hsl(50deg, 100%, 80%))
// => 100%
saturation(#00c, 50%)
// => #339
lightness(color[, value])
返回给定color
的亮度,或将亮度分量设置为可选的第二个value
参数。
lightness(hsl(50deg, 100%, 80%))
// => 80%
lightness(#00c, 80%)
// => #99f
lightness(hsl(50deg, 100%, 80%))
// => 80%
lightness(#00c, 80%)
// => #99f
hsla(color | h,s,l,a)
Convert the given color
to an HSLA
node, or h,s,l,a component values.
hsla(10deg, 50%, 30%, 0.5)
// => HSLA
hsla(#ffcc00)
// => HSLA
hsla(10deg, 50%, 30%, 0.5)
// => HSLA
hsla(#ffcc00)
// => HSLA
hsl(color | h,s,l)
Convert the given color
to an HSLA
node, or h,s,l,a component values.
hsl(10, 50, 30)
// => HSLA
hsl(#ffcc00)
// => HSLA
hsl(10, 50, 30)
// => HSLA
hsl(#ffcc00)
// => HSLA
rgba(color | r,g,b,a)
Return RGBA
from the r,g,b,a channels, or provide a color
to tweak the alpha.
rgba(255,0,0,0.5)
// => rgba(255,0,0,0.5)
rgba(255,0,0,1)
// => #ff0000
rgba(#ffcc00, 0.5)
// rgba(255,204,0,0.5)
rgba(255,0,0,0.5)
// => rgba(255,0,0,0.5)
rgba(255,0,0,1)
// => #ff0000
rgba(#ffcc00, 0.5)
// rgba(255,204,0,0.5)
Alternatively, Stylus supports the #rgba
and #rrggbbaa
notations as well:
#fc08
// => rgba(255,204,0,0.5)
#ffcc00ee
// => rgba(255,204,0,0.9)
#fc08
// => rgba(255,204,0,0.5)
#ffcc00ee
// => rgba(255,204,0,0.9)
rgb(color | r,g,b)
Return a RGBA
from the r,g,b channels or cast to an RGBA
node.
rgb(255,204,0)
// => #ffcc00
rgb(#fff)
// => #fff
rgb(255,204,0)
// => #ffcc00
rgb(#fff)
// => #fff
blend(top[, bottom])
Blends the given top
color over the bottom
one using the normal blending. The bottom
argument is optional, and defaults to #fff
.
blend(rgba(#FFF, 0.5), #000)
// => #808080
blend(rgba(#FFDE00,.42), #19C261)
// => #7ace38
blend(rgba(lime, 0.5), rgba(red, 0.25))
// => rgba(128,128,0,0.625)
blend(rgba(#FFF, 0.5), #000)
// => #808080
blend(rgba(#FFDE00,.42), #19C261)
// => #7ace38
blend(rgba(lime, 0.5), rgba(red, 0.25))
// => rgba(128,128,0,0.625)
lighten(color, amount)
Lighten the given color
by amount
.
This function is unit-sensitive; it supports percentages, for example, as shown here:
lighten(#2c2c2c, 30)
// => #787878
lighten(#2c2c2c, 30%)
// => #393939
lighten(#2c2c2c, 30)
// => #787878
lighten(#2c2c2c, 30%)
// => #393939
darken(color, amount)
Darken the given color
by amount
.
This function is unit-sensitive; it supports percentages, for example, as shown here:
darken(#D62828, 30)
// => #551010
darken(#D62828, 30%)
// => #961c1c
darken(#D62828, 30)
// => #551010
darken(#D62828, 30%)
// => #961c1c
desaturate(color, amount)
Desaturate the given color
by amount
.
desaturate(#f00, 40%)
// => #c33
desaturate(#f00, 40%)
// => #c33
saturate(color, amount)
Saturate the given color
by amount
.
saturate(#c33, 40%)
// => #f00
saturate(#c33, 40%)
// => #f00
complement(color)
Gives the complementary color. Equivalent to spinning hue by 180deg
.
complement(#fd0cc7)
// => #0cfd42
complement(#fd0cc7)
// => #0cfd42
invert(color)
Inverts the color. The red, green, and blue values are inverted. Opacity is left alone.
invert(#d62828)
// => #29d7d7
invert(#d62828)
// => #29d7d7
spin(color, amount)
Spins hue of the given color
by amount
.
spin(#ff0000, 90deg)
// => #80ff00
spin(#ff0000, 90deg)
// => #80ff00
grayscale(color)
Gives the grayscale equivalent of the given color. Equivalent to desaturate(color, 100%)
.
grayscale(#fd0cc7)
// => #0cfd42
grayscale(#fd0cc7)
// => #0cfd42
mix(color1, color2[, amount])
Mix two colors by a given amount. The amount
is optional and is defaulted to 50%
.
mix(#000, #fff, 30%)
// => #b2b2b2
mix(#000, #fff, 30%)
// => #b2b2b2
tint(color, amount)
Mix the given color with white.
tint(#fd0cc7,66%)
// => #feaceb
tint(#fd0cc7,66%)
// => #feaceb
shade(color, amount)
Mix the given color with black.
shade(#fd0cc7,66%)
// => #560443
shade(#fd0cc7,66%)
// => #560443
luminosity(color)
Returns the relative luminance of the given color
.
luminosity(white)
// => 1
luminosity(#000)
// => 0
luminosity(red)
// => 0.2126
luminosity(white)
// => 1
luminosity(#000)
// => 0
luminosity(red)
// => 0.2126
contrast(top[, bottom])
Returns the contrast ratio object between top
and bottom
colors, based on script underlying “contrast ratio” tool by Lea Verou.
The second argument is optional and is defaulted to #fff
.
The main key in the returned object is ratio
, it also have min
and max
values that are different from the ratio
only when the bottom
color is transparent. In that case the error
also contains an error margin.
contrast(#000, #fff).ratio
// => 21
contrast(#000, rgba(#FFF, 0.5))
// => { "ratio": "13.15;", "error": "-7.85", "min": "5.3", "max": "21" }
contrast(#000, #fff).ratio
// => 21
contrast(#000, rgba(#FFF, 0.5))
// => { "ratio": "13.15;", "error": "-7.85", "min": "5.3", "max": "21" }
transparentify(top[, bottom, alpha])
Returns the transparent version of the given top
color, as if it was blend over the given bottom
color (or the closest to it, if it is possible).
The second argument is optional and is defaulted to #fff
.
The third argument is optional and overrides the autodetected alpha.
transparentify(#808080)
// => rgba(0,0,0,0.5)
transparentify(#414141, #000)
// => rgba(255,255,255,0.25)
transparentify(#91974C, #F34949, 0.5)
// => rgba(47,229,79,0.5)
transparentify(#808080)
// => rgba(0,0,0,0.5)
transparentify(#414141, #000)
// => rgba(255,255,255,0.25)
transparentify(#91974C, #F34949, 0.5)
// => rgba(47,229,79,0.5)
路径函数(Path Functions)
basename(path[, ext])
Returns the basename of path
, (optionally) with ext
extension removed.
basename('images/foo.png')
// => "foo.png"
basename('images/foo.png', '.png')
// => "foo"
basename('images/foo.png')
// => "foo.png"
basename('images/foo.png', '.png')
// => "foo"
dirname(path)
Returns the dirname of path
.
dirname('images/foo.png')
// => "images"
dirname('images/foo.png')
// => "images"
extname(path)
Returns the filename extension of path
including the dot.
extname('images/foo.png')
// => ".png"
extname('images/foo.png')
// => ".png"
pathjoin(...)
Peform a path join.
pathjoin('images', 'foo.png')
// => "images/foo.png"
path = 'images/foo.png'
ext = extname(path)
pathjoin(dirname(path), basename(path, ext) + _thumb + ext)
// => 'images/foo_thumb.png'
pathjoin('images', 'foo.png')
// => "images/foo.png"
path = 'images/foo.png'
ext = extname(path)
pathjoin(dirname(path), basename(path, ext) + _thumb + ext)
// => 'images/foo_thumb.png'
集合函数(List / Hash Functions)
push(expr, args...)
将给定的args
压入expr
集合.
nums = 1 2
push(nums, 3, 4, 5)
nums
// => 1 2 3 4 5
nums = 1 2
push(nums, 3, 4, 5)
nums
// => 1 2 3 4 5
别名是 append()
.
pop(expr)
从 expr
中弹出值.
nums = 4 5 3 2 1
num = pop(nums)
nums
// => 4 5 3 2
num
// => 1
nums = 4 5 3 2 1
num = pop(nums)
nums
// => 4 5 3 2
num
// => 1
shift(expr)
Shift an element from expr
.
nums = 4 5 3 2 1
num = shift(nums)
nums
// => 5 3 2 1
num
// => 4
nums = 4 5 3 2 1
num = shift(nums)
nums
// => 5 3 2 1
num
// => 4
unshift(expr, args...)
Unshift the given args
to expr
.
nums = 4 5
unshift(nums, 3, 2, 1)
nums
// => 1 2 3 4 5
nums = 4 5
unshift(nums, 3, 2, 1)
nums
// => 1 2 3 4 5
Aliased as prepend()
.
index(list, value)
Returns the (zero-based) index of value
within a list
.
list = 1 2 3
index(list, 2)
// => 1
index(1px solid red, red)
// => 2
list = 1 2 3
index(list, 2)
// => 1
index(1px solid red, red)
// => 2
keys(pairs)
Return keys in the given pairs
:
pairs = (one 1) (two 2) (three 3)
keys(pairs)
// => one two three
pairs = (one 1) (two 2) (three 3)
keys(pairs)
// => one two three
values(pairs)
Return values in the given pairs
:
pairs = (one 1) (two 2) (three 3)
values(pairs)
// => 1 2 3
pairs = (one 1) (two 2) (three 3)
values(pairs)
// => 1 2 3
list-separator(list)
Return the separator of the given list
.
list1 = a b c
list-separator(list1)
// => ' '
list2 = a, b, c
list-separator(list2)
// => ','
list1 = a b c
list-separator(list1)
// => ' '
list2 = a, b, c
list-separator(list2)
// => ','
length([expr])
Parenthesized expressions may act as tuples, the length()
function returns the length of such expressions.
length((1 2 3 4))
// => 4
length((1 2))
// => 2
length((1))
// => 1
length(())
// => 0
length(1 2 3)
// => 3
length(1)
// => 1
length()
// => 0
length((1 2 3 4))
// => 4
length((1 2))
// => 2
length((1))
// => 1
length(())
// => 0
length(1 2 3)
// => 3
length(1)
// => 1
length()
// => 0
last(expr)
Return the last value in the given expr
:
nums = 1 2 3
last(nums)
last(1 2 3)
// => 3
list = (one 1) (two 2) (three 3)
last(list)
// => (three 3)
nums = 1 2 3
last(nums)
last(1 2 3)
// => 3
list = (one 1) (two 2) (three 3)
last(list)
// => (three 3)
Unit Functions
typeof(node)
Return type of node
as a string.
type(12)
// => 'unit'
typeof(12)
// => 'unit'
typeof(#fff)
// => 'rgba'
type-of(#fff)
// => 'rgba'
type(12)
// => 'unit'
typeof(12)
// => 'unit'
typeof(#fff)
// => 'rgba'
type-of(#fff)
// => 'rgba'
Aliased as type-of
and type
.
unit(val[, type])
Return a string indicating the type of val
or an empty string, or assign the given type
without unit conversion.
unit(10)
// => ''
unit(15in)
// => 'in'
unit(15%, 'px')
// => 15px
unit(15%, px)
// => 15px
unit(10)
// => ''
unit(15in)
// => 'in'
unit(15%, 'px')
// => 15px
unit(15%, px)
// => 15px
percentage(num)
Convert a num
to a percentage.
percentage(.5)
// => 50%
percentage(4 / 100)
// => 4%
percentage(.5)
// => 50%
percentage(4 / 100)
// => 4%
数学函数(Math Functions)
abs(unit)
abs(-5px)
// => 5px
abs(5px)
// => 5px
abs(-5px)
// => 5px
abs(5px)
// => 5px
ceil(unit)
ceil(5.5in)
// => 6in
ceil(5.5in)
// => 6in
floor(unit)
floor(5.6px)
// => 5px
floor(5.6px)
// => 5px
round(unit)
round(5.5px)
// => 6px
round(5.4px)
// => 5px
round(5.5px)
// => 6px
round(5.4px)
// => 5px
Note: All rounding functions can accept optional precision
argument — you can pass the number of digits you want to save after the period:
ceil(5.52px,1)
// => 5.6px
floor(5.57px,1)
// => 5.5px
round(5.52px,1)
// => 5.5px
ceil(5.52px,1)
// => 5.6px
floor(5.57px,1)
// => 5.5px
round(5.52px,1)
// => 5.5px
sin(angle)
Returns the value of sine for the given angle
. If the angle is given as a degree unit, like 45deg
, it is treated as a degree, otherwise it is treated as radians.
sin(30deg)
// => 0.5
sin(3*PI/4)
// => 0.707106781
sin(30deg)
// => 0.5
sin(3*PI/4)
// => 0.707106781
cos(angle)
Returns the value of cosine for the given angle
. If the angle is given as a degree unit, like 45deg
, it is treated as a degree, otherwise it is treated as radians.
cos(180deg)
// => -1
cos(180deg)
// => -1
tan(angle)
Returns the value of tangent for the given angle
. If the angle is given as a degree unit, like 45deg
, it is treated as a degree, otherwise it is treated as radians.
tan(45deg)
// => 1
tan(90deg)
// => Infinity
tan(45deg)
// => 1
tan(90deg)
// => Infinity
min(a, b)
min(1, 5)
// => 1
min(1, 5)
// => 1
max(a, b)
max(1, 5)
// => 5
max(1, 5)
// => 5
even(unit)
even(6px)
// => true
even(6px)
// => true
odd(unit)
odd(5mm)
// => true
odd(5mm)
// => true
sum(nums)
sum(1 2 3)
// => 6
sum(1 2 3)
// => 6
avg(nums)
avg(1 2 3)
// => 2
avg(1 2 3)
// => 2
range(start, stop[, step])
Returns a list of units from start
to stop
(included) by given step
.
The step
argument defaults to 1
if omitted. It cannot be 0
.
range(1, 6)
// equals to `1..6`
// 1 2 3 4 5 6
range(1, 6, 2)
// 1 3 5
range(-6, -1, 2)
// -6 -4 -2
range(1px, 3px, 0.5px)
// 1px 1.5px 2px 2.5px 3px
range(1, 6)
// equals to `1..6`
// 1 2 3 4 5 6
range(1, 6, 2)
// 1 3 5
range(-6, -1, 2)
// -6 -4 -2
range(1px, 3px, 0.5px)
// 1px 1.5px 2px 2.5px 3px
It is most often used in for
loops:
for i in range(10px, 50px, 10)
.col-{i}
width: i
for i in range(10px, 50px, 10)
.col-{i}
width: i
Yields:
.col-10 {
width: 10px;
}
.col-20 {
width: 20px;
}
.col-30 {
width: 30px;
}
.col-40 {
width: 40px;
}
.col-50 {
width: 50px;
}
.col-10 {
width: 10px;
}
.col-20 {
width: 20px;
}
.col-30 {
width: 30px;
}
.col-40 {
width: 40px;
}
.col-50 {
width: 50px;
}
base-convert(num, base, width)
Returns a Literal
num
converted to the provided base
, padded with width
zeroes.
Width defaults to 2
.
base-convert(1, 10, 3)
// => 001
base-convert(14, 16, 1)
// => e
base-convert(42, 2)
// => 101010
base-convert(1, 10, 3)
// => 001
base-convert(14, 16, 1)
// => e
base-convert(42, 2)
// => 101010
字符串函数(String Functions)
match(pattern, string[, flags])
Returns any matches of pattern
(regular expression) in string
.
match('^(height|width)?([<>=]{1,})(.*)', 'height>=1024px')
// => 'height>=1024px' 'height' '>=' '1024px'
match('^foo(?:bar)?', 'foo')
// => 'foo'
match('^foo(?:bar)?', 'foobar')
// => 'foobar'
match('^foo(?:bar)?', 'bar')
// => null
match('ain', 'The rain in SPAIN stays mainly in the plain')
// => 'ain'
match('ain', 'The rain in SPAIN stays mainly in the plain', g)
// => 'ain' 'ain' 'ain'
match('ain', 'The rain in SPAIN stays mainly in the plain', 'gi')
// => 'ain' 'AIN' 'ain' 'ain'
match('^(height|width)?([<>=]{1,})(.*)', 'height>=1024px')
// => 'height>=1024px' 'height' '>=' '1024px'
match('^foo(?:bar)?', 'foo')
// => 'foo'
match('^foo(?:bar)?', 'foobar')
// => 'foobar'
match('^foo(?:bar)?', 'bar')
// => null
match('ain', 'The rain in SPAIN stays mainly in the plain')
// => 'ain'
match('ain', 'The rain in SPAIN stays mainly in the plain', g)
// => 'ain' 'ain' 'ain'
match('ain', 'The rain in SPAIN stays mainly in the plain', 'gi')
// => 'ain' 'AIN' 'ain' 'ain'
replace(pattern, replacement, val)
Return the string val
, after replacing with all pattern
matches with replacement
.
replace(i, e, 'griin')
// => 'green'
replace(i, e, griin)
// => #008000
replace(i, e, 'griin')
// => 'green'
replace(i, e, griin)
// => #008000
join(delim, vals...)
Join the given vals
with delim
.
join(' ', 1 2 3)
// => "1 2 3"
join(',', 1 2 3)
// => "1,2,3"
join(', ', foo bar baz)
// => "foo, bar, baz"
join(', ', foo, bar, baz)
// => "foo, bar, baz"
join(', ', 1 2, 3 4, 5 6)
// => "1 2, 3 4, 5 6"
join(' ', 1 2 3)
// => "1 2 3"
join(',', 1 2 3)
// => "1,2,3"
join(', ', foo bar baz)
// => "foo, bar, baz"
join(', ', foo, bar, baz)
// => "foo, bar, baz"
join(', ', 1 2, 3 4, 5 6)
// => "1 2, 3 4, 5 6"
split(delim, val)
The split()
method splits a string or ident into a list of strings by separating the string into substrings.
split(_, bar1_bar2_bar3)
// => bar1 bar2 bar3
split(_, 'bar1_bar2_bar3')
// => 'bar1' 'bar2' 'bar3'
split(_, bar1_bar2_bar3)
// => bar1 bar2 bar3
split(_, 'bar1_bar2_bar3')
// => 'bar1' 'bar2' 'bar3'
substr(val, start, length)
The substr()
method returns the characters in a string beginning at the specified location through the specified number of characters.
substr(ident, 1, 2)
// => de
substr('string', 1, 2)
// => 'tr'
val = dredd
substr(substr(val, 1), 0, 3)
// => #f00
substr(ident, 1, 2)
// => de
substr('string', 1, 2)
// => 'tr'
val = dredd
substr(substr(val, 1), 0, 3)
// => #f00
slice(val, start[, end])
The slice()
method extracts a section of a string/list and returns a new string/list.
slice('lorem' 'ipsum' 'dolor', 1, 2)
slice('lorem' 'ipsum' 'dolor', 1, -1)
// => 'ipsum'
slice('lorem ipsum', 1, 5)
// => 'orem'
slice(rredd, 1, -1)
// => #f00
slice(1px solid black, 1)
// => solid #000
slice('lorem' 'ipsum' 'dolor', 1, 2)
slice('lorem' 'ipsum' 'dolor', 1, -1)
// => 'ipsum'
slice('lorem ipsum', 1, 5)
// => 'orem'
slice(rredd, 1, -1)
// => #f00
slice(1px solid black, 1)
// => solid #000
unquote(str | ident)
Unquote the given str
, and return it as a Literal
node.
unquote("sans-serif")
// => sans-serif
unquote(sans-serif)
// => sans-serif
unquote('1px / 2px')
// => 1px / 2px
unquote("sans-serif")
// => sans-serif
unquote(sans-serif)
// => sans-serif
unquote('1px / 2px')
// => 1px / 2px
convert(str)
Like unquote()
but tries to convert the given str
to a Stylus node.
unit = convert('40px')
typeof(unit)
// => 'unit'
color = convert('#fff')
typeof(color)
// => 'rgba'
foo = convert('foo')
typeof(foo)
// => 'ident'
unit = convert('40px')
typeof(unit)
// => 'unit'
color = convert('#fff')
typeof(color)
// => 'rgba'
foo = convert('foo')
typeof(foo)
// => 'ident'
s(fmt, ...)
The s()
function is similar to unquote()
, in that it returns a Literal
node. However, it accepts a format string similar to C's sprintf()
.
Currently, the only specifier is %s
.
s('bar()');
// => bar()
s('bar(%s)', 'baz');
// => bar("baz")
s('bar(%s)', baz);
// => bar(baz)
s('bar(%s)', 15px);
// => bar(15px)
s('rgba(%s, %s, %s, 0.5)', 255, 100, 50);
// => rgba(255, 100, 50, 0.5)
s('bar(%Z)', 15px);
// => bar(%Z)
s('bar(%s, %s)', 15px);
// => bar(15px, null)
s('bar()');
// => bar()
s('bar(%s)', 'baz');
// => bar("baz")
s('bar(%s)', baz);
// => bar(baz)
s('bar(%s)', 15px);
// => bar(15px)
s('rgba(%s, %s, %s, 0.5)', 255, 100, 50);
// => rgba(255, 100, 50, 0.5)
s('bar(%Z)', 15px);
// => bar(%Z)
s('bar(%s, %s)', 15px);
// => bar(15px, null)
Check out the %
string operator for equivalent behaviour.
实用函数(Utility Functions)
called-from
property
called-from
property contains the list of the functions the current function was called from in reverse order (the first item is the deepest function).
foo()
bar()
bar()
baz()
baz()
return called-from
foo()
// => bar foo
foo()
bar()
bar()
baz()
baz()
return called-from
foo()
// => bar foo
current-media()
current-media()
function returns the string of the current block's @media
rule (or ''
if there is no @media
above the block).
@media only screen and (min-width: 1024px)
current-media()
// => '@media (only screen and (min-width: (1024px)))'
@media only screen and (min-width: 1024px)
current-media()
// => '@media (only screen and (min-width: (1024px)))'
+cache(keys...)
+cache
is a really powerful built-in function that allows you to create your own “cachable” mixins.
A “cachable mixin” is one that would apply its contents to the given selector on the first call, but would @extend
the first call's selector at the second call with the same params.
size($width, $height = $width)
+cache('w' + $width)
width: $width
+cache('h' + $height)
height: $height
.a
size: 10px 20px
.b
size: 10px 2em
.c
size: 1px 2em
size($width, $height = $width)
+cache('w' + $width)
width: $width
+cache('h' + $height)
height: $height
.a
size: 10px 20px
.b
size: 10px 2em
.c
size: 1px 2em
Would yield to
.a,
.b {
width: 10px;
}
.a {
height: 20px;
}
.b,
.c {
height: 2em;
}
.c {
width: 1px;
}
.a,
.b {
width: 10px;
}
.a {
height: 20px;
}
.b,
.c {
height: 2em;
}
.c {
width: 1px;
}
See how the selectors are grouped together by the used property.
+prefix-classes(prefix)
Stylus comes with a block mixin prefix-classes
that can be used for prefixing the classes inside any given Stylus block. For example:
+prefix-classes('foo-')
.bar
width: 10px
+prefix-classes('foo-')
.bar
width: 10px
Yields:
.foo-bar {
width: 10px;
}
.foo-bar {
width: 10px;
}
lookup(name)
Allows looking up the value of a variable called name
, passed as a string. Returns null
if the variable is undefined.
Useful when you need to get a value of a variable with dynamically generated name:
font-size-1 = 10px
font-size-2 = 20px
font-size-3 = 30px
for i in 1..3
.text-{i}
font-size: lookup('font-size-' + i)
font-size-1 = 10px
font-size-2 = 20px
font-size-3 = 30px
for i in 1..3
.text-{i}
font-size: lookup('font-size-' + i)
Yields:
.text-1 {
font-size: 10px;
}
.text-2 {
font-size: 20px;
}
.text-3 {
font-size: 30px;
}
.text-1 {
font-size: 10px;
}
.text-2 {
font-size: 20px;
}
.text-3 {
font-size: 30px;
}
define(name, expr[, global])
Allows to create or overwrite a variable with a given name
, passed as a string, onto current scope (or global scope if global
is true).
This BIF can be useful in those cases where you need interpolation in variable names:
prefix = 'border'
border = { color: #000, length: 1px, style: solid }
for prop, val in border
define(prefix + '-' + prop, val)
body
border: border-length border-style border-color
prefix = 'border'
border = { color: #000, length: 1px, style: solid }
for prop, val in border
define(prefix + '-' + prop, val)
body
border: border-length border-style border-color
yields:
body {
border: 1px solid #000;
}
body {
border: 1px solid #000;
}
operate(op, left, right)
Perform the given op
on the left
and right
operands:
op = '+'
operate(op, 15, 5)
// => 20
op = '+'
operate(op, 15, 5)
// => 20
selector()
Returns the compiled current selector or &
if called at root level.
.foo
selector()
// => '.foo'
.foo
&:hover
selector()
// '.foo:hover'
.foo
selector()
// => '.foo'
.foo
&:hover
selector()
// '.foo:hover'
selector-exists(selector)
Returns true if selector
exists..
.foo
color red
a
font-size 12px
selector-exists('.foo') // true
selector-exists('.foo a') // true
selector-exists('.foo li') // false
selector-exists('.bar') // false
.foo
color red
a
font-size 12px
selector-exists('.foo') // true
selector-exists('.foo a') // true
selector-exists('.foo li') // false
selector-exists('.bar') // false
This method does not take into account the current context meaning:
.foo
color red
a
font-size 12px
selector-exists('a') // false
selector-exists(selector() + ' a') // true
.foo
color red
a
font-size 12px
selector-exists('a') // false
selector-exists(selector() + ' a') // true
opposite-position(positions)
Return the opposite of the given positions
.
opposite-position(right)
// => left
opposite-position(top left)
// => bottom right
opposite-position('top' 'left')
// => bottom right
opposite-position(right)
// => left
opposite-position(top left)
// => bottom right
opposite-position('top' 'left')
// => bottom right
image-size(path)
Returns the width
and height
of the image found at path
. Lookups are performed in the same manner as @import
, altered by the paths
setting.
width(img)
return image-size(img)[0]
height(img)
return image-size(img)[1]
image-size('tux.png')
// => 405px 250px
image-size('tux.png')[0] == width('tux.png')
// => true
width(img)
return image-size(img)[0]
height(img)
return image-size(img)[1]
image-size('tux.png')
// => 405px 250px
image-size('tux.png')[0] == width('tux.png')
// => true
embedurl(path[, encoding])
Returns an inline image as a url()
literal, encoded with encoding
.
(Available encodings: base64
(default), and utf8
).
background: embedurl('logo.png')
// => background: url("data:image/png;base64,…")
background: embedurl('logo.svg', 'utf8')
// => background: url("data:image/svg+xml;charset=utf-8,…")
background: embedurl('logo.png')
// => background: url("data:image/png;base64,…")
background: embedurl('logo.svg', 'utf8')
// => background: url("data:image/svg+xml;charset=utf-8,…")
add-property(name, expr)
Adds property name
, with the given expr
to the closest block.
For example:
something()
add-property('bar', 1 2 3)
s('bar')
body
foo: something()
something()
add-property('bar', 1 2 3)
s('bar')
body
foo: something()
yields:
body {
bar: 1 2 3;
foo: bar;
}
body {
bar: 1 2 3;
foo: bar;
}
Next, the "magic" current-property
local variable comes into play. This variable is automatically available to function bodies, and contains an expression with the current property's name, and value.
For example, if we were to inspect this local variable using p()
, we get the following:
p(current-property)
// => "foo" (foo __CALL__ bar baz)
p(current-property[0])
// => "foo"
p(current-property[1])
// => foo __CALL__ bar baz
p(current-property)
// => "foo" (foo __CALL__ bar baz)
p(current-property[0])
// => "foo"
p(current-property[1])
// => foo __CALL__ bar baz
Using current-property
we can take our example a bit further, and duplicate the property with new values, and a conditional to ensure the function is only used within a property value.
something(n)
if current-property
add-property(current-property[0], s('-webkit-something(%s)', n))
add-property(current-property[0], s('-moz-something(%s)', n))
s('something(%s)', n)
else
error('something() must be used within a property')
body {
foo: something(15px) bar;
}
something(n)
if current-property
add-property(current-property[0], s('-webkit-something(%s)', n))
add-property(current-property[0], s('-moz-something(%s)', n))
s('something(%s)', n)
else
error('something() must be used within a property')
body {
foo: something(15px) bar;
}
yields:
body {
foo: -webkit-something(15px);
foo: -moz-something(15px);
foo: something(15px) bar;
}
body {
foo: -webkit-something(15px);
foo: -moz-something(15px);
foo: something(15px) bar;
}
If you noticed in the example above, bar
is only present for the initial call, since we returned something(15px)
, it remained in-place within the expression, however the others do not take the rest of the expression into account.
Our more robust solution below defines a function named replace()
which clones the expression to prevent mutation, replaces the string value of an expression with another, and returns the cloned expression. We then move on to replace __CALL__
within the expressions, which represents the cyclic call to something()
.
replace(expr, str, val)
expr = clone(expr)
for e, i in expr
if str == e
expr[i] = val
expr
something(n)
if current-property
val = current-property[1]
webkit = replace(val, '__CALL__', s('-webkit-something(%s)', n))
moz = replace(val, '__CALL__', s('-moz-something(%s)', n))
add-property(current-property[0], webkit)
add-property(current-property[0], moz)
s('something(%s)', n)
else
error('something() must be used within a property')
body
foo: something(5px) bar baz
replace(expr, str, val)
expr = clone(expr)
for e, i in expr
if str == e
expr[i] = val
expr
something(n)
if current-property
val = current-property[1]
webkit = replace(val, '__CALL__', s('-webkit-something(%s)', n))
moz = replace(val, '__CALL__', s('-moz-something(%s)', n))
add-property(current-property[0], webkit)
add-property(current-property[0], moz)
s('something(%s)', n)
else
error('something() must be used within a property')
body
foo: something(5px) bar baz
yields:
body {
foo: -webkit-something(5px) bar baz;
foo: -moz-something(5px) bar baz;
foo: something(5px) bar baz;
}
body {
foo: -webkit-something(5px) bar baz;
foo: -moz-something(5px) bar baz;
foo: something(5px) bar baz;
}
Our implementation is now fully transparent both in regards to the property it is called within, and the position of the call.
This powerful concept aids in transparent vendor support for function calls, such as gradients.
Console Functions
warn(msg)
Warn with the given error msg
. Does not exit.
warn("oh noes!")
warn("oh noes!")
error(msg)
Exit Stylus with the given error msg
.
add(a, b)
unless a is a 'unit' and b is a 'unit'
error('add() expects units')
a + b
add(a, b)
unless a is a 'unit' and b is a 'unit'
error('add() expects units')
a + b
p(expr)
Inspect the given expr
:
fonts = Arial, sans-serif
p('test')
p(123)
p((1 2 3))
p(fonts)
p(#fff)
p(rgba(0,0,0,0.2))
add(a, b)
a + b
p(add)
fonts = Arial, sans-serif
p('test')
p(123)
p((1 2 3))
p(fonts)
p(#fff)
p(rgba(0,0,0,0.2))
add(a, b)
a + b
p(add)
stdout:
inspect: "test"
inspect: 123
inspect: 1 2 3
inspect: Arial, sans-serif
inspect: #fff
inspect: rgba(0,0,0,0.2)
inspect: add(a, b)
inspect: "test"
inspect: 123
inspect: 1 2 3
inspect: Arial, sans-serif
inspect: #fff
inspect: rgba(0,0,0,0.2)
inspect: add(a, b)
External File Functions
json(path[, options])
Convert the JSON file at path
into Stylus variables or an object. Nested variable object keys are joined with a dash (-
).
For example, the following sample media-queries.json
file:
{
"small": "screen and (max-width:400px)",
"tablet": {
"landscape": "screen and (min-width:600px) and (orientation:landscape)",
"portrait": "screen and (min-width:600px) and (orientation:portrait)"
}
}
{
"small": "screen and (max-width:400px)",
"tablet": {
"landscape": "screen and (min-width:600px) and (orientation:landscape)",
"portrait": "screen and (min-width:600px) and (orientation:portrait)"
}
}
May be used in the following ways:
json('media-queries.json')
@media small
// => @media screen and (max-width:400px)
@media tablet-landscape
// => @media screen and (min-width:600px) and (orientation:landscape)
vars = json('vars.json', { hash: true })
body
width: vars.width
vars = json('vars.json', { hash: true, leave-strings: true })
typeof(vars.icon)
// => 'string'
// don't throw an error if the JSON file doesn't exist
optional = json('optional.json', { hash: true, optional: true })
typeof(optional)
// => 'null'
json('media-queries.json')
@media small
// => @media screen and (max-width:400px)
@media tablet-landscape
// => @media screen and (min-width:600px) and (orientation:landscape)
vars = json('vars.json', { hash: true })
body
width: vars.width
vars = json('vars.json', { hash: true, leave-strings: true })
typeof(vars.icon)
// => 'string'
// don't throw an error if the JSON file doesn't exist
optional = json('optional.json', { hash: true, optional: true })
typeof(optional)
// => 'null'
use(path)
You can use any JS-plugin at given path
with use()
function right inside your .styl
files, like this:
use("plugins/add.js")
width add(10, 100)
// => width: 110
use("plugins/add.js")
width add(10, 100)
// => width: 110
And the add.js
plugin in this case looks this way:
var plugin = function(){
return function(style){
style.define('add', function(a, b) {
return a.operate('+', b);
});
};
};
module.exports = plugin;
var plugin = function(){
return function(style){
style.define('add', function(a, b) {
return a.operate('+', b);
});
};
};
module.exports = plugin;
If you'd like to return any Stylus objects like RGBA
, Ident
, or Unit
, you could use the provided Stylus nodes like this:
var plugin = function(){
return function(style){
var nodes = this.nodes;
style.define('something', function() {
return new nodes.Ident('foobar');
});
};
};
module.exports = plugin;
var plugin = function(){
return function(style){
var nodes = this.nodes;
style.define('something', function() {
return new nodes.Ident('foobar');
});
};
};
module.exports = plugin;
You can pass any options as an optional second argument, using a hash object:
use("plugins/add.js", { foo: bar })
use("plugins/add.js", { foo: bar })
Undefined Functions
Undefined functions are output as literals. So, for example, we may call rgba-stop(50%, #fff)
within our css, and it will output as you would expect. We can use this within helpers as well.
In the example below we simply define the function stop()
which returns the literal rgba-stop()
call.
stop(pos, rgba)
rgba-stop(pos, rgba)
stop(50%, orange)
// => rgba-stop(50%, #ffa500)
stop(pos, rgba)
rgba-stop(pos, rgba)
stop(50%, orange)
// => rgba-stop(50%, #ffa500)