パラメータと結果
メッセージは、メッセージ名という単語で識別されますが、_パラメータ_の形で追加情報を含めることもできます。パラメータは、コマンドや関数に渡される値です。これらのコマンドや関数はカスタムハンドラであり、呼び出しスクリプト内に存在するか、別のスクリプトやヘルパースイート内に存在することがあります。ハンドラの宣言やパラメータの受け取りについての詳細は、ハンドラをご覧ください。
パラメータの2つの渡し方：シーケンシャルと名前付き
コマンドや関数を呼び出すときにパラメータを渡す方法は2つあります：シーケンシャル（順序通り）と名前付きです。シーケンシャルパラメータは、想像通りの順序で渡されます。名前付きパラメータは、_key:value_のペアのプロパティリストとして渡され、各キーが受け取り側のパラメータの名前と一致するように使用されま す。これら2つのパラメータの渡し方は組み合わせることもできます。
呼び出しコマンドや関数は、呼び出されるハンドラと同じスクリプト内にあることも、異なるスクリプト内にあることもあります。呼び出しは多くの場合、別のスクリプト内にあり、これはテストのモジュラ化に有用です。テスト構造には、様々なタスクを実行する多種多様なハンドラを含む他のスクリプトへのいくつかの異なる呼び出しを含むプライマリスクリプトが含まれることがあります。
受け取りハンドラが期待する任意のパラメータにデフォルト値を事前に定義することに興味がある場合は、デフォルトのパラメータ値を参照してください。パラメータを受け取るハンドラの作成については、ハンドラを参照してください。
シーケンシャルパラメータ
シーケンシャルパラメータの渡し方
シーケンシャルパラメータを渡すためには、コマンド名の後にパラメータ値を列挙し、コンマで区切るか、関数を呼び出すときに関数名の後の括弧内に含めます（単一のパラメータ値が渡されるときの関数の他のバリエーションもあります - 関数の呼び出しを参照）。
コマンド put "Hello, World!"は、"Hello, World!"という文字列を単一のパラメータとしてputメッセージと共に送信します。複数のパラメータを送信するには、それらをコンマで区切って列挙します。
例：コマンドでシーケンシャルパラメータを渡す
この例では、数値31、テキストgreen、変数styleの3つのパラメータをシーケンシャルパラメータとしてdoSomethingImportantコマンドに渡します：
doSomethingImportant 31, "green", style
コマンドのパラメータは括弧で囲むべきではありません（単一のパラメータとしてリストを渡す意図がある場合を除く）。
例：関数でシーケンシャルパラメータを渡す
関数呼び出しメッセージにパラメータを含めるには、関数名の後の括弧内にそれらを列挙します：
put roundToNearest(salary/12, 0.01) into monthlyPayTothePenny
例：空のパラメータを供給する
2つのコンマが連続すると空のパラメータを意味し、リストの最後のコンマは無視されるので、次の例では3つのパラメータ（"silverBar"、""、16）が渡されます：
get verifyQuantity("silverBar",,16,)
シーケンシャルパラメータの割り当て
パラメータが順序に従って渡されると、その値はハンドラ宣言の一部であるパラメータ変数に（同じ順序で）割り当てられます。呼び出し元がパラメータ変数の数よりも少ない値を渡すと、割り当てられなかったものはそのデフォルト値（または空）を受け取ります。呼び出し元がより多くの値を渡す場合、ハンドラはそれらにparameterList関数、paramCount関数、param関数を使用してアクセ スできます。
例：
例えば、以下のように宣言されたcastSpellハンドラを考えてみましょう。
to castSpell spellName, duration, potency -- "to"を使って、この行はcastSpellハンドラを宣言し、3つのパラメータ変数を定義します
//魔法を唱えるためのことをします：
Put duration and potency into Cauldron
Stir Cauldron -- 魔法を実行するカスタムコール
Log "Alakazam!: " & spellName -- 魔法が唱えられたことを確認するメッセージ
end castSpell
ここで、spellName、duration、potencyは、ハンドラが呼び出されたときに渡されるパラメータの値を受け取るパラメータ変数です。
上記のハンドラがコマンドcastSpell "sleep", 12 hours, "deep"を使って呼び出された場合、スクリプト全体は以下のようになるでしょう。
castSpell "sleep", 12 hours, "deep" --これは呼び出しコマンドで、3つのパラメータを順序に従って渡します
to castSpell spellName, duration, potency --順序に従って渡されたパラメータは、受け取られてその順序に従って対応するパラメータ変数に挿入されます
//魔法を唱えるためのことをします：
Put duration and potency into Cauldron
Stir Cauldron -- 魔法を実行するカスタムコール
Log "Alakazam!: " & spellName -- 魔法が唱えられたことを確認するメッセージ
end castSpell
この場合、値"sleep"はパラメータ変数spellNameに、値12時間はdurationに、"deep"はpotency変数に割り当てられます。
同じハンドラがコマンドcastSpell "sleep"を使用して呼び出されたと仮定します：
castSpell "sleep"
to castSpell spellName, duration, potency
//魔法を唱えるための操作をします！
TypeText "Alakazam!"
end castSpell
この場合、一つだけのパラメータ値が提供されています。 値"sleep"は以前と同じようにパラメータ変数castSpellに割り当てられますが、durationとpotency変数に対する値が与えられていないため、それらはデフォルト値（または、この場合、ハンドラがデフォルト値を定義していないので、empty）に初期化されます。
また、ハンドラはパラメータ変数よりも多いパラメータ値で呼び出されることもあります：
castSpell "sleep", 12 hours, "deep", stardust
to castSpell spellName, duration, potency
//魔法を唱えるための操作をします！
TypeText "Alakazam!"
end castSpell
この場合、最初の3つの値は通常通り3つのパラメータ変数に割り当てられます。追加の値、stardustは任意の変数に割り当てられませんが、ハンドラ内でparam関数を使用してparam(4)として利用可能です。 呼び出し元によって渡された順序パラメータの値の数は、paramCount関数を使用して取得可能で、この場合は4を返します。 そして、渡された順序パラメータの全リストはparameterListとして利用可能です。
呼び出されたハンドラは、楕円または三つのピリオド（...）を使用して、任意の数のパラメー タを明示的に受け入れることもできます。この受け入れ方についての詳細は、可変数のパラメータの受け入れを参照してください。
名前付きパラメータ
名前付きパラメータの渡し方
パラメータを渡す第二の方法は、名前で渡す です。名前でパラメータを渡すためには、プロパティリスト（または_key:value_のペアのシーケンス）を使用し、その後にby nameという単語を使います。ハンドラは、適切な値を受け取るようにプロパティ変数で設定する必要があります。
最終的に渡されるパラメータがプロパティリストや_key:value_のペアのシー ケンスでない場合、by nameを使用しても効果はありません。
例:
これらの例はすべて、プロパティリストとして同じパラメータを渡すさまざまな方法を示しています。これはコマンドと関数の両方に対して行います。
プロパティリストを名前でコマンドに渡すさまざまな方法：
orderItem aPropertyList by name
orderItem {id:a, size:b, color:c} by name
orderItem id:a, size:b, color:c by name
プロパティリストを名前で関数に渡すさまざまな方法：
put itemInformation({id:a, size:b, color:c} by name)
put itemInformation(id:a, size:b, color:c by name)
名前付きパラメータの割り当て
名前で渡される任意の値は、同じ名前を持つパラメータ変数に割り当てられます。名前付きパラメータを渡すためには、唯一のパラメータとしてプロパティリストを渡し、その後にby nameという単語を追加します。プロパティリストパラメータ（または_key:value_ペアのシーケンス）がby nameで渡されると、呼び出されたハンドラ内の各パラメータ変数には、変数と同じ名前を持つプロパティリスト内のプロパティの値が割り当てられます。
名前で渡された値の完全なセットは、呼び出されたハンドラ内でparametersByName関数を使用して取得できます。
例: プロパティリストを名前で渡す
この例では、spellName変数にはプロパティリストのspellNameプロパティの値が割り当てられ、durationプロパティの値はdurationパラメータ変数に割り当てられ、以下同様です。もしプロパティリストがパラメータ変数の一つに対応するプロパティ名を持っていない場合、その変数は割り当てられたデフォルト値（またはデフォルト値がない場合は空）から始まります。
set deepSleep to {spellName:"sleep", potency:"deep"} -- これはプロパティリストを変数に格納します
castSpell deepSleep by name -- castSpellハンドラを呼び出し、単一のプロパティリストを渡します。'by name'キーワードは、プロパティリストの値がプロパティキーと一致するパラメータ変数に割り当てられるようにします
to castSpell spellName, duration, potency -- 名前で渡されたパラメータは受け取られ、それらの値は対応するパラメータ変数に挿入されます
//呪文を唱えるための処理：
Put duration and potency into Cauldron
Stir Cauldron
Log "Alakazam!: " & spellName
end castSpell
名前で渡されるプロパティリストは、式の結果であることもあります。例えば、このコマンドはdeepSleepプロパティリストのプロパティにdurationプロパティを追加し、その結果のプロパティを名前で渡します：
castSpell deepSleep adding {duration: 1 hr} by name
もちろん、プロパティリストは呼び出し行で直接指定することもできます：
castSpell {spellName:"sleep", potency:"deep", duration:15 minutes} by name
または、このようにブレースを省略することもできます：
castSpell duration:15 minutes, spellName:"sleep", potency:"deep" by name
連続的なパラメータと名前付きパラメータの両方
ハンドラへのパラメータの渡し方として、連続的なパラメータと名前付きパラメータの組み合わせを使うことも可能です。これを行うには、まず連続的なパラメータを指定し、その後に名前付きパラメータとby nameを続けます：
castSpell "sleep", potency:"deep" by name
この場合、最初のパラメータである"sleep"は名前がついていないため、連続的に渡され、したがって最初のパラメータ変数spellNameに割り当てられます。これに続いてby nameで渡されるプロパティリストがあり、プロパティ名potencyがpotencyパラメータ変数にマッチし、その値に"deep"が割り当てられます。
パラメータの数
SenseTalkでは、コマンドや関数が呼び出されると、渡されたまたは期待されるパラメータの数に関係なく、その名前のカスタムハンドラや組み込みのコマンドや関数を呼び出します。渡されるパラメータの数が呼び出されるハンドラが期待する数と一致しない場合、その差をさまざまな方法で処理することがあります：例外がスローされるか、余分な値が無視されるか、供給されなかったパラメータに対してデフォルトの値が想定されるかもしれません。呼び出されたハンドラは、受け取ったものを適切に処理してランタイムで応答します。詳細は、渡されたパラメータの受け取りを参照してください。
リストをパラメータとして渡す
個々のパラメータを渡す代わりに、as parametersを指定してリストに含まれるすべての値を渡すことができます。これにより、リストは単一のエンティティとしてではなく、リスト内の値が個々に渡されます：
put [candles, 6, blue] into thingsToBeUpdated
updateAllItems thingsToBeUpdated as parameters -- これにより、3つのパラメータが渡されます：変数candles、数値6、変数blue。
"as parameters"を省略すると、リスト全体が一つのパラメータとして渡されます。
これは、現在のハンドラが受け取ったパラメータのリストをそのまま渡す場合に特に便利です：
return otherFunction(parameterList() as parameters)
プロパティリストをパラメータとして
便宜上、最後または唯一のパラメータがプロパティリストの場合、中括弧（curly braces）を省略することができます。これらの形式のいずれかが使用されると、個々のプロパティがすべて単一のプロパティリストとしてまとめて渡されます。
例：
これらの例はどちらも同じことをします。唯一の違いは、2番目のパラメータとして渡されるプロパティリストの中括弧を省略するかどうかです。
addAtPosition 23, {item:"paper", quantity:500, color:"White"} -- 最初に渡されるパラメータは23で、2番目のパラメータはプロパティリストです。
addAtPosition 23, item:"paper", quantity:500, color:"White" -- 最初に渡されるパラメータは23で、2番目のパラメータはプロパティリストです。
例：
addToInventory item:"candles", quantity:6,color:"Blue"-- 呼び出されたハンドラにプロパティリストを単一のパラメータとして渡します。
set article to fetchClipping(author:"Lewis", title:"Lost")-- 単一のパラメータとして呼び出し関数にプロパティリストを渡します。
プロパティリストは、名前によるパラメータの渡し方にも使用できます。パラメータが名前で渡されると、呼び出されたハンドラ内で利用可能となり、プロパティキー、または「名前」によって参照できます。名前によるパラメータの渡し方について詳しくは、Two Ways to Pass Parameters: Sequential and Namedをご覧ください。
コンテナとして渡されるパラメータ（参照による）
ハンドラが呼び出しスクリプト内の一つまたはそれ以上の値を変更できると便利な場合があります。SenseTalkでは、 これは呼び出しスクリプトがそれを許可した場合、すなわち一つ以上のパラメータを「参照によって」または「コンテナとして」渡すことでのみ行うことができます（詳細はReferences to Containersを参照してください）。これを示すために、非常に単純なコマンドハンドラで2つの値を交換するものをここに示します：
on swapValues a,b
put a into temp
put b into a
put temp into b
end swapValues
通常の方法で呼び出されると、このコマ ンドは呼び出しスクリプトには影響を与えません：
swapValues x,y -- このコマンドはxとyを変更しません
ただし、呼び出しスクリプトが明示的にそのパラメータをコンテナとして渡すと、その値は変更できます：
swapValues container x, container y -- これはxとyの値を交換します
Syntax:
container aContainer
{a} reference {to} aContainer
refer to aContainer
@ aContainer
結果の返却
関数ハンドラは呼び出しスクリプトに値を返します。これは関数呼び出し表現の値として使われます。関数ハンドラが明示的に値を返さない場合、その返り値は単純に空になります。通常、関ために関数を持つ理由は、値を提供するためですので、関数ハンドラはほとんどの場合で return ステートメントで終了します。return ステートメントには、返すべき値（式であるかもしれません）を一つ含める必要があります。必要であれば、リストとして複数の値を返すことができます。ここにその例を示します：
return [min(source), max(source), average(source)]
パラメータと結果を操作するためのコマンドと関数
Params 宣言
動作: スクリプトの初期ハンドラのいくつかの名前付き入力パラメータを宣言します。params 宣言はスクリプトの最初のステートメントでなければなりません。それは入力パラメータに名前を付けます。パラメータは、以下で説明するように、param、paramcount、および params 関数を使用しても引き続きアクセスできます。
Syntax:
params paramName1 {, paramName2 ...}
例:
params width,height
Param 関数
動作: パラメータリスト内でその序数位置によって指定された、現在のハンドラに順序付けられて渡されたパラメータの一つの値を返します。ハンドラは宣言したパラメータの数に関係なく、任意の数の入力順序パラメータを受け取ることができます。param 関数は、ハンドラ内からその値を取得するために使用することができます。
重要: この関数は順序パラメータの値のみを返します。詳細は Two Ways to Pass: Sequential and Named Parameters を参照してください。
Syntax:
the params
params()
例:
get the param of 1-- 最初のパラメータを取得する
put param(0)-- ハンドラ名を表示する
例:
//水やりの日程を定義するリスト
put ["2020-09-06","2020-09-08","2020-09-10","2020-09-11","2020-09-14","2020-09-16"] into WateringDateList
Repeat with each item of WateringDateList
If it = Today
WaterThePlants Today, 2020 -- この二つ目のパラメータは余計で、必ずしも呼び出されるハンドラによって期待されるわけではない
end if
End repeat
to WaterThePlants Date -- この行は渡されたパラメータをキャッチするための変数を1つだけ宣言しています。今日の日付がこのDateパラメータ変数に追加されます。
// 植物に水をやるための処理をする
--Click "WateringButton"
log "Watering completed on " & Date -- 水やりが完了したこと、およびパラメータとして渡された日付をログに記録する
// 追加の変数をチェックする、最大で5つまで:
repeat with each [2,3,4,5]
if param(it) does not equal empty then put "Parameter " & it & " is: " ¶m(it) -- もしパラメータが2-5の位置のいずれかに渡されていたら、その値を実行ウィンドウに表示します。この場合、 「Parameter 2 is: 2020」と表示します。
end repeat
end WaterThePlants
ParamCount Function
動作: 現在のハンドラーに渡された連続したパラメータの数を返します。
重要: この関数は、連続したパラメータの値のみを返します。詳細については、Two Ways to Pass: Sequential and Named Parametersをご覧ください。
Syntax:
the paramCount
paramCount()
例:
repeat with n=1 to the paramCount
put "Parameter " & n & " is " & param(n)
end repeat
Params Function
動作: ハンドラ名と現在のハンドラに渡されたすべてのパラメータの値を含むテキスト文字列を返します。パラメータの値はリストとプロパティリストを除いてそれぞれが引用符で囲まれています。
構文:
parametersByNameによる
parametersByName()
例:
put the params -- Might show: test "John Doe","27",("JD","Bud")
ParameterList Function
動作: 現在のハンドラに渡されたすべての連続したパラメータを含むリストを返します。これは、paramCountとparam関数を使用するよりも、渡されたパラメータを操作する便利な方法かもしれません。連続パラメータについての詳細は、Sequential Parametersを参照してください。
Syntax:
the parameterList
parameterList()
例:
repeat with each item of the parameterList
add it to total
end repeat
return func(the parameterList as parameters)
-- pass our params to func
ParametersByName Function
動作: 呼び出されたハンドラ内から使用すると、parametersByName関数は、マッチングする変数名がなかったため、またはその変数の値が連続したパラメータによって与えられたために、任意のパラメータ変数に割り当てられなかった値を含む、フルプロパティリストを渡します。この関数は、渡されたパラメータと受け取り側の期待との間のミスアライメントを特定するのに役立ちます。
構文:
the result
result()
例:
castSpell {spellName:"sleep", potency:"deep", duration: 12 hours} by name
castSpellに対して spellName, duration, potency
put the parametersByName -- ハンドラに渡されたプロパティリスト全体にアクセスし、Runウィンドウに表示します
end castSpell
例:
//水やりの日付リストを定義する
put ["2020-09-06","2020-09-08","2020-09-10","2020-09-12","2020-09-14","2020-09-16"] into WateringDateList
WateringDateListの各項目を繰り返し
If it = Today
WaterThePlants {Date: Today, extra: 2020} by name -- この2番目のパラメータは余分であり、呼び出されるハンドラによって必ずしも期待されているわけではありません
end if
End repeat
to WaterThePlants Today -- この行には、パスされたパラメータをキャッチするための変数が1つだけ宣言されています
// 植物に水をやるための処理
Click "WateringButton"
// 受け取ったすべてのパラメータを出力します：
put parametersByName() -- parametersByName関数を使用して、パラメータの完全なリストにアクセスします。"{Date:"2020-09-06", extra:2020}"を出力します
end WaterThePlants
Return コマンド
動作: 関数ハンドラ内で使用されると、関数の結果を返します。メッセージハンドラで使用されると、the resultを設定します。
構文:
return {expression}
例:
return pi*diameter
関連:
Result 関数
動作: 前のコマンドによって設定された結果（ある場合）を返します。例えば、ファイルに作用するほとんどのコマンドは、成功するとthe resultを空に設定し、失敗すると何が間違ったのかを示すメッセージに設定します。
構文： {the} param of numExpr
param( numExpr )
例:
if the result is not empty then throw "Error", the result
各文の始めに、the resultは前の文によって生成された結果に設定されます。したがって、操作の結果を決定するためには、次に実行される文の一部としてこの関数を呼び出す必要があります。
return文がコマンド（関数ではなく）として呼び出されたハンドラーの一部として実行されると、返り値はそれを呼び出したスクリプトのthe resultを設定します。
次のコマンドは、一部の条件下でthe resultを空でないものに設定します：answer、ask、convert、copy、create、delete、move、open、post、read、rename、replace、seek、shell。また、ファイルやURLにアクセスする際にも設定されます。前のコマンドが成功したかどうかを判断するための結果のテストでは、結果が特定の単語を探すのではなく、結果が空であるかどうかをチェックするのが一般的です。なぜなら、エラーメッセージの正確な表現が将来のリリースで変更される可能性があるからです。
the throwExceptionResultsのグローバルプロパティがtrueに設定されている場合、コマンドがthe resultを例外オブジェクトに設定すると（これはほとんどのエラー状況で発生します）、その例外は上記のようにこの関数を介して利用可能になるのではなく、例外がスローされます。
非空の結果が設定されると、その結果はthe resultHistoryグローバルプロパティに挿入されます。これにより、スクリプトは以前のステートメントから結果値を取得することが可能になります。ただし、空の値は含まれないため、結果を特定のステートメントにマッチさせる際には注意が必要です。the resultHistoryLimitグローバルプロパティに指定された数の結果が保持され、この制限に達すると古い結果が破棄されます。
返される値が例外オブジェクト（オブジェクトタイプが"exception"のプロパティリスト）の場合、the throwExceptionResultsグローバルプロパティがTrueに設定されていると、呼び出し元はその例外をスローします。
関連: