Amiga Format 103/af103sub.adf/Hugo.LZX/Hugo/hdhelp.hlp

Text File | 1997-08-22 | 13KB | 440 lines

$binary file

# -------------------------------------------
# Hugo Debugger Help File
# Copyright (c) 1997 by Kent Tessman
# The General Coffee Company Film Productions
#
# Version 2.3
# -------------------------------------------

# ------------
# General help
# ------------

"help hugo debugger introduction intro menu menus menubar"
The Hugo Debugger

The Hugo Debugger is a tool for debugging programs written in
the Hugo language.  It enables a Hugo developer to trace code
execution, set breakpoints, watch expressions, modify values,
and perform other debugging functions expected of a modern
programming/design environment.

The Hugo Debugger is not a source-level debugger per se; that
is, it doesn't trace code execution by stepping visually
through the original source file(s).  Instead, it expands the
compact encoding of the compiled program line-by-line into its
source-level equivalent.

Help on various topics is available under the Help menu via
the "Topic" selection.  Alternatively, press the "Context Help"
key (see "Shortcut Keys" for further details) at any point to
get help about the current activity.

(Enter "list" as the topic for a list of available help
topics.)
$

"list available"
Available Help Topics

Hugo Debugger

Restarting
Printing
Exiting the Debugger

Windows
Code Window
Watch Window
Calls
Breakpoints
Local Variables
Property/Attribute Aliases
Auxiliary Window
Output

Running a program
Finish Routine
Stepping Through Code
Skipping Over Code
Stepping Backward

Searching Code
Watch Expressions
Setting or Modifying Values
Breakpoints
Object Tree
Moving Objects

Setup
$


# ---------
# File Menu
# ---------

"&Restart restart restarting"
File Menu:  Restart

Halts execution of the currently loaded program and reloads the
original program image from disk.  All global variables, array
values, properties, and attributes are restored to their
initial (i.e., compile-time) values.

Press Enter to confirm or Escape to cancel.
$


"&Print... print printing"
File Menu:  Print

Prints the contents of the current window to the printer
specified in the current Setup (see the Tools Menu).

Press Enter to confirm or Escape to cancel.
$


"E&xit Debugger exit quit exiting quitting"
File Menu:  Exit Debugger

Stops execution of the currently loaded program and exits the
Debugger.  (In the Debugger, as opposed to the Hugo Engine, the
'quit' statement does not force a return to the operating
system; use the "Exit Debugger" command to quit instead.)

Press Enter to confirm or Escape to cancel.
$


# -----------------------------
# View Menu (and other windows)
# -----------------------------

"view views window windows switching display displays"
Views

The Hugo Debugger allows you to switch between various windows
showing different information about the currently executing
program, all of which are automatically updated as the program
runs.

Available views include:
  - Code
  - Watch Window
  - Calls
  - Breakpoints
  - Local Variables
  - Property/Attribute Aliases
  - Help
  - Auxiliary Window
  - Output

Help is available on each of these.
$

"code current"
Code Window

The Code window is where the program code is displayed as it
executes.  Each statement, before it is run, is translated into
its source-level equivalent.  If color display is available,
different elements such as variables, objects, text, etc. will
be displayed in different colors.  (See "Setup" under the Tools
menu.)

The current (i.e., about to be run) line is the last-added to
the window.  This line is typically highlighted even when the
Code window is not the active window.

Another line is also highlighted, although only when the Code
window is active.  This selected line may be moved to help in
setting breakpoints, etc.

See "Shortcut Keys" under the Help menu for information on how
to navigate the Code window.
$

"&Watch &Watch... Window watch watches"
Watch Expressions

Once a watch expression has been entered using the "Watch..."
option under the Debug menu, it is displayed in the Watch
window as:

     <expression> : <value>

Some examples of <expression> are:

     object.property    (property)
     linelength         (global variable)
     local:4            (local variable)
     array[n]           (array)
     parent(object)     (built-in function)
     a + (5 * b)        (simple expression)
     children(obj) < i  (comparison)

(Note that while built-in functions such as parent() may be
used in a watch expression, routines and property routines may
not.  The reason for this is that since watch expressions are
continually and automatically updated, they cannot themselves
contain any program code.)

The <value> is automatically updated as the program runs.  As
with all Hugo data types, <value> is a 16-bit integer.  Whether
it is displayed as an integer value, dictionary entry, object
name, etc. is dependent on what is chosen for the "Watch As"
parameter.

When the Watch window is the active window, it is possible to
toggle the selected expression (by pressing Enter) between
being a breakpoint or not.  A breakpoint expression forces the
Debugger to suspend execution whenever <value> is non-zero.
Breakpoint expressions are indicated by a "B:" at the start of
the line (and by the breakpoint color, if color is available).
$

"&Calls calls call"
View Menu:  Calls

The Calls window displays the current nesting of routine calls.
That is, if Routine1 calls Routine2, and Routine2 calls
Routine3, the Calls window would show

  Routine1
    Routine2
      Routine3

while stepping through Routine3.

When a non-linear stepping command is given, such as stepping
backward, the Calls window may be erased, as the previous
nesting of routine calls is no longer applicable.
$

"&Breakpoints &Breakpoint... breakpoints breakpoint"
Breakpoints

Lines of code can be flagged as breakpoints; when a breakpoint
is encountered, execution is suspended and control is passed to
the Debugger.

To set a breakpoint, either select "Breakpoint..." from the
Debug menu, or press the appropriate shortcut key.  Enter the
address of the line to be set as a breakpoint.  If the
currently selected line in the code window is a program
statement (as opposed to some other message), the address of
that line of code becomes the default breakpoint address.

In addition to program addresses, other ways to specify a
breakpoint are by entering the routine name as "Routine" or, in
a case where a property is a routine, as "object.property".
$

"&Local Variables local locals"
View Menu:  Local Variables

Although it is possible to watch local variables in the Watch
window by entering 'local:n' (where n is a value from 1 to 16)
as the watch expression, it is sometimes convenient to readily
bring up a display of all local variables.

All local variables in the Local Variables window are watched
as the same data type.  That is, the "Watch As" parameter is
set as a group to integer value, object number, dictionary
entry, routine name, etc.

The displayed values of the entire set of local variables are
automatically updated as they change.
$

"Property/Attribute &Aliases property attribute properties attributes alias aliases"
View Menu:  Property/Attribute Aliases

When property numbers are translated to their souce-level
equivalent by the Debugger (i.e., to the property name), the
name used is the original or first-declared property name.
When a property is an alias of another property, both of them
are represented by the same number, so the Debugger has no way
of knowing if it is actually the alias being used.  (The same
applies to aliased attributes.)

For quick reference during Debugging, the Property/Attribute
Aliases window displays a list of which aliases are mapped to
which properties or attributes.
$

"A&uxiliary auxiliary"
Auxiliary Screen

The Auxiliary screen (or window, depending on your operating
system) is used as a workspace for displaying additional
information without writing to the normal output screen, help
window, or normal Debugger display.

The Object Tree, for example, is drawn on the Auxiliary screen.
$

"&Output output"
Output Screen

The Output screen is the normal program screen.  When a program
is run with the Hugo Engine instead of the Hugo Debugger, all
output--i.e., printed text--is sent to what the Debugger refers
to as the Output screen.
$


# --------
# Run Menu
# --------

"&Go run running program execution executing"
Running a Program

Selecting "Go" from the Run menu will execute the currently
loaded program.  If the program has previously been
interrupted, execution is resumed from the current (i.e., next)
line.

The view is switched to the Output screen, and the program runs
without interruption until:

  - A breakpoint is encountered
  - A watch-expression breakpoint evaluates to a non-zero value
  - Control is manually switched to the Debugger by the user,
    either at an input line or by forcing a break

See "Stepping and Tracing" for information on how to trace
execution line-by-line.
$

"&Step Step &Over S&kip Next St&ep Back step tracing trace stepping over back skip skipping next finish finishing"
Stepping and Tracing

All of the following are available from the "Run" menu, or by
pressing the applicable shortcut key:

Finish Routine
  - Suspends tracing until the current routine is completed.
    Tracing is resumed at the previous calling level.

Step
  - Allows you to trace program execution line-by-line, seeing
    each statement before it is executed.  Some debugging
    environments refer to this type of function as "Step Into",
    since when, for example, a routine call is encountered,
    tracing continues into (and subsequently out of) that
    routine.

Step Over
  - Like normal tracing (i.e, "Step", above), but routine calls
    are not "traced into".  Instead, stepping is suspended for
    the duration of the routine (and any other routines called
    within it).  Stepping is resumed once the initial routine
    call is completed.

Skip Next
  - Skips over the next line to be executed without performing
    any other operation.  This is useful, for example, in
    overriding variable assignments, routine calls, etc.

Step Back
  - Moves the current code position back to the last-executed
    statement.  Note that stepping backward shouldn't be
    thought of as identical to an "undo" operation--any data
    altered is not reset to the previous value when stepping
    backward.  "Step Back" is most useful for, e.g., modifying
    a value and then re-trying a particular expression,
    function, etc.
$


# ----------
# Debug Menu
# ----------

"&Search Code... search find searching finding"
Searching Code

Searches the entire Code window (including non-visible text)
for next occurrence, if any, of the entered string, beginning
with the selected line and continuing to the end of the data in
the Code window.  If no match is found at that point, the
search restarts at the beginning of the Code window text.

If the string is found, the next line containing it becomes the
selected line.
$

"Set &Value set setting modify modifying value values"
Setting or Modifying Values

Any variable data type can be set or modified using this
function.  Enter an expression to modify as:

     <expression> = <value>
     <object> is [not] <attribute

(The '=' or 'is' must be included, as appropriate.)

The assignment will be carried out exactly as if it was part of
normal program execution.
$

"Object &Tree &Move Object... object objects tree move moving"
Object Tree

To view the current parent-child-sibling hierarchy of objects,
select "Object Tree" from the Debug menu.  To view the entire
tree, enter "nothing" as the starting object, or simply hit
Enter.

The object tree will be displayed as:

     <parent>
        |
     <child>---<sibling>---...
        |          |
       ...        ...

where <parent> is the starting object.

To move an object's position, select "Move Object" from the
Debug menu, and enter both the object to be moved and the new
parent object.
$


# ----------
# Tools Menu
# ----------

"&Setup... setup color colors printer"
Setup

The Setup menu allows you to alter certain elements of the
Debugger setup.  Depending on your system configuration, not
all setup options may be available.

Color
  - If available, allows you to choose various combinations of
    colors and backgrounds to customize the look of the main
    Debugger screen.

Printer
  - If available, allows you to select the device name to which
    output will be sent when activating "Print" from the File
    menu.  Enter the device name according to your normal
    operating system nomenclature.  (For example, on a PC, this
    might be "LPT1"; on an Amiga, "PRT:", etc.)
$

$end

# end of file
# end of file