Actions are debugged by placing Debug statements in your actions. When a Debug statement is executed it conditionally displays the debug panel describing various content. You have complete control over what content is displayed at runtime. You can also display any custom information that you wish by placing it in the Debug statement's prompt field. You can also automatically open the action positioned to the statement which caused the debug panel to be displayed.
Debugging can also be entered by placing a breakpoint on a statement in an action Action Editor window. At runtime when the statement is encountered, the debug panel will be displayed. Breakpoints are set, cleared and toggled from the context menu's Breakpoints submenu. You can also toggle a breakpoint on a single statement by double clicking in the line number column.
Debug statements are always processed. Breakpoints are only processed if they are enabled.
Breakpoints are automatically enabled when an action is run from an action editor window. They are also automatically enabled by the Actions>Debug>Pause Running Action menu item, (or equivalent toolbar item or keyboard shortcut), which is used to break into an executing action. Breakpoints can be enabled manually in a debug panel. You can cause breakpoints to always be enabled via the The Actions >Debug menu.
When an action is executing, you can break in and commence debugging by selecting the Actions>Debug>Pause Running Action menu item (or toolbar item). This method is useful when you want to debug an action which is running and has not encountered a Debug statement or breakpoint. Perhaps the action is looping and you want to see where it is. Note that it may take a while to display the debug panel as debugging commences with the next action statement to be executed. This method can even be used while a prompt is displayed.
The debug panel's configuration panel has an Auto display statement in action setting. When enabled, the action containing the statement which caused the debug panel to be opened, will automatically be displayed with the statement selected. Note: the displayed action is a copy of what is executing. Making changes to the action can cause subsequent displays to be positioned incorrectly. This setting is initially enabled.
The debug panel allows you to cancel or continue execution. It also always displays four states. Each of these states display as green when enabled and red when disabled. You can toggle a state by clicking on the red or green icon. The following states are displayed:
When you close the debug panel via the Continue button, execution will proceed until the next Debug statement or breakpoint (idf enabled) is encountered.
The debug panel also allows you to exit by stepping to a subsequent statement at which time the debug panel will again be displayed.
There are four types of stepping:
When an action editor window is displayed while an action is running, you can modify breakpoints by the window's context menu (or keyboard shortcuts). The action displayed when debugging is a copy. You can modify breakpoints if the content of the action editor window has not been modified. If the content has been changed, you will not be able to modify breakpoints. If a breakpoint is modified while an action is running, the edited action window will immediately be saved. Basically, if you want to debug an action by setting or clearing breakpoints at runtime, do not change its content.
Changes to breakpoints while an action is running cannot be undone via the Edit>Undo mechanism (⌘Z).
You cannot place a breakpoint on any of the following statements:
Note that a breakpoint can be placed on a Start statement. As documented, executing a Start statement is equivalent to executing an Exit statement. When a Start statement causes a break (via stepping or a breakpoint), it is displayed as Implicit Exit. Important: A breakpoint on a Start statement will not be encountered if the associated action is run ... only if the previous action falls into it.
The implicit exits state exists because Yate only executes statements and does not typically detect an action about to exit by falling out of a non inline action or by executing a Start statement. While both of these scenarios are equivalent to an Exit statement, they are handled differently.
1: Debug 2: Repeat Forever loop 3: 4: Start loop
In the rather silly code above, the debug panel will be displayed when statement 1 is executed. If you step, statement 2 will be displayed. If you then step the action will loop forever without displaying the debug panel again. This is because there effectively is no statement being executed. If you do an Actions>Debug>Pause Running Action, the debug panel will be displayed. The action will be positioned to the Start statement and the call stack will display an Implicit exit statement. When Actions>Debug>Pause Running Action is executed, implicit exits are automatically enabled.
When implicit exits are enabled, falling out of an action or executing a Start statement will break. This means that you can always set and catch the exit, explicit or implicit, from an action. Note that a breakpoint on a Start statement is honoured even if implicit exits are not enabled.
Note: if you are falling through the end of an action file to exit, you cannot place a breakpoint to catch the exit. In this case, if you want to break before an action exits, place an Exit statement at the end and place a breakpoint on it.
You can quickly remove all breakpoints via the Breakpoints>Remove All Breakpoints context menu item.
Stepping works by the interpreter knowing where it is at any given time and by analyzing the call stack. The call stack as displayed in the debug panel, will show which calls have an active step out or step out grouped.
Step out grouped (⇑) is the most problematic step mode as it is not entirely based on popping the stack but also the change of the file being processed. In order to be effective Step out grouped (⇑) must be set when in the first action called grouped. An action which was run grouped by an action already running grouped, has no subsequent file.
Executing a Step out (↑) will change an active Step out grouped (⇑) and vice versa. If you get tired of breaking on each file, execute a Step out (↑).
Step over (⤵︎) is implemented as a Step (➔) followed by a Step out (↑) when appropriate. Stepping over a Test & Run statement will always break on the statement executed when the Test & Run exits.
Debug statements which meet the requirements are always displayed. You can't skip an active Debug statement (or an active breakpoint). You also cannot cancel an active Step out (↑) or Step out grouped (⇑). You can limit the number of breaks by changing a Step out grouped (⇑) to a Step out (↑).
There are special considerations when debugging while batch processing. You cannot step from the Batch Start action into the folder processing. You also cannot step into the Batch End action from the folder processing.
As breakpoints are not enabled by default when batch processing, you require at least one Debug statement. When the first Debug statement is executed, you can enabled breakpoints. The enabled/disabled status of breakpoints is maintained when transitioning between batch processor states. This means if you have a Debug statement in the Batch Start inline action, you can manually enable breakpoints and have them processed while folder processing.
Additional information: