How are the methods goto, execute and transfer different?

SWML offers a lot of flexibility in how you control program flow with it's control methods. Of these, goto, execute, and transfer allow you to unconditionally control program flow.

goto

The goto method is designed to allow you to jump to particular labels within a section. Use this method to simulate more complex loops like while and for loops.

you can not jump to sections using goto.

Use execute described further below to jump sections.

version: 1.0.0
sections:
  main:
    - play: say:Entering infinite loop
    - label: loop
    - play: say:Looping ...
    - goto: loop

execute

The execute method allows you to invoke a subsection as a function. You can pass parameters to the function and receive a return value.

YAML

version: 1.0.0
sections:
  main:
    - play: say:Transferring you to another section
    - execute: subsection
    - play: "say: %{return_value}"

  subsection:
    - play: say:inside a subsection
    - return: "back!"

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "play": "say:Transferring you to another section"
      },
      {
        "execute": "subsection"
      },
      {
        "play": "say: %{return_value}"
      }
    ],
    "subsection": [
      {
        "play": "say:inside a subsection"
      },
      {
        "return": "back!"
      }
    ]
  }
}

Output transcript:

"Transferring you to another section"
"inside a subsection"
"back!"

Or in a more complex example:

YAML

version: 1.0.0
sections:
  main:
    - play: say:Transferring you to another section
    - execute:
        dest: subsection
        params:
          a: 1
          b: 2
    - play: "say: %{return_value}"

  subsection:
    - return: "%{params.a+params.b}"

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "play": "say:Transferring you to another section"
      },
      {
        "execute": {
          "dest": "subsection",
          "params": {
            "a": 1,
            "b": 2
          }
        }
      },
      {
        "play": "say: %{return_value}"
      }
    ],
    "subsection": [
      {
        "return": "%{params.a+params.b}"
      }
    ]
  }
}

transfer

YAML

version: 1.0.0
sections:
  main:
    - play: say:Transferring you to another section
    - transfer: subsection
    - play: "say:Back!"

  subsection:
    - play: say:inside a subsection

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "play": "say:Transferring you to another section"
      },
      {
        "transfer": "subsection"
      },
      {
        "play": "say:Back!"
      }
    ],
    "subsection": [
      {
        "play": "say:inside a subsection"
      }
    ]
  }
}

Output transcript:

"Transferring you to another section"
"inside a subsection"

info

Notice how we aren't going back to the calling section at all.

Conclusion

	goto	execute	transfer
Use	Jump between labels within a section	Invoke a subsection with params, then return	Invoke a subsection with params
Scope	within a section	From one section to another, or to another SWML file	From one section to another, or to another SWML file