ウィジェット等を組み合わせて作った機能を新しい機能として定義して(作って)簡単に呼び出す(使う)ための機能です
定義したマクロは編集のスタンプアイコン(snippet)に登録しておくといいかもしれません
マクロを定義したTiddlerに「$:/tags/Macro」タグをつけることでそのTiddler以外からも呼び出しができるようになります
その他TWに標準で定義されているCore Macrosも存在します
JavaScriptで定義することも出来ますが、ここでは扱いません
マクロの作り方です
今は作らない場合は呼び出し(Macro Calls in WikiText)まで飛ばしてください
マクロの内容によって書き方に多少幅があります
\define マクロ名()
マクロの本体
\endマクロ名と(は続けて書く必要があります(スペースも入れてはいけません)
\define マクロ名() マクロの本体複数行マクロと異なり\endはつけません
\define マクロ名(引数1, 引数2)
マクロの本体
\end引数の書式は入力がない場合のデフォルト値を指定するなら引数名:デフォルト値、無い場合は引数名です
1行マクロも引数の書き方は同様です
マクロの本体では引数だけでなく呼び出し元で定義された変数(またはマクロ)を使うことができます。また、呼び出し方は2種類あります(後述)
| 書式 | 対象 | 挙動 |
$引数名$ | マクロで定義した引数に渡された値 | 渡された文字列に置換します |
$(変数名)$ | マクロの外で定義された変数やマクロ | 結果の文字列に置換します |
<<_引数名_>> | マクロで定義した引数に渡された値 | 呼び出し |
<<変数名>> | マクロの外で定義された変数やマクロ | 呼び出し |
置換は対象の値や結果に置換した後でマクロの本体が実行されます
つまり、その対象の値や結果が元々そこに書いてあったかのように振舞うということです
これは文字列の結合を簡単に表現できる方法です
例えば前後に文字列を追加した物をマクロやウィジェットに渡す時に便利です
呼び出しは普段の呼び出しと同様です
こちらは置換で問題になる値に含むことの出来ない文字列を回避することができます
例えばマクロやウィジェットに値として"$name$"のように渡した場合、nameの値に"が含まれていた場合に機能しません
置換の必要性がなければ呼び出しの方を使う方が文字の制限を受けずに済んでいいかもしれません
呼び出し方は2種類あります
<<マクロ名>>
<<マクロ名 引数名1:値1 引数名2:値2>>
<<マクロ名 引数1の値 引数2の値>>マクロに定義された引数の順番通りに値を書くことで3行目のように引数名を省略できます
引数名を指定する方法には順番を無視できる他に1個ずれてたみたいなミスを防げるメリットがあります
マクロによってはこの些細なミスで長時間悩む場合もあるかも？
また、変数も1行目と同様の書き方で呼び出されます<<currentTiddler>>とか、SetWidgetやVarsWidgetなどで設定した変数とか
<$macrocall $name="マクロ名" 引数名=値/>通常の呼び出しで使う書式の上位版です
通常の呼び出しではうまくいかない時でもこちらで呼び出すとうまくいく場合があるかもしれません
引数には値を直接渡す以外にもTextReferenceやマクロやフィルターの結果等を渡すこともできます
マクロを渡したい場合はマクロコールウィジェットを使います
気になったら読む程度で問題ないです。Core Macrosまで飛ばして構いません
マクロ名には使えない文字があります。(は定義する際には使えません>は通常の呼び出しを行う際には使えません
なので()<>の4文字は使わない方が良いです
実は日本語は使えますが、ずっと使えるかは分からないのでアルファベットを使う方が確実でしょうか
なお、>はマクロコールウィジェットを利用すれば今のところ使えます
使うべきではないでしょうが
引数名はアルファベットの大文字と小文字、数字、-、_のみが使えます
日本語は使えません
引数同士の区切りとして,やスペースや改行等を使うことができます
また、デフォルト値を指定するときの:の前後にもスペース等の空白文字を入れることが出来るようです
値は以下のように書けます(デフォルト値も同様です)
| 例 | 値に含むことの出来ない文字列 |
"""値""" | """ |
"値" | " |
'値' | ' |
[[値]] | ] |
値 | "と'とスペースや改行 |
TWに標準で用意されているマクロから一部を簡単に紹介
基本的に公式の各TiddlerのParametersがマクロの引数の順番になっている
| tabs Macro | フィルターで指定したTiddlerをタブで切り替え可能な形式で表示する(タブブラウザのように) タブに縦と横のパターンがある |
| Table-of-Contents Macros | タグを利用してツリーっぽい表示を作って表示したりtabsマクロの用にできる いわゆる目次でtocと略して表記されたりする 引数のsortを"all[tiddlers]任意のオペレーター"とすることでタグ抜きでの利用も可能 例えば "all[tiddlers]prefix[SystemTag]"ただ、タグ抜きだと階層化はされない(多分) toc-tabbed-internal-navマクロやtoc-tabbed-external-navマクロは個人的におすすめ |
| tree Macro | Tiddlerタイトルの/を区切り文字に見立てて階層化して表示します 百聞は一見にしかず |
| tag Macro | 指定したタグを表示できる クリックすると指定のタグがついたTiddlerの一覧を表示 各Tiddlerの本文の上に表示されている物と同じ |
| now Macro | 指定した形式で日時を表示できる ただし表示されるのはこのマクロが表示された瞬間の物で、時計の代わりにはならない ウィジェット等に渡して使うことがある |
| timeline Macro | サイドバーの最近の更新(Recent)に表示されている更新履歴と同じ物を表示できる subfilterに"任意のオペレーター"とすることで対象のTiddlerを絞り込める 標準ではシステムTiddlerは対象外なので必要ならばsubfilterで含めるようにする |
今のところToCマクロのsortとtimelineマクロのsubfilterはマクロ内では$引数名$でフィルター内部に埋め込まれて(置換で)利用されているので元のフィルターを無視した運用ができる
| qualify Macro | (渡した文字列)-(currentTiddler依存(？)のユニークな数字)を返す マクロを作る時にマクロの本体中にどこかのフィールドに入力を行う場合に便利 普通に作ると同じフィールドに書き込まれてしまうため、複数箇所で使うには同時に使わないようにするか呼び出しで毎度書き込み先を指定することになるが、qualifyマクロを使うとその手間が省ける ただし、同じTiddlerで二度以上使う場合は指定も必要になる(同じ数字が付与されるので) |