# Overall Debugger Command Syntax
# Copyright (C) 2014-2015 Rocky Bernstein <rocky@cpan.org>

=begin comment

The intent of this file is to live in both in the github wiki and as
part of on-line help documentation
lib/Devel/Trepan/CmdProcess/Command/Help/...

=end comment

=encoding utf8

=head1 Overall Debugger Command Syntax

If the first non-blank character of a line starts with #,
the command is ignored.

Commands are split at wherever C<;;> appears. This process disregards
any quotes or other symbols that have meaning in Perl. The strings
after the leading command string are put back on a command queue.

When reading a command if the string ends in C<\> (backslash), another
line is read and this is concatenated to the previous result with a
newline inserted between the prior string and the continuation string.

Within a single command, tokens are then white-space split. Again,
this process disregards quotes or symbols that have meaning in Perl.
Some commands like
L<C<eval>|Devel::Trepan::Command::CmdProcessor::Eval>, C<macro>, and
L<C<break>|Devel::Trepan::Command::CmdProcessor::Break> have access to
the untokenized string entered and make use of that rather than the
tokenized list.

Resolving a command name involves possibly 4 steps. Some steps may be
omitted depending on early success or some debugger settings:

=over 4

=item 1.

The leading token is first looked up in the macro table. If it is in
the table, the expansion is replaces the current command and possibly
other commands pushed onto a command queue. See L<C<help
macros>|Devel::Trepan::CmdProcessor::Command::Macros> for help on how
to define macros, and L<C<info
macro>|Devel::Trepan::CmdProcessor::Command::Info::Macros> for current
macro definitions.

=item 2.

The leading token is next looked up in the debugger alias table and
the name may be substituted there. See "help alias" for how to define
aliases, and "show alias" for the current list of aliases.

=item 3.

After the above, The leading token is looked up a table of debugger
commands. If an exact match is found, the command name and arguments
are dispatched to that command. Otherwise, we may check to see the the
token is a unique prefix of a valid command. For example, "dis" is not
a unique prefix because there are both "display" and "disable"
commands, but "disp" is a unique prefix. You can allow or disallow
abbreviations for commands using "set abbrev". The default is
abbreviations are on.

=item 4.

If after all of the above, we still don't find a command, the line
may be evaluated as a Perl statement in the current context of the
program at the point it is stopped. However this is done only if
"autoeval" is on.  (It is on by default.)

=back

If L<C<auto
eval>|Devel::Trepan::CmdProcessor::Command::Set::Auto::Eval> is not
set on, or if running the Perl statement produces an error, we display
an error message that the entered string is "undefined".

=head1 See also:

L<C<help syntax
examples>|Devel::Trepan::CmdProcessor::Command::Help::examples.pod>, and
L<C<help syntax suffix>|Devel::Trepan::CmdProcessor::Command::Help::suffix.pod>