関数

関数とは、特定のタスクを実行する再利用可能なコードのブロックです。そのタスクが必要なときはいつでも、スクリプトの中でその関数を使うことができます。このため、必要なたびにスクリプトにそのタスク用のコードを追加する手間が省けます。また、スクリプト内のコード量を減らすことで、スクリプトをすっきりと整理することができます。

関数では以下のようなことができます。

  • スクリプトからデータを受け取り、それを何らかの方法で操作し、その結果をスクリプトに返す。
  • アクションまたは一連のアクションを実行し、結果のデータをスクリプトに渡す。

一部の関数は、スクリプトで使用するためにStudioに組み込まれています。組み込み関数を利用する場合、スクリプトで特に指定する必要はありません。使いたいときに呼び出すだけです。

スニペットで使用するカスタム関数を独自に作成することもできます。これは、スクリプト内で頻繁に使用するコードがある場合に便利です。必要なたびにスクリプトに追加するのではなく、そのコードを含む関数を作成することができます。すると、そのコードが必要になったときにいつでもその関数を呼び出すことができます。

関数の使用例をダウンロードしてStudioにインポートすることができます。

構文

関数名の最後には開括弧と閉括弧があります：functionName()。

括弧内のテキストはすべてパラメーターで、関数とスクリプトの間で渡されるデータを定義します：functionName(param1,param2)。

カスタム関数を作成するには、次の構文を使用します。

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

構文の内容は次のとおりです。

  • FUNCTIONは、すべてのカスタム関数ステートメントを開始する必須のキーワードです。
  • <name>は関数の名前です。
  • ([<parameter>] [...])は、関数が必要とするパラメーターを定義します。
  • { ... }には関数のコードが含まれています。
  • [RETURN <data>]は、関数からメインスクリプトにデータを渡すために含めるステートメントです。

カスタム関数には任意の名前を付けられますが、以下のガイドラインに従う必要があります。

  • 英数字（a-z, A-Z, 0-9）を使用できます。

  • 名前の最初の文字はアルファベットでなければなりません。
  • 名前の任意の場所に、アンダースコア文字（_）とドル記号（$）を使用できます。
  • 予約語や組み込み関数の名前は使用しないでください。

RETURNステートメントの構文は次のとおりです。

RETURNまたはRETURN <var>

関数を呼び出す場合、以下のいずれかの構文を使用します。

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

パラメーターと引数

多くの関数はスクリプトからのデータを使用する必要があります。これはパラメーターと引数を使って行うことができます。

パラメーターは、関数の作成時に定義します。パラメーターとは、関数名に続く括弧の中に指定される変数名です。1つの関数に複数のパラメーターを持たせることができます。各パラメーターはカンマで区切ります。必要であればスペースを入れることもできますが、必須ではありません。例えば、関数logn(value, base)には、valueとbaseという2つのパラメーターがあります。

スクリプトがパラメーターを介して関数に渡す特定のデータを引数と呼びます。次の例では、スニペットで組み込み関数abs(value)を使用しています。この例では、-42が、valueパラメーターに渡される引数です。

ASSIGN abVal = abs(-42)

Studioでは、すべてのパラメーターが必須です。関数がパラメーター付きで定義されている場合、その関数を呼び出すときに値を渡す必要があります。関数に渡される引数の数は、定義されたパラメーターの数と一致しなければなりません。

スクリプトは、引数の型やフォーマットが正しいかどうかをチェックしません。しかし、引数が関数が必要とする型やフォーマットでない場合、関数が正常に完了しなかったり、結果が正確でなくなる可能性はあります。

関数に渡される引数が多すぎたり少なすぎたりすると、スクリプトの実行時にコンパイルエラーが発生します。この現象は組み込み関数とカスタム関数で発生します。

引数のフォーマット設定

パラメーターを必要とする関数を呼び出す場合は、関数に渡す引数を含める必要があります。引数のフォーマット設定については、以下のガイドラインに従ってください。

  • 引数が数値や変数の場合、一重引用符や二重引用符で囲む必要はありません。
  • 引数が変数の場合、中括弧で囲む必要はありません。
  • 引数が英数字であり変数ではない場合、一重引用符または二重引用符で囲みます。

例えば、関数dateadd()には、unit、date、valueという3つのパラメーターがあります。

Unit は、年や月など、この関数で変更したい日付の部分を定義します。Date は、変更する元の日付です。そしてvalue は、元の日付の指定した単位を関数でどれだけ増やすかを示します。次の例は、各部分のフォーマット設定を示しています。

ASSIGN NewDateYearNumeric = dateadd('year', MyDateTime, 1)

unit は英数字の文字列なので、一重引用符でフォーマットされます。この例のdate は変数なので、引用符はありません。文字列の日付を渡した場合、引用符が必要になります。value は数値なのでフォーマットされていません。

RETURNステートメント

RETURNステートメントは関数を終了させ、スクリプトに制御を戻します。また、スクリプトにデータを戻すこともできます。

RETURNステートメントは、データを変数値か配列としてのみスクリプトに渡すことができます。配列やオブジェクトの一部でない限り、複数の値を渡すことはできません。オブジェクトを最初にJSONに変換しない限り、オブジェクトを渡すことはできません。必要であれば、スクリプト内でオブジェクトに変換し直すことができます。

RETURNステートメントの構文は次のとおりです。

RETURNまたはRETURN <var>

スクリプトに値を返すすべての組み込み関数には、RETURNステートメントが含まれています。ユーザーが作成したカスタム関数では、RETURNステートメントはオプションです。RETURNステートメントがない場合、関数はスクリプトに値を返すことができません。RETURNステートメントを持たない関数を使用する唯一の方法は、これをステートメントのように呼び出すことです。

関数にRETURNステートメントを含める場合、これは関数の最後の行でなければなりません。

可変のビジビリティ

デフォルトの動作では、関数内のすべての値が利用可能であり、これらは関数内でのみ使用可能となります。関数が終了すると、関数内のすべての値は失われます。変数値をスクリプトに戻すRETURNステートメントが関数に含まれている場合、RETURNステートメントを介して渡された値のみが関数の外部で使用可能となります。

メインスクリプトに存在する変数をカスタム関数に含めると、それらの変数はグローバルスコープを持ちます。つまり、これらの値はRETURNステートメントを使用しなくても関数の外で使用できます。同様に、関数内で変数をグローバルとして宣言すると、その値をメインスクリプトで使用できます。これはサブスクリプトの動作と似ています。

式の中で関数を使用する場合、または変数の値として関数を使用する場合は、デフォルトの動作をします。しかし、関数をステートメントとして呼び出すと、関数内のすべての値がグローバルスコープを持ち、関数の外でも使用できるようになります。RETURNのない関数については、これが唯一の使用方法となります。

カスタム関数を作成する

スクリプトの複数の場所で使用したいコードがある場合、カスタム関数を作成できます。カスタム関数は、それを作成したスクリプト内でのみ使用できます。カスタム関数を別のスクリプトで使用する場合は、関数定義コードをそのスクリプトにコピーする必要があります。

スクリプト内の1つのSnippetアクションで関数を作成し、同じスクリプト内の他のSnippetアクションからその関数を呼び出すことができます。関数定義を含むスニペットをデバッグすると、関数がデバッグに含まれます。しかし、他のスニペットをデバッグする際には、この関数は含まれません。

カスタム関数を宣言する構文は次のとおりです。

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

FUNCTIONはキーワードで、この後にカスタム関数が続くことをスクリプトに知らせます。関数名は、スクリプトのその他のエンティティと同じ命名ガイドラインに従わなければなりません。

  • 英数字（a-z, A-Z, 0-9）を使用できます。

  • 名前の最初の文字はアルファベットでなければなりません。
  • 名前の任意の場所に、アンダースコア文字（_）とドル記号（$）を使用できます。
  • 予約語や組み込み関数の名前は使用しないでください。

関数にパラメーターが必要な場合は、関数名の末尾の括弧内に含めます。パラメーターがない場合、括弧内を空白のままにできます。複数のパラメーターはカンマで区切ります。

関数を構成するコードは中括弧の中に指定します。中括弧の位置は自由です。これらは、FUNCTIONキーワードや名前と同じ行に書くことも、別々の行に書くこともできます。例えば、次の2つはどちらも有効な関数定義です。

FUNCTION myFunction() { ASSIGN var = "value" } 
FUNCTION myFunction() 
{ 
	ASSIGN var = "value"
}

その関数にRETURNステートメントが含まれる場合、閉じ中括弧の前の最後のステートメントでなければなりません。

 

関数は文字列を取らず、引用符なしでも、引用符がなく数値やブール値でない場合は変数と仮定します。

関数の作成についての詳細は、宣言ステートメントページを参照してください。

カスタム関数のオートコンプリートヘルプ

カスタム関数用のオートコンプリートヘルプを追加できます。これは、Snippet editorウィンドウで関数名を入力し始めるとポップアップ表示されるツールチップテキストです。このヘルプが表示されるのは、ドット表記で関数を呼び出す場合のみです。

IntelliPromptヘルプが表示されたスニペットエディターウィンドウのテキストビュータブの例。

これらのツールヒントを使用して、関数についての有益な情報を提供することができます。例えば、ヒントを参考に関数のパラメーターを定義できます。

オートコンプリートヘルプを追加するには、関数宣言と同じ行にコメントを追加します。例えば、前の画像に示したツールチップを作成する場合、関数宣言は次のようになります。

FUNCTION MyAppend(a,b) // My function to append the text
{
   RETURN "{a}{b}"
}

関数にオートコンプリートヘルプを追加する場合、関数のコードを含む中括弧は関数定義とは別の行に配置する必要があります。スクリプトは、2つの前方スラッシュ以降のすべてのテキストをコメントの一部と見なします。中括弧が同じ行にある場合、スクリプトはそれらをコメントの一部として処理します。

スクリプトで関数を呼び出す

スクリプトの中で関数を使用するには、その関数を呼び出す必要があります。関数を呼び出すには3つの方法があります。すべてのオプションをすべての関数で使用できるわけではありません。特定の関数で使用できるオプションは、その関数が値を返すかどうかによって決まります。関数を呼び出す方法は以下のとおりです。

  • 単独でステートメントのように呼び出す。このオプションはすべての関数で使用できます。
  • 変数や式を使う場所で呼び出す。このオプションは、値を返す関数でのみ機能します。
  • ドット表記法で変数を指定して呼び出す。このオプションは、値を返す関数でのみ機能します。

関数をステートメントのように呼び出す

ステートメントとは、スクリプトに何をすべきかを指示するコマンドキーワードを持つコード行のことです。関数をステートメントとして使用できます。その際、スニペット内の他のステートメントのように、特別なコマンドキーワードは必要ありません。関数内のコードは、スクリプトに何をすべきかを指示します。

すべての関数はステートメントとして呼び出すことができます。関数にRETURNが含まれない場合、これが唯一の使用方法です。これは、RETURNステートメントが、関数からスクリプトにデータを戻すからです。RETURNがない場合、スクリプトが関数内のデータにアクセスするには、関数をステートメントとして呼び出す以外に方法はありません。

関数をステートメントとして呼び出すための構文は次のとおりです。

<functionName><([parameter], [parameter], [...])>

次の例では、append()関数をステートメントのように呼び出しています。

IF TEST = 1
{
  ASSIGN originalString = "My name"
  ASSIGN originalString2 = "Whose pajamas are these? "
  ASSIGN appendWithEscape = $"They're the cat's pajamas."			
}
originalString.append(" is Inigo Montoya.")
originalString2.append(AppendWithEscape)

関数を変数の代わりに使用する

関数が値を返す場合、変数や式の場合と同じようにどこでもその値を使うことができます。スクリプトは、関数が返す値を、変数の値や式の結果と同じように使うことができます。

関数を変数の代わりに使用するための構文は次のとおりです。

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

関数の結果を変数に代入したい場合は、ASSIGNステートメントの一部として関数を呼び出すことができます。例えば、 ASSIGN var = otherVar.function() 。しかし、これが不可能なケースが1つあります。それは、GetRESTproxy()関数のメンバー関数を呼び出す場合です。

次の例は、値を返す関数の使い方を示しています。関数の例は次のとおりです：

FUNCTION replaceCharacters(string)
{
	ASSIGN adjustedString = string.replace("&", "and")
	RETURN adjustedString
}

この関数は、アンパサンド文字（&）をandという単語に置き換えます。次の例では、stringRes変数の文字列値の変数の代わりに関数replaceCharacters()を使用しています。このコードが実行されると、stringResの値はMy favorite animals are dogs and cats.に更新されます。

ASSIGN testString = "dogs & cats"
ASSIGN stringRes = "My favorite animals are {replaceCharacters(testString)}."

ドット表記で関数を使う

関数が値を返す場合、ドット表記を使って変数と一緒に使うことができます。これは、次のように関数を変数にアタッチします：variable.function()。この方法で関数を呼び出すと、変数の値が関数に渡されます。このオプションは、値を返す関数でのみ機能します。

関数でドット表記を使用するための構文は次のとおりです。

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

次の例はこの方法を示しています。関数は次のとおりです：

FUNCTION MyAppend(a,b)
{
   RETURN "{a}{b}"
}

次は関数MyAppendを変数phで使用するFORループです。

FOR i=1 TO 9
{
   ph = "{ph.MyAppend(i)}"
}

FORループの結果はph="123456789"です。

ドット表記を使って関数を呼び出すと、その関数にアタッチされている変数の値が、最初のパラメーターの引数として関数に渡されます。先の例では、phの初期値が、パラメーターaの引数として関数MyAppend()に渡されます。これが、関数定義に2つのパラメーターがあるにも関わらず、関数呼び出しには引数が1つしか含まれていない理由です。iの初期値は、パラメーターbの引数として関数に渡されます。

ドット表記で関数を呼び出す利点は、関数のツールチップヘルプを追加できることです。