Stylusのビルトイン関数まとめ

stylus-built-in-functions-color.md

色

red(color[, value])

color の赤成分を返します。第2引数に赤成分を指定すると、合成された値を返します。

red(#c00)
// => 204

red(#000, 255)
// => #f00

green(color[, value])

color の緑成分を返します。第2引数に緑成分を指定すると、合成された値を返します。

green(#0c0)
 // => 204

green(#000, 255)
// => #0f0

blue(color[, value])

color の青成分を返します。第2引数に青成分を指定すると、合成された値を返します。

blue(#00c)
// => 204

blue(#000, 255)
// => #00f

alpha(color[, value])

color の透明度を返します。第2引数に透明度を指定すると、合成された値を返します。

alpha(#fff)
// => 1

alpha(rgba(0,0,0,0.3))
// => 0.3

alpha(#fff, 0.5)
// => rgba(255,255,255,0.5)

dark(color)

色が濃いかどうかを確認します。

dark(black)
// => true

dark(#005716)
// => true

dark(white)
// => false

light(color)

色が明るいかどうかを確認します。

light(black)
// => false

light(white)
// => true

light(#00FF40)
// => true

hue(color[, value])

color の色相を返すか、色相コンポーネントを第2引数に設定します。

hue(hsl(50deg, 100%, 80%))
// => 50deg

hue(#00c, 90deg)
// => #6c0

saturation(color[, value])

color の彩度を返すか、彩度コンポーネントを第2引数に設定します。

saturation(hsl(50deg, 100%, 80%))
// => 100%

saturation(#00c, 50%)
// => #339

lightness(color[, value])

color の明るさを返すか、明るさコンポーネントをオプションの2番目の値引数に設定します。

lightness(hsl(50deg, 100%, 80%))
// => 80%

lightness(#00c, 80%)
// => #99f

hsla(color | h,s,l,a)

HSLAノード、またはh、s、l、コンポーネント値に変換します。

hsla(10deg, 50%, 30%, 0.5)
// => HSLA

hsla(#ffcc00)
// => HSLA

hsl(color | h,s,l)

HSLAノード、またはh、s、l、コンポーネント値に変換します。

hsl(10, 50, 30)
// => HSLA

hsl(#ffcc00)
// => HSLA

rgba(r,g,b,a) rgba(color, alpha)

r、g、b、aチャンネルからRGBAを返すか、アルファを微調整するための色を指定します。

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 と #rrggbbaa 表記もサポートします。

#fc08
// => rgba(255,204,0,0.5)

#ffcc00ee
// => rgba(255,204,0,0.9)

blend(top[, bottom])

通常のブレンドを使用して、指定された top の色を bottom の色に重ねます。 bottom はオプションで、デフォルトは #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)

lighten(color, amount)

色を明るくします。 パーセンテージおよび絶対値（0~100）で指定できます。

lighten(#2c2c2c, 30)
// => #787878

lighten(#2c2c2c, 30%)
// => #393939

darken(color, amount)

色を暗くします。パーセンテージおよび絶対値（0~100）で指定できます。

darken(#D62828, 30)
// => #551010

darken(#D62828, 30%)
// => #961c1c

saturate(color, amount)

彩度を上げます。

saturate(#c33, 40%)
// => #f00

desaturate(color, amount)

彩度を下げます。

desaturate(#f00, 40%)
// => #c33

complement(color)

補色を返します。

complement(#fd0cc7)
// => #0cfd42

invert(color)

色を反転します。 赤、緑、青の値は反転し、不透明度は変わりません。

invert(#d62828)
// => #29d7d7

spin(color, amount)

与えられた色の色相を量で回転させます。

spin(#ff0000, 90deg)
// => #80ff00

mix(color1, color2[, amount])

color1 に amount の分量だけcolor2 を混ぜます。 amount はオプションで、デフォルトは50％です。

mix(#000, #fff, 30%)
// => #b2b2b2

tint(color, amount)

color に amount の分量だけ白を混ぜます。

tint(#fd0cc7,66%)
// => #feaceb

shade(color, amount)

color に amount の分量だけ黒を混ぜます。

shade(#fd0cc7,66%)
// => #560443

luminosity(color)

相対輝度を返します。

luminosity(white)
// => 1

luminosity(#000)
// => 0

luminosity(red)
// => 0.2126

contrast(top[, bottom])

Lea Verouによるスクリプトの基礎となる「コントラスト比」ツールに基づいて、上下の色の間のコントラスト比オブジェクトを返します。

2番目の引数はオプションで、デフォルトは#fffです。

返されるオブジェクトの主なキーはratioです。また、最小値と最大値もあり、下部の色が透明の場合にのみ、比率とは異なります。 その場合、エラーにはエラーマージンも含まれます。

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])

指定された一番上の色の透明バージョンを、指定された一番下の色（または可能な場合はそれに最も近い色）の上にブレンドされたかのように返します。

2番目の引数はオプションで、デフォルトは#fffです。

3番目の引数はオプションで、自動検出されたアルファを上書きします。

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)

stylus-built-in-functions-convert.md

変換

base-convert(num, base, width)

base に指定された進数で、width で指定された桁数まで0で埋めた値を返します。 width のデフォルト値は2です。

base-convert(1, 10, 3)
// => 001

base-convert(14, 16, 1)
// => e

base-convert(42, 2)
// => 101010

match(pattern, string[, flags])

値（ string ）を pattern （正規表現）と照合します。

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)

val に与えられた値の pattern を replacement で置き換えます。

replace(i, e, 'griin')
// => 'green'

replace(i, e, griin)
// => #008000

join(delim, vals...)

指定されたリストを 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"

split(delim, val)

文字列を部分文字列に分割することによって、string /ident を文字列の配列に分割します。

split(_, bar1_bar2_bar3)
// => bar1 bar2 bar3

split(_, 'bar1_bar2_bar3')
// => 'bar1' 'bar2' 'bar3'

substr(val, start, length)

指定された位置から指定された文字数までの文字列を返します。

substr(ident, 1, 2)
// => de

substr('string', 1, 2)
// => 'tr'

val = dredd
substr(substr(val, 1), 0, 3)
// => #f00

slice(val, start[, end])

string / list のセクションを抽出し、新しい string / list を返します。

end にマイナスの値を指定した場合は、最後から○つを除外

slice('lorem' 'ipsum' 'dolor', 1, 2) 
// => 'ipsum

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)

引用符を外して、Literalノードとして返します。

unquote("sans-serif")
// => sans-serif

unquote(sans-serif)
// => sans-serif

unquote('1px / 2px')
// => 1px / 2px

convert(str)

unquote（） と似ていますが、与えられた str を Stylusノードに変換しようとします。

unit = convert('40px')
typeof(unit)
// => 'unit'

color = convert('#fff')
typeof(color)
// => 'rgba'

foo = convert('foo')
typeof(foo)
// => 'ident'

s(fmt, ...)

Literalノードを返すという点で unquote（） と似ていますが、Cの sprintf（） と非常によく似たフォーマット文字列を受け入れます。 現在唯一の指定子は ％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)

stylus-built-in-functions-debug.md

デバッグ

warn(msg)

警告文を出しますが、終了しません。

warn("oh noes!")

error(msg)

警告文を出して終了します。

add(a, b)
  unless a is a 'unit' and b is a 'unit'
    error('add() expects units')
  a + b

p(expr)

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)

 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)

stylus-built-in-functions-list.md

リスト / 配列

push(expr, args…)

args を expr に追加します。

 nums = 1 2
 push(nums, 3, 4, 5)

 nums
 // => 1 2 3 4 5

pop(expr)

expr から最後の値を抜きます。

nums = 4 5 3 2 1
num = pop(nums)

nums
// => 4 5 3 2
num
// => 1

shift(expr)

expr から最初の値を抜きます。

nums = 4 5 3 2 1
num = shift(nums)

nums
// => 5 3 2 1
num
// => 4

unshift(expr, args…)

shift() の逆。エイリアスは prepend()。

nums = 4 5
unshift(nums, 3, 2, 1)

nums
// => 1 2 3 4 5

index(list, value)

リスト内の値のインデックス（ゼロから始まる）を返します。

list = 1 2 3

index(list, 2)
// => 1

index(1px solid red, red)
// => 2

keys(pairs)

与えられた pairs のキーを返します。

pairs = (one 1) (two 2) (three 3)
keys(pairs)
// => one two three

values(pairs)

与えられた pairs の値を返します。

pairs = (one 1) (two 2) (three 3)
values(pairs)
// => 1 2 3

list-separator(list)

リストの区切り文字を返します。

list1 = a b c
list-separator(list1)
// => ' '

list2 = a, b, c
list-separator(list2)
// => ','

last(expr)

与えられたexprの最後の値を返します。

nums = 1 2 3
last(nums)
last(1 2 3)
// => 3

list = (one 1) (two 2) (three 3)
last(list)
// => (three 3)

stylus-built-in-functions-mixin.md

ミックスイン

+cache(keys…)

「キャッシュ可能な」ミックスインを作成できる、強力な組み込み関数です。

「キャッシュ可能なミックスイン」は、最初の呼び出しで指定されたセレクターにその内容を適用しますが、2番目の呼び出しで同じパラメーターを使用して最初の呼び出しのセレクターに @extend します。

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

コンパイル

.a,
.b {
  width: 10px;
}
.a {
  height: 20px;
}
.b,
.c {
  height: 2em;
}
.c {
  width: 1px;
}

+prefix-classes(prefix)

特定のStylusブロック内のクラス名にprefixを付けることができます。

例

+prefix-classes('foo-')
  .bar
    width: 10px

コンパイル

.foo-bar {
  width: 10px;
}

stylus-built-in-functions-number.md

単位 / 数値

unit(unit[, type])

与えられた値の単位を返します。第2引数に単位を与えると、与えられた値をその単位に変えて返します。

unit(10)
// => ''

unit(15in)
// => 'in'

unit(15%, 'px')
// => 15px

unit(15%, px)
// => 15px

percentage(num)

パーセンテージに変換します。

percentage(.5)
// => 50%

percentage(4 / 100)
// => 4%

abs(unit)

絶対値を返します。

abs(-5px)
// => 5px

abs(5px)
// => 5px

ceil(init[, digit])

切り上げ。第2引数で桁数を指定できます。

ceil(5.5in)
// => 6in

ceil(5.52px,1)
// => 5.6px

floor(init[, digit])

切り捨て。第2引数で桁数を指定できます。

floor(5.6px)
// => 5px

floor(5.57px,1)
// => 5.5px

round(init[, digit])

四捨五入。第2引数で桁数を指定できます。

round(5.5px)
// => 6px

round(5.4px)
// => 5px

round(5.52px,1)
// => 5.5px

sin(angle)

与えられた角度に対するサインの値を返します。角度が 45deg など、度の単位として指定されている場合は角度として扱われ、それ以外の場合はラジアンとして扱われます。

sin(30deg)
// => 0.5

sin(3*PI/4)
// => 0.707106781

cos(angle)

与えられた角度に対するコサインの値を返します。角度が 45deg など、度の単位として指定されている場合は角度として扱われ、それ以外の場合はラジアンとして扱われます。

cos(180deg)
// => -1

tan(angle)

与えられた角度に対するタンジェントの値を返します。角度が 45deg など、度の単位として指定されている場合は角度として扱われ、それ以外の場合はラジアンとして扱われます。

tan(45deg)
// => 1

tan(90deg)
// => Infinity

min(a, b)

a , b のうち小さい方を返します。

min(1, 5)
// => 1

max(a, b)

a , b のうち大きい方を返します。

max(1, 5)
// => 5

even(unit)

偶数かどうか調べます。

even(6px)
// => true

odd(unit)

奇数かどうか調べます。

odd(5mm)
// => true

sum(nums)

合計を返します。

sum(1 2 3)
// => 6

avg(nums)

平均を返します。

avg(1 2 3)
// => 2

range(start, stop[, step])

与えられた step による開始から終了までの（含まれている）単位のリストを返します。 step のデフォルトの1で、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

for ループでよく使われます。

for i in range(10px, 50px, 10)
  .col-{i}
    width: i

コンパイル後

.col-10 {
  width: 10px;
}
.col-20 {
  width: 20px;
}
.col-30 {
  width: 30px;
}
.col-40 {
  width: 40px;
}
.col-50 {
  width: 50px;
}

stylus-built-in-functions-path.md

パス / ファイル名

basename(path[, ext])

path の拡張子を削除して返します。

basename('images/foo.png')
// => "foo.png"

basename('images/foo.png', '.png')
// => "foo"

dirname(path)

path のディレクトリ名を返します。

dirname('images/foo.png')
// => "images"

extname(path)

path の拡張子をドットを含めて返します。

extname('images/foo.png')
// => ".png"

pathjoin(…)

パスを結合します。

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'

stylus-built-in-functions-type.md

型

typeof(node)

型を文字列で返します。エイリアスは typeof() と type() です。

型の種類は unit, string, ident, object, rgba, boolean

type(12)
// => 'unit'

typeof(12)
// => 'unit'

typeof(#fff)
// => 'rgba'

type-of(#fff)
// => 'rgba'

stylus-built-in-functions-undefined.md

未定義の関数はリテラルとして出力されるので、たとえば、CSS内で rgba-stop（50％、#fff） を呼び出しても期待どおりに出力されます。 これをヘルパー内でも使用できます。

以下の例では、リテラルの rgba-stop（） 呼び出しを返す関数 stop（） を定義するだけです。

stop(pos, rgba)
  rgba-stop(pos, rgba)

stop(50%, orange)
// => rgba-stop(50%, #ffa500)

stylus-built-in-functions-utility.md

ユーティリティ

called-from プロパティ

現在の関数が逆の順序で呼び出された関数のリストが含まれます（最初の項目は最も深い関数です）。

foo()
  bar()

bar()
  baz()

baz()
  return called-from

foo()
// => bar foo

current-media()

現在のブロックの @media 規則の文字列を返します。ブロックの上に @media がない場合は ''を返します。

@media only screen and (min-width: 1024px)
  current-media()
// => '@media (only screen and (min-width: (1024px)))'

## called-from プロパティ

現在の関数が逆の順序で呼び出された関数のリストが含まれます（最初の項目は最も深い関数です）。

foo()
  bar()

bar()
  baz()

baz()
  return called-from

foo()
// => bar foo

current-media()

現在のブロックの @media 規則の文字列を返します。ブロックの上に @media がない場合は ''を返します。

@media only screen and (min-width: 1024px)
  current-media()
// => '@media (only screen and (min-width: (1024px)))'

lookup(name)

文字列として渡された name の名前をもつ変数が定義されていれば値を返します。変数が未定義の場合は null を返します。

動的に生成された名前を持つ変数の値を取得する必要があるときに便利です。

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)

.text-1 {
  font-size: 10px;
}
.text-2 {
  font-size: 20px;
}
.text-3 {
  font-size: 30px;
}

define(name, expr[, global])

文字列として渡された、name の名前をもつ変数を現在のスコープ（またはglobalがtrueの場合はグローバルスコープ）に作成または上書きすることを許可します。

このbifは、変数名を補間したい場合に便利です。

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

body {
  border: 1px solid #000;
}

operate(op, left, right)

オペランドを実行します。

op = '+'
operate(op, 15, 5)
// => 20

length([expr])

括弧で囲まれた式はタプルとして振る舞うかもしれません、そのような式の長さを返します。

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

selector()

コンパイルされた現在のセレクタ、またはルートレベルで呼び出された場合は & を返します。

.foo
  selector()
// => '.foo'

.foo
  &:hover
    selector()
// '.foo:hover'

selector-exists(selector)

セレクタが存在するか調べます。

.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('a') // false
  selector-exists(selector() + ' a') // true

opposite-position(positions)

positions の反対を返します。

 opposite-position(right)
 // => left

 opposite-position(top left)
 // => bottom right

 opposite-position('top' 'left')
 // => bottom right

image-size(path)

path の画像の width と height を返します。

pathで見つかった画像の幅と高さを返します。 参照は @import と同じ方法で実行され、パス設定によって変更されます。

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])

インライン画像を url（） リテラル（base64, 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,…")

add-property(name, expr)

よくわからない

json(path[, options])

JSONファイルをStylus変数またはオブジェクトに変換します。 ネストした可変オブジェクトキーはダッシュ（ - ）で結合します。

たとえば、次のサンプル media-queries.json ファイル

{
    "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)"
    }
}

次のように使用されます。

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)

'.styl'ファイルの中で use（） 関数を使用して、任意のjsプラグインを任意のパスで使用できます。

use("plugins/add.js")

width add(10, 100)
// => width: 110

この場合のadd.jsプラグインは次のようになります。

var plugin = function(){
  return function(style){
    style.define('add', function(a, b) {
      return a.operate('+', b);
    });
  };
};
module.exports = plugin;

RGBA、Ident、UnitなどのStylusオブジェクトを返したい場合は、提供されているStylusノードを次のように使用します。

var plugin = function(){
  return function(style){
    var nodes = this.nodes;
    style.define('something', function() {
      return new nodes.Ident('foobar');
    });
  };
};
module.exports = plugin;

ハッシュオブジェクトを使用して、任意のオプションをオプションの2番目の引数として渡すことができます。

use("plugins/add.js", { foo: bar })