Migrating to Pug v2

Pug v2は2016年8月にリリースされました。 将来のリリースで改善していくためには、いくつかのAPIやドキュメント化されていない機能を 廃止したり、廃止するかどうかを検討する必要がありました。 出来る限り廃止しない方法を探りましたが、それらの変更の多くはコンソールエラーが発生していました。

このページでは最新のPugに対応するための変換方法を記載します。

プロジェクト名変更

Pug v2のリリース以降、商標の問題によりプロジェクト名が、「Jade」から「Pug」に変更されました。 これにより拡張子も.jadeから.pugに変更されました。 .jadeは引き続き利用可能ですが、いずれ廃止されます。 すぐに.pugに変更することをお勧めします。

廃止された機能

廃止された機能のほとんどは公式lintのpug-lintで検出可能です。

Mixin呼び出し

//- old

mixin foo('whatever')

//- new

+foo('whatever')

mixinの宣言と呼び出しを区別しやすくするため、 呼び出し時の構文を変更しました。

属性補完

//- old

a(href='#{link}')

a(href='before#{link}after')

//- new

a(href=link)

//- (Node.js/io.js ≥ 1.0.0の場合)
a(href=`before${link}after`) 
//- (どれでも可)
a(href='before' + link + 'after')

実装が必要以上に複雑だったため、属性補完機能を廃止しました。 JavaScriptの値を使うことが出来るという点も、分かりにくい要因の一つでした。
属性構文の詳細は変数挿入を参照してください。

eachのプレフィックス

//- old

- each a in b
  = a

- for a in b
  = a

//- new

each a in b
  = a

for a in b
  = a

eachはJavaScript構文ではありません。 そのため、JavaScriptの中でeach文を使うと、(実装面で)分かりにくくなってしまいます。 同じことが括弧無しfor文にも言えます。
単純に先頭の-を削除すれば動作します。

廃止されたAPI

以下のプロパティとコンパイルオプションが廃止されました。 これらのAPIが使われていないことを確認してください。

プロパティ

doctype

以前、jade.doctypeオブジェクト(ドキュメント化されていません)にdoctypeショートカットが含まれていました。 このオブジェクトは、拡張してショートカットの追加・変更をすることができました。
Pug v2ではこのオブジェクトを分離して、doctypeパッケージに含めました。 doctypeショートカットを追加するには、codeGenプラグインを使う必要があります。

nodes

以前、jade.nodesオブジェクト(ドキュメント化されていません)には、 「Jadeの抽象構文木(もちろんドキュメント化されていません)のノード」のコンストラクタとして機能するクラスが含まれていました。
Pug v2では、AST(抽象構文木)ノードのtypeプロパティを使ってダックタイピングするのをやめました。

selfClosing

以前、jade.selfClosing配列(ドキュメント化されていません)では、配列を拡張して自己終了タグの動作を変更することができました。
Pug v2ではこの配列を分離して、void-elementsパッケージに含めました。 この配列を変更するには、codeGenプラグインを使う必要があります。

utils

以前、jade.utilsオブジェクト(ドキュメント化されていません)には、 テンプレートエンジンのための、便利な3つの関数が含まれていました。
utils.mergeは使われることが無いので廃止しました。 この機能はES2015のObject.assignを使うことで実現できます。
utils.stringifyはjs-stringifyとして分割し、より一層XSS攻撃から守ることが出来るようになりました。 できる限りこのパッケージを使うことをお勧めします。

Compiler、Lexer、Parser

以前、Jadeの compilerクラス、lexerクラス、parserクラス(ドキュメント化されていません)は、 これらのプロパティからエクスポートされていました。 そして、これらのクラスから派生させた独自のcompiler、lexer、parserを作成することができました。
Pug v2ではコンパイル時のプロセスをカスタマイズ可能にしたので、これらのプロパティを廃止しました。
Pug v2でこれらのクラスの相当するものは、それぞれpug-code-gen、pug-lexer、pug-parserです。互換性はありません。

オプション

compiler、lexer、parser

これらのオプションは廃止されたCompiler、Lexer、Parserで使われていました。

client

clientオプションはclient関数をコンパイルする時に使われていました。 2013年からcompileClientが推奨されるようになり、それ以降、clientを利用すると警告を表示するようになっています。