FISH Debugging
This section describes FISH debugging capabilities that use the command-line interface. Any interface to PFC that supports direct command-line interaction should support this capability. A user-interface may, however, provide an alternate means by which to debug FISH code.
In order to make the most of this functionality, some understanding of how FISH is implemented is helpful. While
interpreting a FISH function, each line of source is converted (pseudo-compiled) into one or more pseudo-code objects,
and these objects are executed when the function is called. Each pseudo-code object created is assigned a unique ID number
for reference. Each pseudo-code object is also aware of the source file from which it originated and the line number of
that file. The pseudo-code objects, their ID numbers, and their breakpoint
status are available through the fish list code command.
To enter debugging mode, use the fish debug command, supplying the name of a FISH function. If the function
requires arguments, these must be specified on the command line following the function name. The arguments will be evaluated,
and the function will begin to execute in debug mode.
In debug mode, the code stops upon entry to the function. Each time the current execution point changes, information is output to the screen. This information includes the name of the function, the file name and line number of the source, and the source file line (if available) from which the current code originated. The command prompt changes to Debug>, and PFC waits for a response from the user about how to proceed. Note that input will be accepted from the current input source, so it is possible to include debug commands in a data file.
While in debug mode, the following commands are available:
- fish debug s keyword
- break keyword ...
This function sets and clears breakpoints in a number of ways. A breakpoint is set in a pseudo-code object, and causes FISH to stop before the object is executed and to provide the Debug> prompt. Note that breakpoints only function in debug mode.
- clear
Remove all breakpoints from all pseudo-code objects.
- code <i > b
Set or clear a breakpoint at a pseudo-code object with ID number i. If i is not specified, then the current pseudo-code object is used.
- fish b
Set or clear a breakpoint at the first pseudo-code object in the FISH function.
- codeinto
Execute a single pseudo-code object. If a function call is made in that object, then execution is stopped at the start of that function.
- codeover
Execute a single pseudo-code object; execution is not stopped if a function call is made in that object.
- codeto i
Execute until the pseudo-code object with ID i is about to be executed. If that object is never reached, then the original function call will end, as will the debugging mode.
- lineinto
Execute all pseudo-code objects originating from the current source line, and stop when the next pseudo-code object would have originated from the next line. If a function call is made, the debugger stops upon entry to that function.
- lineover
Execute all pseudo-code objects originating from the current source line, and stop when the next pseudo-code object originates from the next line. It does not stop if function calls that cause code to be executed in other functions are made.
- lineto i
Execute until code originating from the current source file at line i is reached. If that line is never reached, then the original function call will end, as will the debugging mode.
- list keyword ...
- call
Output the current call stack. For instance, if function fred calls function george, and execution is halted in function george, the call stack will read:
fred george
- code <i1 > <i2 >
Output the pseudo-code object with ID i1. If i1 is not specified, output the pseudo-code object that will be executed next. If i2 is specified, the pseudo-code from i1 to i2 is be output.
- fish
Output the current value of FISH symbol fish. The leading @ symbol is not necessary here, but it will be accepted. If the symbol is a function, it will not be executed; instead, its current value will be used.
- register
Output the current contents of the register. The register is used to store FISH values that are going to be passed as arguments to FISH intrinsics, used for array access or passed as arguments to functions.
- source <i1 > <i2 >
Output the line from the source file that was used to create the FISH function. If the source file is unavailable, an error will occur. If i1 is not specified, then the line corresponding to the current execution point is used. If i2 is specified, then lines from i1 to i2 are output.
- stack
The current contents of the stack are output. The stack is used to store local variables and arguments during function execution. At present, the names of stack variables are not available.
- run
Continue execution until a breakpoint is reached, or until the original function ends.
| Was this helpful? ... | PFC 6.0 © 2019, Itasca | Updated: Nov 19, 2021 |