From 61bcfd131ac281bfac83cb8146377fdc2a8f45a4 Mon Sep 17 00:00:00 2001 From: rocky Date: Thu, 15 Feb 2024 06:39:16 -0500 Subject: [PATCH] zsh{,db} -> bash{,db} and other doc fixes --- README.md | 2 +- command/break.sh | 2 +- command/condition.sh | 4 +- command/next.sh | 4 +- docs/Makefile | 2 +- docs/commands/breakpoints/condition.rst | 2 +- docs/commands/breakpoints/tbreak.rst | 11 ++--- docs/commands/data/display.rst | 29 +++++------ docs/commands/data/eval.rst | 4 +- docs/commands/data/examine.rst | 8 +-- docs/commands/data/load.rst | 8 +-- docs/commands/info/breakpoints.rst | 2 +- docs/commands/info/line.rst | 2 +- docs/commands/info/program.rst | 2 +- docs/commands/info/source.rst | 4 +- docs/commands/info/variables.rst | 31 ++++++------ docs/commands/running/debug.rst | 8 +-- docs/commands/running/kill.rst | 6 +-- docs/commands/running/next.rst | 11 ++--- docs/commands/running/skip.rst | 4 +- docs/commands/set/autoeval.rst | 8 +-- docs/commands/set/autolist.rst | 56 ++++++++++----------- docs/commands/set/debug.rst | 4 +- docs/commands/set/different.rst | 8 +-- docs/commands/set/style.rst | 4 +- docs/commands/show/aliases.rst | 4 +- docs/commands/show/args.rst | 4 +- docs/commands/show/autoeval.rst | 6 +-- docs/commands/show/autolist.rst | 4 +- docs/commands/show/basename.rst | 4 +- docs/commands/show/confirm.rst | 4 +- docs/commands/show/different.rst | 4 +- docs/commands/show/editing.rst | 4 +- docs/commands/show/filename-display.rst | 4 +- docs/commands/show/highlight.rst | 4 +- docs/commands/show/linetrace.rst | 4 +- docs/commands/show/listsize.rst | 4 +- docs/commands/show/style.rst | 4 +- docs/commands/show/trace-commands.rst | 4 +- docs/commands/show/width.rst | 4 +- docs/commands/support/source.rst | 2 +- docs/conf.py | 16 +++--- docs/entry-exit.rst | 28 +++++------ docs/features.rst | 12 ++--- docs/index.rst | 12 ++--- docs/install.rst | 65 +++++++------------------ docs/make.bat | 2 +- docs/manpage.rst | 35 +++++++------ docs/syntax/command.rst | 10 ++-- readthedocs.yaml | 35 +++++++++++++ test/example/stepping.sh | 2 +- 51 files changed, 250 insertions(+), 257 deletions(-) create mode 100644 readthedocs.yaml diff --git a/README.md b/README.md index c53b6320..2f40fb30 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [![Build Status Circle](https://circleci.com/gh/rocky/bashdb.svg?&style=shield)](https://circleci.com/gh/rocky/bashdb) -[![Packaging status](https://repology.org/badge/vertical-allrepos/zshdb.svg)](https://repology.org/project/zshdb/versions) +[![Packaging status](https://repology.org/badge/vertical-allrepos/bashdb.svg)](https://repology.org/project/bashdb/versions) Here, we have a debugger for Bash 5.2 and higher. diff --git a/command/break.sh b/command/break.sh index 36fd2131..07e7e285 100644 --- a/command/break.sh +++ b/command/break.sh @@ -34,7 +34,7 @@ See also: "tbreak" and "continue"' _Dbg_help_add tbreak \ -'**tbreak* [*loc-spec*] +'**tbreak** [ *location* ] [**if** *condition*] Set a one-time breakpoint at *loc-spec*. diff --git a/command/condition.sh b/command/condition.sh index c91f748d..e4047f88 100644 --- a/command/condition.sh +++ b/command/condition.sh @@ -1,7 +1,7 @@ # -*- shell-script -*- # condition.sh - gdb-like "condition" debugger command # -# Copyright (C) 2002-2006, 2008, 2009, 2011, 2016, 2019 +# Copyright (C) 2002-2006, 2008, 2009, 2011, 2016, 2019, 2024 # Rocky Bernstein rocky@gnu.org # # This program is free software; you can redistribute it and/or @@ -24,7 +24,7 @@ _Dbg_help_add condition \ Break only if *bash-cond* is true in breakpoint number *bp_number*. -*bp_number* is an integer and *cond* is an zsh expression to be evaluated whenever +*bp_number* is an integer and *cond* is an bash expression to be evaluated whenever breakpoint *bp_number* is reached. Examples: diff --git a/command/next.sh b/command/next.sh index ce2dd6db..4160d99e 100644 --- a/command/next.sh +++ b/command/next.sh @@ -29,9 +29,7 @@ _Dbg_help_add next \ Step one statement ignoring steps into function calls at this level. This is sometimes called 'step over' or 'step through'. -With an integer argument, perform ``next`` that many times. However if -an exception occurs at this level, or we *return*, *yield* or the -thread changes, we stop regardless of count. +With an integer argument, perform ``next`` that many times. A suffix of ``+`` on the command or an alias to the command forces to move to another line, while a suffix of ``-`` does the opposite and diff --git a/docs/Makefile b/docs/Makefile index 78430239..18a6d29c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,7 +5,7 @@ # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = python -msphinx -SPHINXPROJ = zshdb +SPHINXPROJ = bashdb SOURCEDIR = . BUILDDIR = _build diff --git a/docs/commands/breakpoints/condition.rst b/docs/commands/breakpoints/condition.rst index 72e3f1de..bc0d6904 100644 --- a/docs/commands/breakpoints/condition.rst +++ b/docs/commands/breakpoints/condition.rst @@ -6,7 +6,7 @@ Add Condition to a Breakpoint (condition) **condition** *bp_number* *condition* -*bp_number* is a breakpoint number. *condition* is a zsh expression +*bp_number* is a breakpoint number. *condition* is a bash expression which must evaluate to *True* before the breakpoint is honored. If *condition* is absent, any existing condition is removed; i.e., the breakpoint is made unconditional. diff --git a/docs/commands/breakpoints/tbreak.rst b/docs/commands/breakpoints/tbreak.rst index bf66448d..cae19ce1 100644 --- a/docs/commands/breakpoints/tbreak.rst +++ b/docs/commands/breakpoints/tbreak.rst @@ -9,12 +9,11 @@ Set a Temporary Breakpoint (tbreak) With a line number argument, set a break there in the current file. With a function name, set a break at first executable line of that function. Without argument, set a breakpoint at current location. If -a second argument is `if`, subequent arguments given an expression +a second argument is `if`, subsequent arguments given an expression which must evaluate to true before the breakpoint is honored. The location line number may be prefixed with a filename or module -name and a colon. Files is searched for using *sys.path*, and the `.py` -suffix may be omitted in the file name. +name and a colon. Examples: +++++++++ @@ -23,10 +22,8 @@ Examples: tbreak # Break where we are current stopped at tbreak 10 # Break on line 10 of the file we are currently stopped at - tbreak os.path.join # Break in function os.path.join - tbreak os.path:45 # Break on line 45 of os.path - tbreak myfile.py:45 # Break on line 45 of myfile.py - tbreak myfile:45 # Same as above. + tbreak /etc/profile:10 # Break on line 10 of /etc/default + tbreak myfile:45 # Use relative file name .. seealso:: diff --git a/docs/commands/data/display.rst b/docs/commands/data/display.rst index 3e574ead..f19d8c33 100644 --- a/docs/commands/data/display.rst +++ b/docs/commands/data/display.rst @@ -1,24 +1,25 @@ .. index:: display .. _display: -Set a Display Expression (`display`) ------------------------------------- +Set a Display Expression (``display``) +-------------------------------------- -**display** [ *format* ] *expression* +**display** [*stmt*] -Print value of expression *expression* each time the program stops. -*format* may be used before *expression* and may be one of `/c` for -char, `/x` for hex, `/o` for octal, `/f` for float or `/s` for string. +Evaluate *stmt* each time the debugger is stopped. If *stmt* is omitted, evaluate +all of the display statements that are active. In contrast, **info display** +shows the display statements without evaluating them. -For now, display expressions are only evaluated when in the same -code as the frame that was in effect when the display expression -was set. This is a departure from gdb and we may allow for more -flexibility in the future to specify whether this should be the -case or not. +Examples: ++++++++++ + +:: + + display echo $x # show the current value of x each time debugger stops + display # evaluate all display statements -With no argument, evaluate and display all currently requested -auto-display expressions. .. seealso:: - :ref:`undisplay ` to cancel display requests previously made. + :ref:`undisplay ` to cancel display requests previously made, and + `info display `. diff --git a/docs/commands/data/eval.rst b/docs/commands/data/eval.rst index 95a64ea0..2284f9ee 100644 --- a/docs/commands/data/eval.rst +++ b/docs/commands/data/eval.rst @@ -1,8 +1,8 @@ .. index:: eval .. _eval: -Evaluate a Zsh Expression (`eval`) ----------------------------------- +Evaluate a Bash Expression (``eval``) +------------------------------------- **eval** *cmd* diff --git a/docs/commands/data/examine.rst b/docs/commands/data/examine.rst index 30467469..c88d4c0b 100644 --- a/docs/commands/data/examine.rst +++ b/docs/commands/data/examine.rst @@ -1,8 +1,8 @@ .. index:: examine .. _examine: -Print the value of an expression (`examine`) --------------------------------------------- +Print the value of an expression (``examine``) +---------------------------------------------- **examine** *expr1* @@ -12,8 +12,8 @@ Single variables and arithmetic expressions do not need leading ``$`` for their value is to be substituted. However if neither these, variables need ``$`` to have their value substituted. -In contrast to normal zsh expressions, expressions should not have -blanks which would cause zsh to see them as different tokens. +In contrast to normal bash expressions, expressions should not have +blanks which would cause bash to see them as different tokens. Examples: +++++++++ diff --git a/docs/commands/data/load.rst b/docs/commands/data/load.rst index c8f2ca68..0afd4b98 100644 --- a/docs/commands/data/load.rst +++ b/docs/commands/data/load.rst @@ -1,12 +1,12 @@ .. index:: load .. _load: -Read in a Zsh Script (`load`) ------------------------------ +Read in a Bash Script (``load``) +--------------------------------- -**load** *zsh-script* +**load** *bash-script* -Read in lines of a *zsh-script*. +Read in lines of a *bash-script*. .. seealso:: diff --git a/docs/commands/info/breakpoints.rst b/docs/commands/info/breakpoints.rst index d613ad50..584686a0 100644 --- a/docs/commands/info/breakpoints.rst +++ b/docs/commands/info/breakpoints.rst @@ -22,7 +22,7 @@ Example: :: - zshdb<4> info breakpoints + bashdb<4> info breakpoints Num Type Disp Enb What 1 breakpoint keep n /etc/profile:8 2 breakpoint keep y /etc/profile:10 diff --git a/docs/commands/info/line.rst b/docs/commands/info/line.rst index f5dd4bf6..3cb8445c 100644 --- a/docs/commands/info/line.rst +++ b/docs/commands/info/line.rst @@ -13,7 +13,7 @@ Example: :: - zshdb<1> info line + bashdb<1> info line Line 4 of "/etc/profile" .. seealso:: diff --git a/docs/commands/info/program.rst b/docs/commands/info/program.rst index 8241f6f3..2876ba68 100644 --- a/docs/commands/info/program.rst +++ b/docs/commands/info/program.rst @@ -16,7 +16,7 @@ Example: :: - zshdb<1> info program + bashdb<1> info program Program stopped. It stopped after being stepped. Next statement to be run is: diff --git a/docs/commands/info/source.rst b/docs/commands/info/source.rst index 82200a8d..32df1cc1 100644 --- a/docs/commands/info/source.rst +++ b/docs/commands/info/source.rst @@ -6,14 +6,14 @@ Info Source **info source** -Information about the current zsh script file. +Information about the current bash script file. Example: ++++++++ :: - zshdb<1> info source + bashdb<1> info source Current script file is /etc/profile Located in /etc/profile Contains 27 lines. diff --git a/docs/commands/info/variables.rst b/docs/commands/info/variables.rst index ee89624e..56985f1b 100644 --- a/docs/commands/info/variables.rst +++ b/docs/commands/info/variables.rst @@ -4,28 +4,27 @@ Info Variables ---------------- -**info variables** [*property*] +**info variables [**-i**|**--integer**][**-r**|**--readonly**][**-x**|**--exports**][**-a**|**--indexed**][**-A*|**--associative**][**-t**|**--trace**][**-p**|**--properties**] -list global and static variable names. +list global and local variable names. -Variable lists by property. -*property* is an abbreviation of one of: +Options: + + -i | --exports restricted to integer variables + -r | --readonly restricted to read-only variables + -x | --exports restricted to exported variables + -a | --indexed restricted to indexed array variables + -A | --associative restricted to associative array variables + -t | --trace restricted to traced variables + -p | --properties display properties of variables as printed by declare -p -* arrays, -* exports, -* fixed, -* floats, -* functions, -* hash, -* integers, or -* readonly Examples: +++++++++ :: - info variables # show all variables - info variables readonly # show only read-only variables - info variables integer # show only integer variables - info variables functions # show only functions + info variables # show all variables + info variables -p # show all variables with their properties + info variables -r # show only read-only variables + info variables -i # show only integer variables diff --git a/docs/commands/running/debug.rst b/docs/commands/running/debug.rst index 22f85cf5..f5b840f3 100644 --- a/docs/commands/running/debug.rst +++ b/docs/commands/running/debug.rst @@ -1,12 +1,12 @@ .. index:: debug .. _debug: -Recursive Debugging (`debug`) ------------------------------ +Recursive Debugging (``debug``) +------------------------------- -**debug** [*zsh-script* [*args*...]] +**debug** [*bash-script* [*args*...]] -Recursively debug into *zsh-script*. +Recursively debug into *bash-script*. If *script* is not given, take the script name from the command that is about to be executed. Note that when the nested debug finished, you diff --git a/docs/commands/running/kill.rst b/docs/commands/running/kill.rst index aa49d896..a8a680d7 100644 --- a/docs/commands/running/kill.rst +++ b/docs/commands/running/kill.rst @@ -1,8 +1,8 @@ - index:: kill +.. index:: kill .. _kill: -Send Kill Signal (`kill`) -------------------------- +Send Kill Signal (``kill``) +--------------------------- **kill** [ *signal-number* ] diff --git a/docs/commands/running/next.rst b/docs/commands/running/next.rst index ec4e6a74..04002026 100644 --- a/docs/commands/running/next.rst +++ b/docs/commands/running/next.rst @@ -1,16 +1,15 @@ .. index:: next .. _next: -Step Over (`next`) ------------------- +Step Over (``next``) +-------------------- **next** [ **+** | **-** ] [ *count* ] -Step one statement ignoring steps into function calls at this level. +Step one statement ignoring steps into function calls at this level. This is sometimes called +'step over' or 'step through'. -With an integer argument, perform ``next`` that many times. However if -an exception occurs at this level, or we *return*, *yield* or the -thread changes, we stop regardless of count. +With an integer argument, perform ``next`` that many times. A suffix of ``+`` on the command or an alias to the command forces to move to another line, while a suffix of ``-`` does the opposite and diff --git a/docs/commands/running/skip.rst b/docs/commands/running/skip.rst index 839296e9..9c3de755 100644 --- a/docs/commands/running/skip.rst +++ b/docs/commands/running/skip.rst @@ -1,8 +1,8 @@ .. index:: skip .. _skip: -Skip over statement (`skip`) ----------------------------- +Skip over statement (``skip``) +------------------------------ **skip** [ *count* ] diff --git a/docs/commands/set/autoeval.rst b/docs/commands/set/autoeval.rst index af7c2ddf..4339835b 100644 --- a/docs/commands/set/autoeval.rst +++ b/docs/commands/set/autoeval.rst @@ -9,9 +9,9 @@ Auto-Evaluation of Unrecognized Debugger Commands (`set auto eval`) Evaluate unrecognized debugger commands. Often inside the debugger, one would like to be able to run arbitrary -zsh commands without having to preface expressions with +bash commands without having to preface expressions with ``print`` or ``eval``. Setting *autoeval* on will cause unrecognized -debugger commands to be *eval*'d as a zsh expression. +debugger commands to be *eval*'d as a bash expression. Note that if this is set, on error the message shown on type a bad debugger command changes from: @@ -20,11 +20,11 @@ debugger command changes from: Undefined command: "fdafds". Try "help". -to something more zsh-eval-specific such as: +to something more bash-eval-specific such as: :: - /tmp/zshdb_eval_26397:2: command not found: fdafds + /tmp/bashdb_eval_26397:2: command not found: fdafds .. seealso:: diff --git a/docs/commands/set/autolist.rst b/docs/commands/set/autolist.rst index b47eba11..039105a5 100644 --- a/docs/commands/set/autolist.rst +++ b/docs/commands/set/autolist.rst @@ -13,34 +13,34 @@ With this, you will get output like: :: - -> 1 from subprocess import Popen, PIPE - (trepan2) next - (/users/fbicknel/Projects/disk_setup/sqlplus.py:2): - ** 2 import os - 1 from subprocess import Popen, PIPE - 2 -> import os - 3 import re - 4 - 5 class SqlPlusExecutor(object): - 6 def __init__(self, connection_string='/ as sysdba', sid=None): - 7 self.__connection_string = connection_string - 8 self.session = None - 9 self.stdout = None - 10 self.stderr = None - (trepan2) next - (/users/fbicknel/Projects/disk_setup/sqlplus.py:3): - ** 3 import re - 1 from subprocess import Popen, PIPE - 2 import os - 3 -> import re - 4 - 5 class SqlPlusExecutor(object): - 6 def __init__(self, connection_string='/ as sysdba', sid=None): - 7 self.__connection_string = connection_string - 8 self.session = None - 9 self.stdout = None - 10 self.stderr = None - (trepan2) + bashdb<0> set autolist on + Auto run of 'list' command is on. + bashdb<1> s + (/etc/profile:20): + 20: if [ -d /etc/profile.d ]; then + 15: PS1='$ ' + 16: fi + 17: fi + 18: fi + 19: + 20: => if [ -d /etc/profile.d ]; then + 21: for i in /etc/profile.d/*.sh; do + 22: if [ -r $i ]; then + 23: . $i + 24: fi + bashdb<2> s + (/etc/profile:21): + 21: for i in /etc/profile.d/*.sh; do + 16: fi + 17: fi + 18: fi + 19: + 20: if [ -d /etc/profile.d ]; then + 21: => for i in /etc/profile.d/*.sh; do + 22: if [ -r $i ]; then + 23: . $i + 24: fi + 25: done .. seealso:: diff --git a/docs/commands/set/debug.rst b/docs/commands/set/debug.rst index ea5b4534..f60869c6 100644 --- a/docs/commands/set/debug.rst +++ b/docs/commands/set/debug.rst @@ -4,9 +4,9 @@ Recursive Debugging (`debug`) ----------------------------- -**debug** [*zsh-script* [*args*...]] +**debug** [*bash-script* [*args*...]] -Recursively debug into *zsh-script*. +Recursively debug into *bash-script*. If *script* is not given, take the script name from the command that is about to be executed. Note that when the nested debug finished, you diff --git a/docs/commands/set/different.rst b/docs/commands/set/different.rst index 321208fa..b112048a 100644 --- a/docs/commands/set/different.rst +++ b/docs/commands/set/different.rst @@ -1,7 +1,7 @@ .. index:: set; different .. _set_different: -Consecutive Stops on Different File/Line Positions) (`set different`) +Consecutive Stops on Different File/Line Positions) (``set different``) --------------------------------------------------------------------- **set different** [ **on** | **off** ] @@ -11,7 +11,7 @@ Set consecutive stops must be on different file/line positions. By default, the debugger traces all events possible including line, exceptions, call and return events. Just this alone may mean that for any given source line several consecutive stops at a given line may -occur. Independent of this, zsh allows one to put several commands in +occur. Independent of this, bash allows one to put several commands in a single source line of code. When a programmer does this, it might be because the programmer thinks of the line as one unit. @@ -21,8 +21,8 @@ often be too fine-grained and annoying. By setting different on you can set a more coarse-level of stepping which often still is small enough that you won't miss anything important. -Note that the `step` and `next` debugger commands have '+' and '-' -suffixes if you wan to override this setting on a per-command basis. +Note that the ``step`` and ``next`` debugger commands have '+' and '-' +suffixes if you want to override this setting on a per-command basis. .. seealso:: diff --git a/docs/commands/set/style.rst b/docs/commands/set/style.rst index 2bd7e0b1..4e9b932a 100644 --- a/docs/commands/set/style.rst +++ b/docs/commands/set/style.rst @@ -1,8 +1,8 @@ .. index:: set; style .. _set_style: -Set whether to use Pygments in Formatting Listings (`set style`) ---------------------------------------------------------------- +Set whether to use Pygments in Formatting Listings (``set style``) +------------------------------------------------------------------ **set style** [*pygments-style*] diff --git a/docs/commands/show/aliases.rst b/docs/commands/show/aliases.rst index 1f3523a1..806f2f38 100644 --- a/docs/commands/show/aliases.rst +++ b/docs/commands/show/aliases.rst @@ -1,8 +1,8 @@ .. index:: show; aliases .. _show_aliases: -Show Debugger Command Aliases (`show aliases`) ----------------------------------------------- +Show Debugger Command Aliases (``show aliases``) +------------------------------------------------ **show aliases** [ *alias* ...| **\*** ] diff --git a/docs/commands/show/args.rst b/docs/commands/show/args.rst index 784f1516..b36aa14d 100644 --- a/docs/commands/show/args.rst +++ b/docs/commands/show/args.rst @@ -1,8 +1,8 @@ .. index:: show; args .. _show_args: -Show Program invocation Arguments (`show args`) ------------------------------------------------ +Show Program invocation Arguments (``show args``) +------------------------------------------------- **show args** diff --git a/docs/commands/show/autoeval.rst b/docs/commands/show/autoeval.rst index 239de153..4664826c 100644 --- a/docs/commands/show/autoeval.rst +++ b/docs/commands/show/autoeval.rst @@ -1,12 +1,12 @@ .. index:: show; autoeval .. _show_autoeval: -Show whether to evaluation of unrecognized debugger commands (`show autoeval`) ------------------------------------------------------------------------------- +Show whether to evaluation of unrecognized debugger commands (``show autoeval``) +-------------------------------------------------------------------------------- **show autoeval** -Show whether *zsh* evaluates of unrecognized debugger commands. +Show whether *bash* evaluates of unrecognized debugger commands. .. seealso:: diff --git a/docs/commands/show/autolist.rst b/docs/commands/show/autolist.rst index 767f7430..dec87a07 100644 --- a/docs/commands/show/autolist.rst +++ b/docs/commands/show/autolist.rst @@ -1,8 +1,8 @@ .. index:: show; autolist .. _show_autolist: -Show whether list on entry is in effect (`show autolist`) ---------------------------------------------------------- +Show whether list on entry is in effect (``show autolist``) +----------------------------------------------------------- **show autolist** diff --git a/docs/commands/show/basename.rst b/docs/commands/show/basename.rst index 78479ed9..31ac5b1b 100644 --- a/docs/commands/show/basename.rst +++ b/docs/commands/show/basename.rst @@ -1,8 +1,8 @@ .. index:: show; basename .. _show_basename: -Show if path should have basename only (`show basename`) ---------------------------------------------------------- +Show if path should have basename only (``show basename``) +---------------------------------------------------------- **show basename** diff --git a/docs/commands/show/confirm.rst b/docs/commands/show/confirm.rst index a591c487..a0b1c8dc 100644 --- a/docs/commands/show/confirm.rst +++ b/docs/commands/show/confirm.rst @@ -1,8 +1,8 @@ .. index:: show; confirm .. _show_confirm: -Show whether to Confirm Potentially Dangerous Operations (`show confirm`) -------------------------------------------------------------------------- +Show whether to Confirm Potentially Dangerous Operations (``show confirm``) +--------------------------------------------------------------------------- **show confirm** diff --git a/docs/commands/show/different.rst b/docs/commands/show/different.rst index 2999957b..6a5af63a 100644 --- a/docs/commands/show/different.rst +++ b/docs/commands/show/different.rst @@ -1,8 +1,8 @@ .. index:: show; different .. _show_different: -Show whether to stop on same file/line positions (`show different`) -------------------------------------------------------------------- +Show whether to stop on same file/line positions (``show different``) +--------------------------------------------------------------------- Show consecutive stops on different file/line positions. diff --git a/docs/commands/show/editing.rst b/docs/commands/show/editing.rst index e7eba078..bcc2115e 100644 --- a/docs/commands/show/editing.rst +++ b/docs/commands/show/editing.rst @@ -1,8 +1,8 @@ .. index:: show; editing .. _show_editing: -Show whether GNU readline editing is in effect (`show editing`) ---------------------------------------------------------------- +Show whether GNU readline editing is in effect (``show editing``) +----------------------------------------------------------------- **show editing** diff --git a/docs/commands/show/filename-display.rst b/docs/commands/show/filename-display.rst index a71ae89b..3faa581b 100644 --- a/docs/commands/show/filename-display.rst +++ b/docs/commands/show/filename-display.rst @@ -1,8 +1,8 @@ .. index:: show; filename-display .. _show_filename-display: -Show how file names are displayed (`show filename-display`) ------------------------------------------------------------ +Show how file names are displayed (``show filename-display``) +------------------------------------------------------------- **show filename-display** diff --git a/docs/commands/show/highlight.rst b/docs/commands/show/highlight.rst index 0e0b9203..b5d82074 100644 --- a/docs/commands/show/highlight.rst +++ b/docs/commands/show/highlight.rst @@ -1,8 +1,8 @@ .. index:: show; highlight .. _show_highlight: -Show whether highlighting is used in output (`show highlight`) --------------------------------------------------------------- +Show whether highlighting is used in output (``show highlight``) +---------------------------------------------------------------- **show highlight** diff --git a/docs/commands/show/linetrace.rst b/docs/commands/show/linetrace.rst index 18218161..73d498fa 100644 --- a/docs/commands/show/linetrace.rst +++ b/docs/commands/show/linetrace.rst @@ -1,8 +1,8 @@ .. index:: show; linetrace .. _show_linetrace: -Show whether each sourceline is traced before running it (`show line`) ----------------------------------------------------------------------- +Show whether each sourceline is traced before running it (``show linetrace``) +----------------------------------------------------------------------------- **show linetrace** diff --git a/docs/commands/show/listsize.rst b/docs/commands/show/listsize.rst index 40a0ebaf..365da7ff 100644 --- a/docs/commands/show/listsize.rst +++ b/docs/commands/show/listsize.rst @@ -1,8 +1,8 @@ .. index:: show; listsize .. _show_listsize: -Lines shown in source listing) (`show listsize`) ------------------------------------------------- +Lines shown in source listing) (``show listsize``) +-------------------------------------------------- **show listsize** diff --git a/docs/commands/show/style.rst b/docs/commands/show/style.rst index d92cb83b..3886dce6 100644 --- a/docs/commands/show/style.rst +++ b/docs/commands/show/style.rst @@ -1,8 +1,8 @@ .. index:: show; style .. _show_style: -Show Pygments Formatting style in Listings (`show style`) ---------------------------------------------------------- +Show Pygments Formatting style in Listings (``show style``) +----------------------------------------------------------- **show style** *pygments-style* diff --git a/docs/commands/show/trace-commands.rst b/docs/commands/show/trace-commands.rst index 9e80ab37..81a58530 100644 --- a/docs/commands/show/trace-commands.rst +++ b/docs/commands/show/trace-commands.rst @@ -1,8 +1,8 @@ .. index:: show; trace-commands .. _show_trace-commands: -Show whether line tracing in is effect (`show trace-command`) -------------------------------------------------------------- +Show whether line tracing in is effect (``show trace-commands``) +---------------------------------------------------------------- **show trace-commands** diff --git a/docs/commands/show/width.rst b/docs/commands/show/width.rst index 606f9017..5ed738f2 100644 --- a/docs/commands/show/width.rst +++ b/docs/commands/show/width.rst @@ -1,8 +1,8 @@ .. index:: show; width .. _show_width: -Show terminal Width (`show width`) ----------------------------------- +Show terminal Width (``show width``) +------------------------------------ **show width** diff --git a/docs/commands/support/source.rst b/docs/commands/support/source.rst index 55ad23e4..a6dd8275 100644 --- a/docs/commands/support/source.rst +++ b/docs/commands/support/source.rst @@ -11,7 +11,7 @@ Read debugger commands from a file named *file*. Optional *-v* switch is executed. Option *-Y* sets the default value in any confirmation command to be "yes" and *-N* sets the default value to "no". -Note that the command startup file `.zshdbrc` is read automatically +Note that the command startup file `.bashdbrc` is read automatically via a *source* command the debugger is started. An error in any command terminates execution of the command file diff --git a/docs/conf.py b/docs/conf.py index 6a5b6a8f..78a8cb5d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# zshdb documentation build configuration file, created by +# bashdb documentation build configuration file, created by # sphinx-quickstart on Fri Sep 29 07:09:20 2017. # # This file is execfile()d with the current directory set to its @@ -50,8 +50,8 @@ master_doc = 'index' # General information about the project. -project = 'zshdb' -copyright = '2017, 2019, 2023 Rocky Bernstein' +project = 'bashdb' +copyright = '2017, 2019, 2023, 2024 Rocky Bernstein' author = 'Rocky Bernstein' # The version info for the project you're documenting, acts as replacement for @@ -119,7 +119,7 @@ # -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. -htmlhelp_basename = 'zshdbdoc' +htmlhelp_basename = 'bashdbdoc' # -- Options for LaTeX output --------------------------------------------- @@ -146,7 +146,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'zshdb.tex', 'zshdb Documentation', + (master_doc, 'bashdb.tex', 'bashdb Documentation', 'Rocky Bernstein', 'manual'), ] @@ -156,7 +156,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'zshdb', 'zshdb Documentation', + (master_doc, 'bashdb', 'bashdb Documentation', [author], 1) ] @@ -167,7 +167,7 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'zshdb', 'zshdb Documentation', - author, 'zshdb', 'gdb-like debugger for zsh.', + (master_doc, 'bashdb', 'bashdb Documentation', + author, 'bashdb', 'gdb-like debugger for bash.', 'Programming'), ] diff --git a/docs/entry-exit.rst b/docs/entry-exit.rst index 45276a2c..a875250b 100644 --- a/docs/entry-exit.rst +++ b/docs/entry-exit.rst @@ -1,4 +1,4 @@ -Entering the Zsh Debugger +Entering the Bash Debugger **************************** .. toctree:: @@ -8,7 +8,7 @@ Entering the Zsh Debugger Invoking the Debugger Initially ==================================== -The simplest way to debug your program is to run `zshdb`. Give +The simplest way to debug your program is to run ``bashdb``. Give the name of your program and its options and any debugger options: .. code:: console @@ -33,18 +33,18 @@ the name of your program and its options and any debugger options: unset i fi - $ zshdb /etc/profile + $ bashdb /etc/profile -For help on `zshdb` or options, use the ``--help`` option. +For help on `bashdb` or options, use the ``--help`` option. .. code:: console - $ zshdb --help + $ bashdb --help Usage: - zshdb [OPTIONS] + bashdb [OPTIONS] - Runs zsh under a debugger. + Runs bash under a debugger. options: ... @@ -61,26 +61,26 @@ adds overhead and slows down your program. Another possibility then is to add statements into your program to call the debugger at the spot in the program you want. To do this, you source -`zshdb/dbg-trace.sh` from where wherever it appears on your filesystem. +``bashdb/dbg-trace.sh`` from where wherever it appears on your filesystem. This needs to be done only once. -After that you call `_Dbg_debugger`. +After that you call ``_Dbg_debugger``. Here is an Example: .. code:: console - source path-to-zshdb/zshdb/dbg-trace.sh + source path-to-bashdb/bashdb/dbg-trace.sh # work, work, work. - # ... some zsh code + # ... some bash code _Dbg_debugger # start debugging here -Since `_Dbg_debugger` a function call, it can be nested inside some sort of +Since `_Dbg_debugger`` a function call, it can be nested inside some sort of conditional statement allowing one to be very precise about the -conditions you want to debug under. And until first call to `_Dbg_debugger`, +conditions you want to debug under. And until first call to ``_Dbg_debugger``, there is no debugger overhead. -Note that `_Dbg_debugger` causes the statement *after* the call to be stopped at. +Note that ``_Dbg_debugger`` causes the statement *after* the call to be stopped at. diff --git a/docs/features.rst b/docs/features.rst index c819a94a..ec05f46a 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -61,9 +61,9 @@ don't. Without a suffix you get the default; this is set by the :ref:`set diffe .. _trepanning: https://pypi.python.org/pypi/trepan2 .. _debuggers: https://metacpan.org/pod/Devel::Trepan .. _this: http://bashdb.sourceforge.net/pydb/features.html -.. _set_substitute: https://zshdb.readthedocs.org/en/latest/commands/set/substitute.html -.. _set_style: https://zshdb.readthedocs.org/en/latest/commands/set/style.html -.. _set_width: https://zshdb.readthedocs.org/en/latest/commands/set/width.html -.. _eval: https://zshdb.readthedocs.org/en/latest/commands/data/eval.html -.. _step: https://zshdb.readthedocs.org/en/latest/commands/running/step.html -.. _install: http://zshdb.readthedocs.org/en/latest/install.html +.. _set_substitute: https://bashdb.readthedocs.org/en/latest/commands/set/substitute.html +.. _set_style: https://bashdb.readthedocs.org/en/latest/commands/set/style.html +.. _set_width: https://bashdb.readthedocs.org/en/latest/commands/set/width.html +.. _eval: https://bashdb.readthedocs.org/en/latest/commands/data/eval.html +.. _step: https://bashdb.readthedocs.org/en/latest/commands/running/step.html +.. _install: http://bashdb.readthedocs.org/en/latest/install.html diff --git a/docs/index.rst b/docs/index.rst index 41fd6661..157cbf9d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,19 +1,18 @@ -.. zshdb documentation master file, created by +.. bashdb documentation master file, created by sphinx-quickstart on Fri Sep 29 07:09:20 2017. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -zshdb - a gdb-like debugger for zsh +bashdb - a gdb-like debugger for bash ======================================== -zshdb is a gdb-like debugger for zsh_. +bashdb is a gdb-like debugger for bash. Since this debugger is similar to other_ trepanning_ debuggers_ and *gdb* in general, knowledge gained by learning this is transferable to those debuggers and vice versa. -An Emacs interface is available via realgud_. Visual Studio integration is available from rogalmic via -ZshDebug_. +An Emacs interface is available via realgud_. .. toctree:: :maxdepth: 2 @@ -34,9 +33,6 @@ Indices and Tables * :ref:`genindex` * :ref:`search` -.. _zsh: http://www.zsh.org/ -.. _other: https://www.npmjs.com/package/trepan-ni .. _trepanning: https://pypi.python.org/pypi/trepan3k .. _debuggers: https://metacpan.org/pod/Devel::Trepan .. _realgud: https://github.com/realgud/realgud -.. _ZshDebug: https://marketplace.visualstudio.com/items?itemName=rogalmic.zsh-debug diff --git a/docs/install.rst b/docs/install.rst index e170951e..916ef32a 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -7,7 +7,7 @@ How to install From a Package ---------------- -Repology_ maintains a list of various bundled `zshdb` packages. Below are some specific distributions that contain `zshdb`. +Repology_ maintains a list of various bundled ``bashdb`` packages. Below are some specific distributions that contain ``bashdb``. At the time this documentation was built, here is status that they provide: @@ -16,24 +16,10 @@ At the time this documentation was built, here is status that they provide: Check the link above for more up-to-date information. -.. |packagestatus| image:: https://repology.org/badge/vertical-allrepos/zshdb.svg - :target: https://repology.org/project/zshdb/versions +.. |packagestatus| image:: https://repology.org/badge/vertical-allrepos/bashdb.svg + :target: https://repology.org/project/bashdb/versions -Debian/Ubuntu -+++++++++++++++ - -On Debian systems, and derivatives, `zshdb` can be installed by running: - -.. code:: console - - $ sudo apt-get install zshdb - - -The latest version may not yet be included in the archives. If you are running -a stable version of Debian or a derivative, you may need to install `zshdb` from -the backports repository for your version to get a recent version installed. - MacOSX +++++++ @@ -41,30 +27,14 @@ On OSX systems, you can install from Homebrew or MacPorts_. .. code:: console - $ brew install zshdb + $ brew install bashdb From Source ------------ -SourceForge -++++++++++++ - -Go to sourceforge_ and find the most recent version and download a tarball of that. - - -.. code:: console - - $ tar -xpf zshdb-xxx.tar.bz2 - $ cd zshdb-xxx - $ ./autogen.sh - $ make && make test - $ make install # may need sudo - - - -git -+++ +Github +++++++ Many package managers have back-level versions of this debugger. The most recent versions is from the github_. @@ -73,38 +43,38 @@ To install from git: .. code:: console - $ git clone git://github.com/rocky/zshdb.git - $ cd zshdb + $ git clone git://github.com/rocky/bashdb.git + $ cd bashdb $ ./autogen.sh # Add configure options. See ./configure --help -If you've got a suitable `zsh` installed, then +If you've got a suitable ``bashhb`` installed, then .. code:: console $ make && make test -To try on a real program such as perhaps `/etc/zsh/zshrc`: +To try on a real program such as perhaps ``/etc/profile``: .. code:: console - $ ./zshdb -L /etc/zsh/zshrc # substitute .../zshrc with your favorite zsh script + $ ./bashdb -L /etc/profile # substitute /etc/profile your favorite bash script To modify source code to call the debugger inside the program: .. code:: console - source path-to-zshdb/zshdb/dbg-trace.sh + source path-to-bashdb/bashdb/dbg-trace.sh # work, work, work. _Dbg_debugger # start debugging here -Above, the directory *path-to_zshdb* should be replaced with the +Above, the directory *path-to_bashdb* should be replaced with the directory that `dbg-trace.sh` is located in. This can also be from the -source code directory *zshdb* or from the directory `dbg-trace.sh` gets +source code directory *bashdb* or from the directory `dbg-trace.sh` gets installed directory. The "source" command needs to be done only once somewhere in the code prior to using `_Dbg_debugger`. @@ -122,7 +92,6 @@ and uninstall with: $ sudo make uninstall # ;-) -.. _MacPorts: https://ports.macports.org/port/zshdb/summary -.. _Repology: https://repology.org/project/zshdb/versions -.. _github: https://github.com/rocky/zshdb -.. _sourceforge: https://sourceforge.net/projects/bashdb/files/zshdb/ +.. _MacPorts: https://ports.macports.org/port/bashdb/summary +.. _Repology: https://repology.org/project/bashdb/versions +.. _github: https://github.com/rocky/bashdb diff --git a/docs/make.bat b/docs/make.bat index c8aa57b9..f6dd7848 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -9,7 +9,7 @@ if "%SPHINXBUILD%" == "" ( ) set SOURCEDIR=. set BUILDDIR=_build -set SPHINXPROJ=zshdb +set SPHINXPROJ=bashdb if "%1" == "" goto help diff --git a/docs/manpage.rst b/docs/manpage.rst index b39649bf..f351f40f 100644 --- a/docs/manpage.rst +++ b/docs/manpage.rst @@ -1,29 +1,29 @@ -.. _zshdb: +.. _bashdb: .. toctree:: .. contents:: -zshdb command +bashdb command ############# Synopsis -------- -**zshdb** [ *debugger-options* ] [ \-- ] [ *zsh-script* [ *script-options* ...]] +**bashdb** [ *debugger-options* ] [ \-- ] [ *bash-script* [ *script-options* ...]] -**zshdb** [ *options*] -c *execution-string* +**bashdb** [ *options*] -c *execution-string* Description ----------- -*zshdb* is a *zsh* script to which arranges for another *zsh* script +*bashdb* is a *bash* script to which arranges for another *bash* script to be debugged. The debugger has a similar command interface as gdb_. If your zsh script needs to be passed options, add ``--`` before the -script name. That will tell *zshdb* not to try to process any further +script name. That will tell *bashdb* not to try to process any further options. Options @@ -63,14 +63,14 @@ inside the debugger. See :ref:`set basename ` for more information :-n | --nx | --no-init: -Normally the debugger will read debugger commands in `~/.zshdbinit` if -that file exists before accepting user interaction. `.zshdbinit` is +Normally the debugger will read debugger commands in `~/.bashdbinit` if +that file exists before accepting user interaction. `.bashdbinit` is analogous to GNU gdb's `.gdbinit`: a user might want to create such a debugger profile to add various user-specific customizations. Using the `-n` option this initialization file will not be read. This is useful in regression testing or in tracking down a problem with -one's `.zshdbinit` profile. +one's `.bashdbinit` profile. :-c | --command *command-string*: @@ -89,7 +89,7 @@ changeable copyright date in the regression-test matching. :-x | --eval-command *debugger-cmdfile*: Run the debugger commands *debugger-cmdfile* before accepting user -input. These commands are read however after any `.zshdbinit` +input. These commands are read however after any `.bashdbinit` commands. Again this is useful running regression-testing debug scripts. @@ -98,8 +98,8 @@ scripts. The debugger needs to source or include a number of functions and these reside in a library. If this option is not given the default -location of library is relative to the installed zshdb script: -`../lib/zshdb`. +location of library is relative to the installed bashdb script: +`../lib/bashdb`. @@ -134,10 +134,10 @@ given script or command string. One problem with sourcing a debugged script is that the program name stored in ``$0`` will not be the name of the script to be debugged. The debugged script will appear in a call stack not as the top item but as -the item below `zshdb`. +the item below `bashdb`. -The `zshdb` script option assumes a version of zsh with debugging -support, zsh 4.3.6-dev-2 or later. +The `bashdb` script option assumes a version of bash with debugging +support. The debugger slows things down a little because the debugger has to intercept every statement and check to see if some action is to be taken. @@ -145,8 +145,7 @@ intercept every statement and check to see if some action is to be taken. See also --------- -* `bashdb manual `_ - Until a full manual is written, this manual for a similar bash debugger may give some guidance. The two debuggers have similar command interfaces (and code). -* `zshdb github `_ - the github project page +* `bashdb github `_ - the github project page Author ------ @@ -156,7 +155,7 @@ The current version is maintained (or not) by Rocky Bernstein. Copyright --------- -Copyright (C) 2009, 2017, 2019, 2023 Rocky Bernstein +Copyright (C) 2009, 2017, 2019, 2023, 2024 Rocky Bernstein This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or diff --git a/docs/syntax/command.rst b/docs/syntax/command.rst index af61d786..b87df462 100644 --- a/docs/syntax/command.rst +++ b/docs/syntax/command.rst @@ -5,11 +5,11 @@ Debugger Command Syntax Command names and arguments are separated with spaces like POSIX shell syntax. Parenthesis around the arguments and commas between them are -not used. If the first non-blank character of a line starts with `#`, +not used. If the first non-blank character of a line starts with ``#``, the command is ignored. Within a single command, tokens are then white-space split. Again, -this process disregards quotes or symbols that have meaning in `zsh`. +this process disregards quotes or symbols that have meaning in ``bash``. Some commands like :ref:`eval `, have access to the untokenized string entered and make use of that rather than the tokenized list. @@ -25,7 +25,7 @@ commands. If an exact match is found, the command name and arguments are dispatched to that command. 3. If after all of the above, we still don't find a command, the line -may be evaluated as a zsh statement in the current context of the +may be evaluated as a bash statement in the current context of the program at the point it is stopped. However this is done only if "auto evaluation" is on. It is on by default. @@ -33,8 +33,8 @@ If :ref:`auto eval ` is not set on, or if running the Python statement produces an error, we display an error message that the entered string is "undefined". -If you want zsh shell command-processing, it's possible to go into an -python shell with the corresponding the command `zsh` or `shell`. It +If you want bash shell command-processing, it's possible to go into an +python shell with the corresponding the command ``bash`` or ``shell``. It is also possible to arrange going into an python shell every time you enter the debugger. diff --git a/readthedocs.yaml b/readthedocs.yaml new file mode 100644 index 00000000..dd2aa46c --- /dev/null +++ b/readthedocs.yaml @@ -0,0 +1,35 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + # You can also specify other tool versions: + # nodejs: "20" + # rust: "1.70" + # golang: "1.20" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs + # builder: "dirhtml" + # Fail on all warnings to avoid broken references + # fail_on_warning: true + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +# python: +# install: +# - requirements: docs/requirements.txt diff --git a/test/example/stepping.sh b/test/example/stepping.sh index cf574f22..d1b1da2e 100755 --- a/test/example/stepping.sh +++ b/test/example/stepping.sh @@ -1,4 +1,4 @@ -#!/bin/zsh +#!/bin/bash # For testing break, delete, step, step+ step-, default step and set force. for ((i=0; i<3; i++)) do echo 1st loop $i ; done for ((i=0; i<3; i++)) do echo 2nd loop $i ; done