<APISetup> Part 2/3: Run function and return stack

1. Automate Community
2. Tutorials & Examples

When calling other functions, most programming languages create a return stack with distinct local environments. This flow facilitates that process and allows for multiple helper sub-functions. Instead of calling the functions directly in flow start blocks, we can call the run() function and input the desired function and other variables.

Update: Changed payload interpretation to simple dictionary.

@global run(env, goTo, giveVars, returnTo, takeVars, callerUri, returnToKey = "returnTo")

/** Low cost (2 blocks) transition to another function. Also stores and manages the call and return stack.

@param env (dictionary) :
Environment variable containing "api" and other variables from current environment. The new function will have read-access to all variables but will not be able to edit them directly.

@param goTo (string or dictonary) :
Function name or dictionary with "statement" and optional "flow" keys to run. If only "statement" is given, the "callerUri" flow will be used.

@param giveVars (dictionary) :
New variables and/or new values to set for variables only in the new function's environment. They will not affect variables in current environment.

@param returnTo (string or dictionary) :
Function name or dictionary with "statement" and optional "flow" keys to return to. If only "statement" is given, the "callerUri" flow will be used.

@param takeVars (string or array of strings) :
Variables to transfer from new function's returned environment into current environment. This combination will then be given to the "returnTo" function.

@param callerUri (optional Uri) :
Uri of current fiber to be added to environment on return. Can be used for give/take blocks. Also used to determine default flow number for "goTo" and "returnTo".

@returnToKey (optional string) :
Name of key used by new function in place of "returnTo". If unspecified, the default "returnTo" is used.

Example usages in blocks ("env" is the current environment/payload and fiberUri is the current fiber URI):

Flow URI: env["api"]["run()"]
Payload: {"env" : env, "goTo" : "function()", "giveVars" : {"arg1" : 0, "arg2" : 1}, "returnTo" : {"statement" : 1}, "takeVars" : ["result1", "result2"], "callerUri" : fiberUri, "returnToKey" : "continueUri"}

Flow URI: env["api"]["run()"]
Payload: {"env" : env, "goTo" : {"flow":1, "statement": 1}, "returnTo" : "function()", "takeVars": "result"}

*/