macaroni

when

Description:
The when executor is used to conditionally execute a list of executors, depending if condition is true or false, as part of a multi-turn dialog.

Parent: dialog

Value:

• when: sequence of (condition), required, specifying a set of conditions
• execute: sequence of (executor), required, specifying a set of executors to be run, one by one, if conditions are true
• expect: sequence of (trigger), optional, specifying a set of triggers to add to parent command when this branch of dialog is executed
• unexpected: string (retry, cancel, ignore), sequence of executors, or mapping of phrase and/or command, optional, specifying dialog policy for unexpected responses

# key/value compact form
- when:
  - (condition1, required)
  - (condition2, optional)
  - ...
  execute:
  - (executor1, required)
  - (executor2, optional)
  - ...
  expected:
  - (trigger1, optional)
  - (trigger2, optional)
  - ...
  unexpected:
  - (executor1, required)
  - (executor2, optional)
  - ...

# key/value compact example
- when:
  - missing: '{temperature}'
  execute:
  - speak: What temperature?

EXAMPLE

commands:

- triggers:
  - '{device} {#temperature} [degrees]'
  - '[{temp-verb}] [the] {device} [of the car]'
  - '[{temp-verb}] [the] {device} [of the car] (up | down)'
  - '{temp-verb} [the] {device} [of the car] [to] {#temperature} [degrees]'
  - '{temp-verb} [the] {device} [of the car] (up | down) [to] {#temperature} [degrees]'
  - "I'm [{anything}] {temp-statement}"
  - "it's [{anything}] {temp-statement} [in here]"
  - "Make it {temp-statement} [in here]"
  # it's cold in here

  execute:

  - dialog:

    - when:
      - required: '{temp-statement}'
      - missing: '{#temperature}'
      execute:
      - speak: What temperature would you like it to be?
      expect:
      - '[{anything}] {#temperature} [degrees]'
      unexpected:
        phrase:
        - speak: Didn't understand; What temperature, as a number between 60 and 90.
        command:
        - speak: OK. Now, What temperature would you like the cabin to be?

    - when: [ missing: '{#temperature}' ]
      execute:
      - speak: to what temperature?
      expect:
      - '{#temperature} [degrees]'
      - '{temp-verb} [it] [to] {#temperature} [degrees]'
      unexpected:
        phrase: retry
        command:
        - speak: What temperature would you like it to be?

    - when: [ condition: '{#temperature} < 60' ]
      execute:
      - speak: minimum is 60
      expect:
      - '[ok] {#temperature} [degrees]'
      - '{temp-verb} [it] [to] {#temperature} [degrees]'
      unexpected:
      - speak: What temperature would you like it to be?

    - when: [ condition: '{#temperature} > 90' ]
      execute:
      - speak: maximum is 90
      expect:
      - '[ok] {#temperature} [degrees]'
      - '{temp-verb} [it] [to] {#temperature} [degrees]'
      unexpected:
      - speak: What temperature would you like it to be?

  - speak: 'OK, setting the temperature to {#temperature} degrees'
  - broadcast:
      name: CarControl.SetTemperature
      value: '{#temperature}'

Additional information:

• unexpected has many forms; it can be split by phrase and command, or specified directly and applied to both phrase and command unexpected inputs
• for any of those three (unexpected, phrase or command), the value can be:
  • string, specyfing retry, cancel, or ignore, or
  • sequence of executors
• for each when branch of the dialog, if no expectation was left, the dialog will be consdidered complete, and executors following the dialog executor will continue
• otherwise, the expectations will be added to the parent command, and the dialog will be considered “open”/”not completed”
• on each subsequent command execution (regardless of it it’s part of a multi-turn dialog or not):
  • at the beginning of the potentially unexpected command, all open/non-complete dialogs will be checked; if marked as cancel:
    • the command will be canceled
    • the command’s dialog context will be destroyed
    • executors following the dialog executor will NOT be executed
  • at the end of the potentially unexpected command
    • all open/non-complete dialogs will be searched
    • the most recent open/non-complete dialog will be selected from that list that was marked retry or specified a sequence of executors
    • for that most recent open/non-complete dialog marked retry or w/ executors
      • if marked retry, that most recent command will be re-triggered, with trigger.type set to unexpected.command
      • if w/ executors, the list of specified unexpected executors will be executed
• on each unrecognized/unmatched phrase (no matching command was found via pattern matching or intent):
  • all open/non-complete dialogs will be checked; if marked as cancel, the command will be marked complete, and all context will be destroyed
  • then, all open/non-complete dialogs will be searched
  • the most recent open/non-complete dialog will be selected from that list that was marked retry or specified a sequence of executors
  • for that most recent open/non-complete dialog marked retry or w/ executors
    • if marked retry, the command will be re-triggered, with trigger.type set to unexpected.phrase
    • if w/ executors, the list of specified unexpected executors will be executed

Status: ✅ IMPLEMENTED