マクロについて

マクロの定義

マクロは、複数のタグやテキストをまとめて1つの新しいタグを作る機能です。

マクロの定義には、[marco]タグと[endmacro]タグを使います。

[marco]タグの name 属性の値に、新しく作るタグの名前を指定します。新しく作るタグの名前には半角英数字および全角文字が使用できます。半角記号は含めないことを推奨します。

[marco]タグと[endmacro]タグの間に書かれたタグやテキストが、新しく作るタグの機能となります。

上記サンプルスクリプトでは、[newtag]というタグを定義した後に[newtag]を実行していますので、「青いテキスト」というテキストが青色で表示されます。

属性・値の受け渡し

基本的な受け渡し

通常のタグと同じように、マクロには属性と値の組み合わせを渡すことができます。

マクロ内では、タグの属性の値に "%" から始まる文字列を指定すると、それはマクロに与えられた属性の値に置き換えられて解釈されます。

上記サンプルスクリプトの最下行では、新しく定義した[coloredtext]タグの iro 属性に "0xff0000" という値を指定していますので、マクロ内の[font]タグの color 属性にその値が引き渡されます。結果として、画面上には「色のついたテキスト」というテキストが赤色で表示されることになります。

一括引き渡し

また、"*" を使用すると、マクロに与えられた属性を全て引き渡すこともできます。

上記サンプルスクリプトでは、マクロに渡された color 属性、size 属性、face 属性がそのまま、マクロ内の[font]タグに引き渡されます。

デフォルト値の設定

マクロ中のタグの属性には、デフォルト値を設定することも可能です。

属性の受け渡しの記述の後に、半角パイプ "|" を置くと、その後の文字列がその属性のデフォルト値となります。

上記サンプルスクリプトでは、マクロ中の[font]タグの color 属性に "0x00ff00" というデフォルト値を指定しています。

この場合、マクロに iro 属性が渡された場合はその値が、渡されなかった場合はデフォルト値が[font]タグの color 属性の値となります。

結果として、上記サンプルスクリプトを実行すると、まず「色のついたテキスト」というテキストが赤色で表示され、ついで同文のテキストが緑色で表示されることになります。

なおマクロ中において、デフォルト値の設定されていない属性に値が引き渡されなかった場合には、その属性自体が存在しないものとみなされます。

マクロ変数の利用

マクロの中ではマクロ変数を使うことができます。

これは、属性・値の受け渡しに似た機能ですが、[eval]タグやエンティティを用いることで、マクロに渡された属性や値をより柔軟に取り扱うことができます。

上記サンプルスクリプト内では、マクロが実行されている間、そのマクロの内部からは mp.second 変数を参照することができます。mp.second 変数には、マクロに渡された second 属性の値が格納されています。

上記サンプルスクリプトを実行すると、まず[eval]タグによって、mp.second 変数の値を 1000 倍した数字が tf.millisecond 変数に代入されます。

マクロ内の[wait]タグの time 属性には、tf.millisecond のエンティティが指定されているので、[newtag]マクロの second 属性に指定された値の 1000 倍の数字が指定されることになります。

結果として、上記のサンプルスクリプトを実行すると、その場でコンテンツの再生を 5 秒（5000 ミリ秒）停止するという挙動をします。

なお、マクロ変数は、マクロの実行中以外は参照することができません。