document_category 100 concepts
concepts   - The concepts on which the Mercury debugger is based.
             The concepts for which documentation is available are
             `break_points', `strict_commands', `print_level',
             `default_print_level', `current_environment', `held_variables'
             `procedure_specification' and `decl_debug'.

end
document_category 150 queries
queries    - Commands for invoking goals interactively.
             The commands for queries are
             `query', `cc_query', and `io_query'.

end
document_category 200 forward
forward    - Commands that move execution forward.
             The forward commands are `step', `goto', `next', `finish',
             `exception', `return', `user, `forward',
	     `mindepth', `maxdepth' and `continue'.

end
document_category 300 backward
backward   - Commands that move execution backward.
             The backward commands are `retry' and `track'.

end
document_category 400 browsing
browsing   - Commands that let users explore the state of the computation.
             The browsing commands are `vars', `held_vars', `print', `browse',
             `stack', `up', `down', `level', `current', `view', `hold',
             `diff', `dump', `grep', `list' and `open'.

end
document_category 500 breakpoint
breakpoint - Commands that let users set and control breakpoints.
             The breakpoint commands are `break', `break_print', `condition',
	     `disable', `enable', `delete', `modules', `procedures' and
	     `register'.

end
document_category 600 io_tabling
io_tabling - Commands that let users control the tabling of I/O actions.
             The only such command is `table_io'.

end
document_category 700 parameter
parameter  - Commands that let users access debugger parameters.
             The parameter commands are `mmc_options', `printlevel', `scroll',
             `stack_default_limit', `goal_paths' `scope', `echo', 
             `context', `user_event_context', `list_context_lines',
	     `list_path', `push_list_dir', `pop_list_dir', `fail_trace_counts',
	     `pass_trace_counts', `max_io_actions', `format', `format_param',
	     `alias' and `unalias'.

end
document_category 800 help
help       - Commands that let users access and control the help system.
             The help commands are `document_category', `document' and `help'.
             For help on the `help' command, type `help help help'.

end
document_category 850 mdb_dd
mdb_dd     - mdb commands related to declarative debugging.  These are `dd', 
             `trust', `trusted' and `untrust'.

end
document_category 860 decl
decl       - Commands available from within the declarative debugger.  These 
             are `yes', `no', `inadmissible', `trust', `skip', `browse',
             `print', `set', `help', `info', `ask', `mark', `pd' and `quit'.

end
document_category 900 misc
misc       - Commands that are of interest to most users but do not fit into
             other categories. The misc commands are `source', `save', `shell'
             and `quit'.

end
document_category 1000 exp
exp        - Commands that let users collect and inspect experimental
             data about the behavior of the program. The exp commands are
             `histogram_all', `histogram_exp', and `clear_histogram'.

end
document_category 1100 developer
developer  - Commands that are intended to be of use only to developers
             of the Mercury implementation. The developer commands are
             `flag', `subgoal', `consumer', `gen_stack', `cut_stack,
             `pneg_stack', `mm_stacks', `nondet_stack', `stack_regs',
             `all_regs', `debug_vars', `stats', `print_optionals',
             `unhide_events', `table', `type_ctor', `class_decl',
             `all_type_ctors', `all_class_decls', `all_procedures' and
             `ambiguity'.

end
document concepts 100 break_points
break_points
     The user may associate a break point with some events that occur
     inside a procedure; the invocation condition of the break point
     says which events these are.  The four possible invocation
     conditions (also called scopes) are:

        • the call event,
        • all interface events,
        • all events, and
        • the event at a specific point in the procedure.

     The effect of a break point depends on the state of the break
     point.

        • If the state of the break point is ‘stop’, execution will stop
          and user interaction will start at any event within the
          procedure that matches the invocation conditions, unless the
          current debugger command has specifically disabled this
          behaviour (see the concept ‘strict commands’ below).

        • If the state of the break point is ‘print’, the debugger will
          print any event within the procedure that matches the
          invocation conditions, unless the current debugger command has
          specifically disabled this behaviour (see the concept ‘print
          level’ below).

     Neither of these will happen if the break point is disabled.

     Every break point has a print list.  Every time execution stops at
     an event that matches the breakpoint, mdb implicitly executes a
     print command for each element in the breakpoint's print list.  A
     print list element can be the word ‘goal’, which causes the goal to
     the printed as if by ‘print goal’; it can be the word ‘*’, which
     causes all the variables to the printed as if by ‘print *’; or it
     can be the name or number of a variable, possibly followed (without
     white space) by a term path, which causes the specified variable or
     part thereof to the printed as if the element were given as an
     argument to the ‘print’ command.

end
document concepts 200 strict_commands
strict_commands
     When a debugger command steps over some events without user
     interaction at those events, the _strictness_ of the command
     controls whether the debugger will stop execution and resume user
     interaction at events to which a break point with state ‘stop’
     applies.  By default, the debugger will stop at such events.
     However, if the debugger is executing a strict command, it will not
     stop at an event just because a break point in the stop state
     applies to it.

     If the debugger receives an interrupt (e.g. if the user presses
     control-C), it will stop at the next event regardless of what
     command it is executing at the time.

end
document concepts 300 print_level
print_level
     When a debugger command steps over some events without user
     interaction at those events, the _print level_ controls under what
     circumstances the stepped over events will be printed.

        • When the print level is ‘none’, none of the stepped over
          events will be printed.

        • When the print level is ‘all’, all the stepped over events
          will be printed.

        • When the print level is ‘some’, the debugger will print the
          event only if a break point applies to the event.

     Regardless of the print level, the debugger will print any event
     that causes execution to stop and user interaction to start.

end
document concepts 400 default_print_level
default_print_level
     The debugger maintains a default print level.  The initial value of
     this variable is ‘some’, but this value can be overridden by the
     user.

end
document concepts 500 current_environment
current_environment
     Whenever execution stops at an event, the current environment is
     reset to refer to the stack frame of the call specified by the
     event.  However, the ‘up’, ‘down’ and ‘level’ commands can set the
     current environment to refer to one of the ancestors of the current
     call.  This will then be the current environment until another of
     these commands changes the environment yet again or execution
     continues to another event.

end
document concepts 600 paths_in_terms
paths_in_terms
     When browsing or printing a term, you can use "^‘n’" to refer to
     the Nth subterm of that term.  If the term's type has named fields,
     you can use "^‘fname’" to refer to the subterm of the field named
     ‘fname’.  You can use several of these subterm specifications in a
     row to refer to subterms deep within the original term.  For
     example, when applied to a list, "^2" refers to the tail of the
     list (the second argument of the list constructor), "^2^2" refers
     to the tail of the tail of the list, and "^2^2^1" refers to the
     head of the tail of the tail, i.e.  to the third element of the
     list.  You can think of terms as Unix directories, with constants
     (function symbols of arity zero) being plain files and function
     symbols of arity greater than zero being directories themselves.
     Each subterm specification such as "^2" goes one level down in the
     hierarchy.  The exception is the subterm specification "^..", which
     goes one level up, to the parent of the current directory.

end
document concepts 700 held_variables
held_variables
     Normally, the only variables from the program accessible in the
     debugger are the variables in the current environment at the
     current program point.  However, the user can _hold_ variables,
     causing their values -or selected parts of their values- to stay
     available for the rest of the debugger session.  All the commands
     that accept variable names also accept the names of held variables;
     users can ask for a held variable by prefixing the name of the held
     variable with a dollar sign.

end
document concepts 800 user_defined_events
user_defined_events
     Besides the builtin set of events, the Mercury debugger also
     supports events defined by the user.  Each event appears in the
     source code of the Mercury program as a call prefixed by the
     keyword ‘event’, with each argument of the call giving the value of
     an event _attribute_.  Users can specify the set of user defined
     events that can appear in a program, and the names, types and order
     of the attributes of each kind of user defined event, by giving the
     name of an event set specification file to the compiler when
     compiling that program.  For more details, see *note User defined
     events::.

end
document concepts 900 user_defined_event_attributes
user_defined_event_attributes
     Normally, the only variables from the program accessible in the
     debugger are the variables in the current environment at the
     current program point.  However, if the current event is a user
     defined event, then the attributes of that event are also
     available.  All the commands that accept variable names also accept
     the names of attributes; users can ask for an attribute by
     prefixing the name of the attribute with an exclamation point.

end
document concepts 1000 procedure_specification
procedure_specification
     Some debugger commands, e.g. ‘break’, require a parameter that
     specifies a procedure.  The procedure may or may not be a
     compiler-generated unify, compare or index procedure of a type
     constructor.  If it is, the procedure specification has the
     following components in the following order:
        • An optional prefix of the form ‘unif*’, ‘comp*’, ‘indx*’ or
          ‘init*’, that specifies whether the procedure belongs to a
          unify, compare, index or init predicate.
        • An optional prefix of the form ‘MODULE.’ or ‘MODULE__’ that
          specifies the name of the module that defines the predicate or
          function to which the procedure belongs.
        • The name of the type constructor.
        • An optional suffix of the form ‘/ARITY’ that specifies the
          arity of the type constructor.
        • An optional suffix of the form ‘-MODENUM’ that specifies the
          mode number of the procedure within the predicate or function
          to which the procedure belongs.
     For other procedures, the procedure specification has the following
     components in the following order:
        • An optional prefix of the form ‘pred*’ or ‘func*’ that
          specifies whether the procedure belongs to a predicate or a
          function.
        • An optional prefix of the form ‘MODULE:’, ‘MODULE.’ or
          ‘MODULE__’ that specifies the name of the module that defines
          the predicate or function to which the procedure belongs.
        • The name of the predicate or function to which the procedure
          belongs.
        • An optional suffix of the form ‘/ARITY’ that specifies the
          arity of the predicate or function to which the procedure
          belongs.
        • An optional suffix of the form ‘-MODENUM’ that specifies the
          mode number of the procedure within the predicate or function
          to which the procedure belongs.

end
document concepts 10 decl_debug
     The declarative debugger tries to find a bug in your program by asking
     questions about the correctness of calls executed in your program.
     
     Because pure Mercury code does not have any side effects, the
     declarative debugger can make inferences such as "if a call produces
     incorrect output from correct input, then there must be a bug in the
     code executed by one of the descendents of the call".
     
     The declarative debugger is therefore able to automate much of the
     'detective work' that must be done manually when using the procedural
     debugger.
     
     The following commands are available from within the declarative 
     debugger:
end
