コマンド内関数(サブルーチン)

長くなったコマンドの中で、同じような処理が何度も出てくることがあります。「コマンド内関数」は、そうした 再利用したい処理のかたまり に名前を付け、引数を受け取って実行する仕組みです。同じノード列をコピーして増やす代わりに、関数を 1 つ作り、必要な場所から 呼び出す ことで同じ結果が得られます。

関数は 同じコマンドの中だけ で再利用できます。別のコマンドからは呼び出せないため、コマンドをまたいだ共通処理ではなく、1 つのコマンドの内部整理に向いています。細部を関数に追い出せば、コマンド本体には流れの骨格(条件分岐や順序)だけが残り、引数で対象ユーザーやメッセージ本文を呼び出しごとに切り替えられます。

サイドバーの「関数」セクション

コマンドビルダーの左サイドバーには、「グループ」「変数」などと並んで { } アイコンの関数セクションがあります。ここで、関数の一覧表示・作成・削除・編集対象の切り替えを行います。

ボタン / 表示	内容
「新しい関数を追加」	空の関数を 1 つ作り、関数本体の編集画面に切り替えます。
「コマンド本体に戻る」	関数を編集している間だけ表示される、コマンド本体に戻るボタンです。
関数の一覧	作成済みの関数が、引数の個数と戻り値の型とあわせて並びます。
「削除」アイコン	その関数を削除します。

関数本体に置かれるノード

新しい関数を作ると、関数本体のキャンバスには起点として 関数定義 と エラーハンドラー の 2 つのノードが最初から置かれます(削除や移動はできません)。関数本体の処理は、関数定義ノードの下に続けてノードをつないで作っていきます。

関数まわりで使うノードは次の 3 種類です。

ノード	置く場所	役割
「関数定義」	関数本体の入口(自動配置)	この関数の名前・引数・戻り値の型を編集します。
「関数呼び出し」	コマンド本体や、別の関数の本体	同じコマンド内に定義した関数を呼び出します。引数を渡し、必要なら戻り値を変数として受け取ります。
「戻り値」(return)	関数本体の中	関数の処理を明示的に終わらせ、戻り値を返します。戻り値の型が `void` の関数では値の入力は不要です。

関数の名前・引数・戻り値を編集する(関数定義ノード)

関数本体の入口にある「関数定義」ノードをクリックすると、右側に設定パネルが開き、その関数のメタ情報をまとめて編集できます。

関数名と説明

項目	内容
「関数名」	同じコマンド内で一意の名前を付けます。英数字・アンダースコア・ハイフンが使えます。
「説明」	サイドバーの一覧や、関数呼び出しの補完で表示される短い説明文(任意)。

引数 (params)

「引数」セクションでは、関数が受け取る入力を 0 個以上 並べて定義します。「追加」ボタンで 1 件追加され、各引数には次を設定します。

項目	内容
「引数名」	小文字英数字・アンダースコア・ハイフン。`param_` で始まる名前は使えません(参照式と重複するため)。
「型」	引数のデータ型。「文字列 (string)」「数値 (number)」「真偽値 (boolean)」「ユーザー (User)」「チャンネル (Channel)」「ロール (Role)」「オブジェクト (Object)」「配列 (Array)」から選びます。
「説明」	関数呼び出し側の補助テキストとして表示される説明(任意)。
「必須」	オンにすると、呼び出し側で値を必ず渡す必要があります。
「デフォルト値」	必須をオフにしたときに表示される、省略時に使われる値(任意)。ユーザー / ロール / チャンネル型は持てません(これらを使うときは必ず必須にしてください)。

関数本体の中では、引数を {param_<引数名>} の形で参照します。たとえば引数名を target にしたら、関数本体のメッセージ本文に {param_target.mention} と書けば、呼び出し時に渡されたユーザーのメンションが入ります。

戻り値 (returns)

関数の戻り値の型を 1 つ選びます。

選択肢	意味
「戻り値なし (void)」(初期値)	値を返しません。関数内の処理を行うだけ。
「文字列 (string)」「数値 (number)」「真偽値 (boolean)」「ユーザー (User)」「チャンネル (Channel)」「ロール (Role)」「オブジェクト (Object)」「配列 (Array)」	この型の値を返します。関数本体の中で「戻り値」ノードを使って値を返し、呼び出し側で受け取ります。

void 以外を選ぶと、呼び出し側で戻り値を変数として受け取れるようになります。

関数を呼び出す(関数呼び出しノード)

コマンド本体や、他の関数の本体から「関数呼び出し」ノードを置くと、同じコマンド内の関数を呼び出せます。キャンバスに置いたノードをクリックすると、右側に設定パネルが開きます。

「呼び出す関数」を選ぶ

ドロップダウンに、このコマンド内に定義した関数が並びます。「（関数を選択）」のまま保存すると呼び出し先が決まらず、その呼び出しは何も実行しません。

引数を入力する

関数を選ぶと、その関数の引数フォームが下に展開されます。値の入力欄では {変数名} の参照や ${ ... } の計算式も使えます。

任意引数(必須オフ)を空欄で送ると、引数のデフォルト値が使われます(関数定義側で設定しておけます)。

戻り値の格納先を指定する(任意)

呼び出し先の関数が戻り値を持つ(void 以外の)ときだけ、「戻り値の格納先 (任意)」欄が表示されます。ここに変数名を入れておくと、戻ってきた値が {その変数名} で参照できます。空欄なら戻り値は破棄されます。

関数の途中で抜ける(戻り値ノード)

関数本体の途中で if 分岐に応じて早めに終わらせたい、または値を明示的に返したいときは「戻り値」ノードを使います。

関数の戻り値型が void のときは、void 用の戻り値ノードを置けば「ここで処理を終了」する目印になります。値の入力は不要です。
void 以外の戻り値型のときは、入力欄に その型に合った値 を入れます。リテラル(直接の値)、{変数} 参照、${...} 計算式が使えます。

「戻り値」ノードは関数の中だけで使ってください。関数本体の外(コマンド本体側)に置くと「このノードは関数本体の外には配置できません。」と表示され、その関数は実行時に正しく動かなくなります。

関数の中で使える変数のスコープ

関数の中では、変数の 見えかた がコマンド本体と少し違います。次のように使い分けてください。

種類	関数の中での扱い	例
永続変数(`BSVAR_…`、サーバー共有のグローバル変数など)	読み書きできます。関数の中で増やしたカウントなどは、関数を抜けた後も残ります。	`{BSVAR_score}`
コマンドのオプション (`option_…`)	関数の中からは見えません。必要なら、呼び出し側で引数として渡してください。	(関数の中では参照できない)
関数の引数 (`param_…`)	関数の中だけで読み取り専用として参照できます。書き換えはできません。	`{param_target}`
関数の中で「変数を設定」したローカル変数	その関数の中だけで有効です。関数を抜けると消えます。	`{tmp}`

エラーハンドラーとの関係

関数本体にも、入口の「関数定義」ノードと並んで「エラーハンドラー」ノードが自動で配置されますが、現時点では関数内エラーは コマンド全体のエラーハンドラー(関数の外側、コマンド本体側にある起点ノード) が受け取ります。関数の中でエラーを返したい場合も、コマンド本体側のエラーハンドラーで処理を組み立ててください。

うまく動かないときは

戻り値ノードに「このノードは関数本体の外には配置できません」と表示される: サイドバーで関数を開いてから、関数本体側に置き直してください。
関数の中で書き換えたつもりの値が、関数を抜けたら消える: 関数の外まで残したい値は、呼び出し側で戻り値として受け取るか、永続変数(BSVAR_…)に書き出してください。

次のステップ / 関連ページ

コマンドビルダーの概要 — 画面構成とノードの基本操作
変数と式の使い方 — {変数名} 参照や ${ ... } 計算式の書き方
ノードの種類リファレンス — 利用できるノードの早見表
コマンドの基本設定 — コマンド全体の名前・権限・エラー処理

コマンド内関数(サブルーチン)

目次