Debugging in HFL

• Because HFL is a command-line program, debugging is done as a combination of print or logging statements, stepping through the code line by line, and inspecting data and cell structure elements.

Entering Debug mode

• The debugger built into the HFL interpreter runs during execution pauses.

• To enter debug mode, it is necessary to pause the program first.

• Thus to debug a program, the first step is to insert a call to one of the functions that will invoke a pause. There are several functions that will pause execution, including the pause() function.
• As an example, suppose we wish to start debugging just before calling function 'add()' in the following code:

  • var $x = 2, $y = 3, $z;
    $z = add($x, $y);
    print("THE SUM OF $x and $y IS $z");
    
    function add ($a, $b) {
      print("ADDING $a TO $b");
      return $a + $b;
      }
    

• We could insert a 'pause()' statement just before the call to 'add()':

  • var $x = 2, $y = 3, $z;
    pause('BEFORE CALLING ADD()');
    $z = add($x, $y);
    print("THE SUM OF $x and $y IS $z");
    
    function add ($a, $b) {
      print("ADDING $a TO $b");
      return $a + $b;
      }
    

• The when the compilation is run, we would see:

  • BEFORE CALLING ADD()
    PAUSING...
    ?
    

• The execution is now paused, and we are ready to begin debugging.
• See the section on "HFL Logging and Pause Functions" for information on other functions that will pause execution.

Stepping through the code

• Once in pause mode, the code can be stepped through using the Debugger step commands:
• s
  • Single-steps one instruction, by executing it and then pausing again.
  • Each single-step prints out the number of instructions executed so far, followed by a '>' character and then the instruction to be executed next.
  • For example, in the example above, we could single-step through the program one instruction each time we enter 's':

    • BEFORE CALLING ADD()
      PAUSING...
      ? s
      3 > |$z = add($x, $y)|
      
      PAUSING...
      ? s
      4 > |print("ADDING $a TO $b")|
      
      PAUSING...
      ? s
      ADDING 2 TO 3
      5 > |return($a + $b)|
      
      PAUSING...
      ?
      

  • Notice that the next instruction shown after the call to function 'add', is the first instruction inside of the function.
• o
  • Steps-Over one instruction, by executing all instructions that are inside function calls or scope specifications, and then pauses again.
  • Each single-step prints out the number of instructions executed so far, followed by a '>' character and then the instruction to be executed next.
  • For example, in the example above, we could step-over through the program one instruction each time we enter 'o':

    • BEFORE CALLING ADD()
      PAUSING...
      ? o
      STEPPING OVER...
      
      3 > |$z = add($x, $y)|
      
      PAUSING...
      ? o
      ADDING 2 TO 3
      STEPPING OVER...
      
      6 > |print("THE SUM OF $x and $y IS $z")|
      
      PAUSING...
      ?
      

  • Notice that instead of stepping into function 'add', it skipped to the next instruction after the call to it, which is the 'print' statement.
• r
  • Returns from (steps out of) current subroutine call.
  • For example, in the example above, we could single-step into function 'add', then step out using the 'r' command:

    • BEFORE CALLING ADD()
      PAUSING...
      ? s
      3 > |$z = add($x, $y)|
      
      PAUSING...
      ? s
      4 > |print("ADDING $a TO $b")|
      
      PAUSING...
      ? r
      STEPPING OUT...
      ADDING 2 TO 3
      THE SUM OF 2 and 3 IS 5
      

• ss
  • Starts the debugger in single-step mode. Each time a simple carriage-return is entered with no other values, the program will move forward one instruction in the HFL code.
  • This mode will continue until countermanded with an 'ss off' 's', 'o', or 'oo' Debugger command.
  • For example, in the example above, we could start single-step mode, and we would see the following results as we hit the Enter key:

    • BEFORE CALLING ADD()
      PAUSING...
      ? ss
      WILL SINGLE-STEP PROPS
      ?(Enter)
      3 > |$z = add($x, $y)|
      
      PAUSING...
      ?(Enter)
      4 > |print("ADDING $a TO $b")|
      
      PAUSING...
      ?(Enter)
      ADDING 2 TO 3
      5 > |return($a + $b)|
      
      PAUSING...
      ?(Enter)
      6 > |print("THE SUM OF $x and $y IS $z")|
      
      PAUSING...
      ?(Enter)
      THE SUM OF 2 and 3 IS 5
      

• ss off
  • Exits the debugger from single-step mode.
• oo
  • Starts the debugger in step-over mode. Each time a simple carriage-return is entered with no other values, the program will move forward one instruction in the HFL code as a 'step-over'.
  • This mode will continue until countermanded with an 'oo off' 'o', 's', or 'ss' Debugger command.
  • For example, in the example above, we could start step-over mode, and we would see the following results as we hit the Enter key:

    • BEFORE CALLING ADD()
      PAUSING...
      ? oo
      STEPPING OVER...
      
      3 > |$z = add($x, $y)|
      
      PAUSING...
      ?(Enter)
      ADDING 2 TO 3
      STEPPING OVER...
      
      6 > |print("THE SUM OF $x and $y IS $z")|
      
      PAUSING...
      ?(Enter)
      THE SUM OF 2 and 3 IS 5
      

• oo off
  • Exits the debugger from step-over mode.