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',
             and `procedure_specification'.

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', `finish', `forward',
             `mindepth', `maxdepth' and `continue'.

end
document_category 300 backward
backward   - Commands that move execution backward.
             The only such command is `retry'.

end
document_category 400 browsing
browsing   - Commands that let users explore the state of the computation.
             The browsing commands are `vars', `print', `browse',
             `stack', `up', `down', `level', and `current'.

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

end
document_category 600 parameter
parameter  - Commands that let users access debugger parameters.
             The parameter commands are `printlevel', `echo', `context',
	     `scroll', `mmc_options', `alias' and `unalias'.

end
document_category 700 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 800 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 900 developer
developer  - Commands that are intended to be of use only to developers
             of the Mercury implementation. The developer commands are
             `nondet_stack' and `stack_regs'.

end
document_category 1000 misc
misc       - Commands that do not fit into other categories.
             The misc commands are `source' and `quit'.

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 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.


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.


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 procedure_specification
procedure_specification
     Some debugger commands, e.g. `break', require a parameter that
     specifies a procedure.  Such a 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:' 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 queries 100 query
query MODULE1 MODULE2 ...
    See help for `cc_query'.
end
document queries 200 cc_query
cc_query MODULE1 MODULE2 ...
    See help for `io_query'.
end
document queries 300 io_query
io_query MODULE1 MODULE2 ...
     These commands allow you to type in queries (goals) interactively
     in the debugger.  When you use one of these commands, the debugger
     will respond with a query prompt (`?-' or `run <--'), at which you
     can type in a goal; the debugger will the compile and execute the
     goal and display the answer(s).  You can return from the query
     prompt to the `mdb>' prompt by typing the end-of-file indicator
     (typically control-D or control-Z), or by typing `quit.'.


     The module names MODULE1, MODULE2, ... specify which modules will
     be imported.  Note that you can also add new modules to the list
     of imports directly at the query prompt, by using a command of the
     form `[MODULE]', e.g. `[int]'.  You need to import all the modules
     that define symbols used in your query.  Queries can only use
     symbols that are exported from a module; entities which are
     declared in a module's implementation section only cannot be used.


     The three variants differ in what kind of goals they allow.  For
     goals which perform I/O, you need to use `io_query'; this lets you
     type in the goal using DCG syntax.  For goals which don't do I/O,
     but which have determinism `cc_nondet' or `cc_multi', you need to
     use `cc_query'; this finds only one solution to the specified goal.
     For all other goals, you can use plain `query', which finds all
     the solutions to the goal.


     For `query' and `cc_query', the debugger will print out all the
     variables in the goal using `io__write'.  The goal must bind all
     of its variables to ground terms, otherwise you will get a mode
     error.


     The current implementation works by compiling the queries
     on-the-fly and then dynamically linking them into the program
     being debugged.  Thus it may take a little while for your query to
     be executed.  Each query will be written to a file named `query.m'
     in the current directory, so make sure you don't name your source
     file `query.m'.  Note that dynamic linking may not be supported on
     some systems; if you are using a system for which dynamic linking
     is not supported, you will get an error message when you try to
     run these commands.


     You may also need to build your program using shared libraries for
     interactive queries to work.  With Linux on the Intel x86
     architecture, the default is for executables to be statically
     linked, which means that dynamic linking won't work, and hence
     interactive queries won't work either (the error message is rather
     obscure: the dynamic linker complains about the symbol
     `__data_start' being undefined).  To build with shared libraries,
     you can use `MGNUCFLAGS=--pic-reg' and `MLFLAGS=--shared' in your
     Mmakefile.  See the `README.Linux' file in the Mercury
     distribution for more details.

end
document forward 100 step
step [-NSans] [NUM]
     Steps forward NUM events.  If this command is given at event CUR,
     continues execution until event CUR + NUM. The default value of
     NUM is 1.


     The options `-n' or `--none', `-s' or `--some', `-a' or `--all'
     specify the print level to use for the duration of the command,
     while the options `-S' or `--strict' and `-N' or `--nostrict'
     specify the strictness of the command.


     By default, this command is not strict, and it uses the default
     print level.


     A command line containing only a number NUM is interpreted as if
     it were `step NUM'.


     An empty command line is interpreted as `step 1'.


end
document forward 200 goto
goto [-NSans] NUM
     Continues execution until the program reaches event number NUM.
     If the current event number is larger than NUM, it reports an
     error.


     The options `-n' or `--none', `-s' or `--some', `-a' or `--all'
     specify the print level to use for the duration of the command,
     while the options `-S' or `--strict' and `-N' or `--nostrict'
     specify the strictness of the command.


     By default, this command is strict, and it uses the default print
     level.


end
document forward 300 finish
finish [-NSans] [NUM]
     Continues execution until it reaches a final (EXIT or FAIL) port of
     the NUM'th ancestor of the call to which the current event refers.
     The default value of NUM is zero, which means skipping to the end
     of the current call.  Reports an error if execution is already at
     the desired port.


     The options `-n' or `--none', `-s' or `--some', `-a' or `--all'
     specify the print level to use for the duration of the command,
     while the options `-S' or `--strict' and `-N' or `--nostrict'
     specify the strictness of the command.


     By default, this command is strict, and it uses the default print
     level.


end
document forward 400 return
return [-NSans]
     Continues the program until the program finished returning, i.e.
     until it reaches a port other than EXIT.  Reports an error if the
     current event already refers to such a port.


     The options `-n' or `--none', `-s' or `--some', `-a' or `--all'
     specify the print level to use for the duration of the command,
     while the options `-S' or `--strict' and `-N' or `--nostrict'
     specify the strictness of the command.


     By default, this command is strict, and it uses the default print
     level.


end
document forward 500 forward
forward [-NSans]
     Continues the program until the program resumes forward execution,
     i.e. until it reaches a port other than REDO or FAIL.  Reports an
     error if the current event already refers to such a port.


     The options `-n' or `--none', `-s' or `--some', `-a' or `--all'
     specify the print level to use for the duration of the command,
     while the options `-S' or `--strict' and `-N' or `--nostrict'
     specify the strictness of the command.


     By default, this command is strict, and it uses the default print
     level.


end
document forward 600 mindepth
mindepth [-NSans] DEPTH
     Continues the program until the program reaches an event whose
     depth is at least DEPTH.  Reports an error if the current event
     already refers to such a port.


     The options `-n' or `--none', `-s' or `--some', `-a' or `--all'
     specify the print level to use for the duration of the command,
     while the options `-S' or `--strict' and `-N' or `--nostrict'
     specify the strictness of the command.


     By default, this command is strict, and it uses the default print
     level.


end
document forward 700 maxdepth
maxdepth [-NSans] DEPTH
     Continues the program until the program reaches an event whose
     depth is at most DEPTH.  Reports an error if the current event
     already refers to such a port.


     The options `-n' or `--none', `-s' or `--some', `-a' or `--all'
     specify the print level to use for the duration of the command,
     while the options `-S' or `--strict' and `-N' or `--nostrict'
     specify the strictness of the command.


     By default, this command is strict, and it uses the default print
     level.


end
document forward 800 continue
continue [-NSans]
     Continues execution until it reaches the end of the program.


     The options `-n' or `--none', `-s' or `--some', `-a' or `--all'
     specify the print level to use for the duration of the command,
     while the options `-S' or `--strict' and `-N' or `--nostrict'
     specify the strictness of the command.


     By default, this command is not strict. The print level used by
     the command by default depends on the final strictness level: if
     the command is strict, it is `none', otherwise it is `some'.


end
document backward 100 retry
retry
     Restarts execution at the call port of the call corresponding to
     the current event.


     The command will report an error unless the values of all the
     input arguments are available at the current port.  (The compiler
     will keep the values of the input arguments of traced predicates
     as long as possible, but it cannot keep them beyond the point
     where they are destructively updated.)


     The debugger can perform a retry only from an exit or fail port;
     only at these ports does the debugger have enough information to
     figure out how to reset the stacks.  If the debugger is not at
     such a port when a retry command is given, the debugger will
     continue forward execution until it reaches an exit or fail port
     of the call to be retried before it performs the retry.  This may
     require a noticeable amount of time.


retry NUM
     Restarts execution at the call port of the call corresponding to
     the NUM'th ancestor of the call to which the current event belongs.
     For example, if NUM is 1, it restarts the parent of the current
     call.


end
document browsing 100 vars
vars
     Prints the names of all the known variables in the current
     environment, together with an ordinal number for each variable.


end
document browsing 200 print
print NAME
print NUM
     Prints the value of the variable in the current environment with
     the given name, or with the given ordinal number.  This is a
     non-interactive version of the `browse' command (see below).
     Various settings which affect the way that terms are printed out
     (including e.g. the maximum term depth) can be set using the `set'
     command in the browser.


print *
     Prints the values of all the known variables in the current
     environment.


end
document browsing 300 browse
browse NAME
browse NUM
     Invokes an interactive term browser to browse the value of the
     variable in the current environment with the given ordinal number
     or with the given name.


     The interactive term browser allows you to selectively examine
     particular subterms.  The depth and size of printed terms may be
     controlled.  The displayed terms may also be clipped to fit within
     a single screen.


     For further documentation on the interactive term browser, invoke
     the `browse' command from within `mdb' and then type `help' at the
     `browser>' prompt.


end
document browsing 400 stack
stack [-d]
     Prints the names of the ancestors of the call specified by the
     current event.  If two or more ancestor calls are for the same
     procedure, the procedure identification will be printed once with
     the appropriate multiplicity annotation.


     The option `-d' or `--detailed' specifies that for each ancestor
     call, the call's event number, sequence number and depth should
     also be printed if the call is to a procedure that is being
     execution traced.


     This command will report an error if there is no stack trace
     information available about any ancestor.


end
document browsing 500 up
up [-d] [NUM]
     Sets the current environment to the stack frame of the NUM'th
     level ancestor of the current environment (the immediate caller is
     the first-level ancestor).


     If NUM is not specified, the default value is one.


     This command will report an error if the current environment
     doesn't have the required number of ancestors, or if there is no
     execution trace information about the requested ancestor, or if
     there is no stack trace information about any of the ancestors
     between the current environment and the requested ancestor.


     The option `-d' or `--detailed' specifies that for each ancestor
     call, the call's event number, sequence number and depth should
     also be printed if the call is to a procedure that is being
     execution traced.


end
document browsing 600 down
down [-d] [NUM]
     Sets the current environment to the stack frame of the NUM'th
     level descendant of the current environment (the procedure called
     by the current environment is the first-level descendant).


     If NUM is not specified, the default value is one.


     This command will report an error if there is no execution trace
     information about the requested descendant.


     The option `-d' or `--detailed' specifies that for each ancestor
     call, the call's event number, sequence number and depth should
     also be printed if the call is to a procedure that is being
     execution traced.


end
document browsing 700 level
level [-d] [NUM]
     Sets the current environment to the stack frame of the NUM'th
     level ancestor of the call to which the current event belongs.
     The zero'th ancestor is the call of the event itself.


     This command will report an error if the current environment
     doesn't have the required number of ancestors, or if there is no
     execution trace information about the requested ancestor, or if
     there is no stack trace information about any of the ancestors
     between the current environment and the requested ancestor.


     The option `-d' or `--detailed' specifies that for each ancestor
     call, the call's event number, sequence number and depth should
     also be printed if the call is to a procedure that is being
     execution traced.


end
document browsing 800 current
current
     Prints the current event.  This is useful if the details of the
     event, which were printed when control arrived at the event, have
     since scrolled off the screen.


end
document breakpoint 100 break
break [-PS] FILENAME:LINENUMBER
     Puts a break point on the specified line of the specified source
     file, if there is an event or a call at that position.  If the
     filename is omitted, it defaults to the filename from the context
     of the current event.


     The options `-P' or `--print', and `-S' or `--stop' specify the
     action to be taken at the break point.


     By default, the initial state of the break point is `stop'.

break [-PSaei] PROC-SPEC
     Puts a break point on the specified procedure.


     The options `-P' or `--print', and `-S' or `--stop' specify the
     action to be taken at the break point, while the options `-a' or
     `--all', `-e' or `--entry', and `-i' or `--interface' specify the
     invocation conditions of the break point.


     By default, the action of the break point is `stop', and its
     invocation condition is `interface'.


break [-PS] here
     Puts a break point on the procedure referred to by the current
     event, with the invocation condition being the event at the
     current location in the procedure body.


     The options `-P' or `--print', and `-S' or `--stop' specify the
     action to be taken at the break point.


     By default, the initial state of the break point is `stop'.


break info
     Lists the details and status of all break points.


end
document breakpoint 200 disable
disable NUM
     Disables the break point with the given number.  Reports an error
     if there is no break point with that number.


disable *
     Disables all break points.


end
document breakpoint 300 enable
enable NUM
     Enables the break point with the given number.  Reports an error
     if there is no break point with that number.


enable *
     Enables all break points.


end
document breakpoint 400 delete
delete NUM
     Deletes the break point with the given number.  Reports an error
     if there is no break point with that number.


delete *
     Deletes all break points.


end
document breakpoint 500 modules
modules
     Lists all the debuggable modules (i.e. modules that have debugging
     information).


end
document breakpoint 600 procedures
procedures MODULE
     Lists all the procedures in the debuggable module MODULE.


end
document breakpoint 700 register
register
     Registers all debuggable modules with the debugger.  Has no effect
     if this registration has already been done.  The debugger will
     perform this registration when creating breakpoints and when
     listing debuggable modules and/or procedures.


end
document parameter 100 mmc_options
mmc_options OPTION1 OPTION2 ...
     This command sets the options that will be passed to `mmc' to
     compile your query when you use one of the query commands:
     `query', `cc_query', or `io_query'.  For example, if a query
     results in a compile error, it may sometimes be helpful to use
     `mmc_options --verbose-error-messages'.


end
document parameter 200 printlevel
printlevel none
     Sets the default print level to `none'.


printlevel some
     Sets the default print level to `some'.


printlevel all
     Sets the default print level to `all'.


printlevel
     Reports the current default print level.


end
document parameter 300 echo
echo on
     Turns on the echoing of commands.


echo off
     Turns off the echoing of commands.


echo
     Reports whether commands are being echoed or not.


end
document parameter 400 scroll
scroll on
     Turns on user control over the scrolling of sequences of event
     reports.  This means that every screenful of event reports will be
     followed by a `--more--' prompt.  You may type an empty line,
     which allows the debugger to continue to print the next screenful
     of event reports.  By typing a line that starts with `a', `s' or
     `n', you can override the print level of the current command,
     setting it to `all', `some' or `none' respectively.  By typing a
     line that starts with `q', you can abort the current debugger
     command and get back control at the next event.


scroll off
     Turns off user control over the scrolling of sequences of event
     reports.


scroll SIZE
     Sets the scroll window size to SIZE, which tells scroll control to
     stop and print a `--more--' prompt after every SIZE - 1 events.
     The default value of SIZE is the value of the `LINES' environment
     variable, which should correspond to the number of lines available
     on the terminal.


scroll
     Reports whether user scroll control is enabled and what the window
     size is.


end
document parameter 500 context
context none
     When reporting events or ancestor levels, does not print contexts
     (filename/line number pairs).


context before
     When reporting events or ancestor levels, prints contexts
     (filename/line number pairs) before the identification of the
     event or call to which they refer, on the same line.  With long
     fully qualified predicate and function names, this may make the
     line wrap around.


context after
     When reporting events or ancestor levels, prints contexts
     (filename/line number pairs) after the identification of the event
     or call to which they refer, on the same line.  With long fully
     qualified predicate and function names, this may make the line
     wrap around.


context prevline
     When reporting events or ancestor levels, prints contexts
     (filename/line number pairs) on a separate line before the
     identification of the event or call to which they refer.


context nextline
     When reporting events or ancestor levels, prints contexts
     (filename/line number pairs) on a separate line after the
     identification of the event or call to which they refer.


context
     Reports where contexts are being printed.


end
document parameter 600 alias
alias NAME COMMAND [COMMAND-PARAMETER ...]
     Introduces NAME as an alias for the given command with the given
     parameters.  Whenever a command line has NAME as its first word,
     the debugger will substitute the given command and parameters for
     this word before executing the command line.


     If COMMAND is the upper-case word `EMPTY', the debugger will
     substitute the given command and parameters whenever the user
     types in an empty command line.



     If COMMAND is the upper-case word `NUMBER', the debugger will
     insert the given command and parameters before the command line
     whenever the user types in a command line that consists of a
     single number.


end
document parameter 700 unalias
unalias NAME
     Removes any existing alias for NAME.


end
document help 100 document_category
document_category SLOT CATEGORY
     Create a new category of help items, named CATEGORY.  The summary
     text for the category is given by the lines following this command,
     up to but not including a line containing only the lower-case word
     `end'.  The list of category summaries printed in response to the
     command `help' is ordered on the integer SLOT numbers of the
     categories involved.


end
document help 200 document
document CATEGORY SLOT ITEM
     Create a new help item named ITEM in the help category CATEGORY.
     The text for the help item is given by the lines following this
     command, up to but not including a line containing only the
     lower-case word `end'.  The list of items printed in response to
     the command `help CATEGORY' is ordered on the integer SLOT numbers
     of the items involved.


end
document help 300 help
help CATEGORY ITEM
     Prints help text about the item ITEM in category CATEGORY.


help WORD
     Prints help text about WORD, which may be the name of a help
     category or a help item.


help
     Prints summary information about all the available help categories.


end
document exp 100 histogram_all
histogram_all FILENAME
     Prints (to file FILENAME) a histogram that counts all events at
     various depths since the start of the program.  This histogram is
     available only in some experimental versions of the Mercury
     runtime system.


end
document exp 200 histogram_exp
histogram_exp FILENAME
     Prints (to file FILENAME) a histogram that counts all events at
     various depths since the start of the program or since the
     histogram was last cleared.  This histogram is available only in
     some experimental versions of the Mercury runtime system.


end
document exp 300 clear_histogram
clear_histogram
     Clears the histogram printed by `histogram_exp', i.e. sets the
     counts for all depths to zero.

end
document developer 100 nondet_stack
nondet_stack
     Prints the contents of the fixed slots of the frames on the nondet
     stack.


end
document developer 200 stack_regs
stack_regs
     Prints the contents of the virtual machine registers that point to
     the det and nondet stacks.


end
document developer 300 all_regs
all_regs
     Prints the contents of all the virtual machine registers.

end
document misc 100 source
source FILENAME
     Executes the commands in the file named FILENAME.


end
document misc 200 quit
quit [-y]
     Quits the debugger and aborts the execution of the program.  If
     the option `-y' is not present, asks for confirmation first.  Any
     answer starting with `y', or end-of-file, is considered
     confirmation.


     End-of-file on the debugger's input is considered a quit command.

end
