bash-dap 0.1__tar.gz → 0.3__tar.gz

{bash_dap-0.1 → bash_dap-0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bash-dap
-Version: 0.1
+Version: 0.3
 Summary: A debug adapter (Debug Adapter Protocol) for bash scripts, written in bash and Python
 Author-email: Ilia Maslakov <il.smind@gmail.com>
 License: GPL-3.0-or-later
@@ -18,8 +18,9 @@ Dynamic: license-file
 # bash-dap
 
 A debug adapter of the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)
-for bash scripts: breakpoints, steps into, over and out of functions, the call stack, the
-variables (arrays and associative arrays as trees), expressions, pause.
+for bash scripts: breakpoints on lines, with conditions, and on functions, steps into, over and
+out of functions, the call stack, the variables (arrays and associative arrays as trees),
+expressions, pause.
 
 It needs nothing but bash 4.1 or newer and Python 3.8 or newer: no bashdb, no Node.js.  (The bash
 of macOS is 3.2: a newer one, from Homebrew say, is given to the launch as *bash*.)  The debugger itself is a script
@@ -75,13 +76,20 @@ subshell is a process of its own, so what is said to one, a step, a breakpoint,
 others through files of that directory, which every process looks at, at a test of two files a
 command.  A script under the debugger runs some 25 times slower than by itself.
 
+A breakpoint on a function stops at its first command, at each call, in a subshell too;
+what the script defines later, or a file it sources, is found as well, as the name is all
+the debugger looks for.
+
+The condition of a breakpoint is a command of bash, `[[ $f == report.pdf ]]` or
+`(( count > 2 ))`: the script stops there when its status is 0.  It runs in a subshell, so it
+sees the variables of the script and changes none of them.
+
 When the session ends the adapter ends the script by its process group, the session it has to
 itself; never by a parent, never anything else.
 
 ## Not yet
 
-Conditional breakpoints, breakpoints on functions, a script that another script runs with a
-new bash.
+A script that another script runs with a new bash.
 
 ## License
 

{bash_dap-0.1 → bash_dap-0.3}/README.md

@@ -1,8 +1,9 @@
 # bash-dap
 
 A debug adapter of the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)
-for bash scripts: breakpoints, steps into, over and out of functions, the call stack, the
-variables (arrays and associative arrays as trees), expressions, pause.
+for bash scripts: breakpoints on lines, with conditions, and on functions, steps into, over and
+out of functions, the call stack, the variables (arrays and associative arrays as trees),
+expressions, pause.
 
 It needs nothing but bash 4.1 or newer and Python 3.8 or newer: no bashdb, no Node.js.  (The bash
 of macOS is 3.2: a newer one, from Homebrew say, is given to the launch as *bash*.)  The debugger itself is a script
@@ -58,13 +59,20 @@ subshell is a process of its own, so what is said to one, a step, a breakpoint,
 others through files of that directory, which every process looks at, at a test of two files a
 command.  A script under the debugger runs some 25 times slower than by itself.
 
+A breakpoint on a function stops at its first command, at each call, in a subshell too;
+what the script defines later, or a file it sources, is found as well, as the name is all
+the debugger looks for.
+
+The condition of a breakpoint is a command of bash, `[[ $f == report.pdf ]]` or
+`(( count > 2 ))`: the script stops there when its status is 0.  It runs in a subshell, so it
+sees the variables of the script and changes none of them.
+
 When the session ends the adapter ends the script by its process group, the session it has to
 itself; never by a parent, never anything else.
 
 ## Not yet
 
-Conditional breakpoints, breakpoints on functions, a script that another script runs with a
-new bash.
+A script that another script runs with a new bash.
 
 ## License
 

{bash_dap-0.1 → bash_dap-0.3}/bash_dap/__init__.py

@@ -1,3 +1,3 @@
 """bash-dap: a debug adapter of the Debug Adapter Protocol for bash scripts."""
 
-__version__ = "0.1"
+__version__ = "0.3"

{bash_dap-0.1 → bash_dap-0.3}/bash_dap/adapter.py

@@ -15,7 +15,11 @@ import tempfile
 import threading
 import time
 
+from . import __version__
+
 HARNESS = os.path.join(os.path.dirname(os.path.abspath(__file__)), "harness.sh")
+# a name of a function of bash, as a breakpoint takes it: no space, no quote, no parenthesis
+FUNCTION_NAME = re.compile(r"^[^\s()$`'\"\\]+$")
 VARIABLES_REF = 1  # the reference of the variables of a stop
 
 
@@ -108,6 +112,7 @@ class Adapter:
         self.alive = False
         self.pause_asked = False
         self.breaks = {}
+        self.functions = []
         self.gen = 0
         self.refs = {}
         self.next_ref = VARIABLES_REF + 1
@@ -194,8 +199,13 @@ class Adapter:
             return
         with open(os.path.join(self.dir, "breaks"), "w") as f:
             for path, lines in self.breaks.items():
-                for line in lines:
-                    f.write("%s:%d\n" % (path, line))
+                for line, condition in lines:
+                    if condition:
+                        f.write("%s:%d\t%s\n" % (path, line, condition))
+                    else:
+                        f.write("%s:%d\n" % (path, line))
+            for name in self.functions:
+                f.write("%s()\n" % name)
         self.gen += 1
         open(os.path.join(self.dir, "gen.%d" % self.gen), "w").close()
 
@@ -255,6 +265,8 @@ class Adapter:
             return
         if self.pause_asked and reason == "step":
             reason = "pause"
+        elif reason == "function":
+            reason = "function breakpoint"
         self.pause_asked = False
         self.event("stopped", {"reason": reason, "threadId": 1, "allThreadsStopped": True})
 
@@ -287,6 +299,8 @@ class Adapter:
         self.client = request.get("arguments", {})
         self.respond(request, {
             "supportsConfigurationDoneRequest": True,
+            "supportsFunctionBreakpoints": True,
+            "supportsConditionalBreakpoints": True,
             "supportsEvaluateForHovers": True,
             "supportsTerminateRequest": True,
         })
@@ -345,17 +359,30 @@ class Adapter:
     def on_setBreakpoints(self, request):
         args = request.get("arguments", {})
         path = os.path.realpath(args.get("source", {}).get("path", ""))
-        lines = [b["line"] for b in args.get("breakpoints", []) if "line" in b]
+        # a line and its condition, a command of bash whose status says whether to stop
+        lines = [(b["line"], " ".join(b.get("condition", "").split()))
+                 for b in args.get("breakpoints", []) if "line" in b]
         self.breaks[path] = lines
         self.save_breaks()
         self.respond(request, {"breakpoints": [
             {"id": i + 1, "verified": True, "line": line, "source": {"path": path}}
-            for i, line in enumerate(lines)]})
+            for i, (line, _) in enumerate(lines)]})
 
     def on_setFunctionBreakpoints(self, request):
-        self.respond(request, {"breakpoints": [
-            {"verified": False, "message": "bash-dap has breakpoints on lines only"}
-            for _ in request.get("arguments", {}).get("breakpoints", [])]})
+        """The functions to stop in at their first command; a name that is no name of a
+        function of bash is not taken"""
+        answers = []
+        self.functions = []
+        for b in request.get("arguments", {}).get("breakpoints", []):
+            name = b.get("name", "")
+            if FUNCTION_NAME.match(name):
+                self.functions.append(name)
+                answers.append({"id": 1000 + len(self.functions), "verified": True})
+            else:
+                answers.append({"verified": False,
+                                "message": "no name of a function of bash: %s" % name})
+        self.save_breaks()
+        self.respond(request, {"breakpoints": answers})
 
     def on_setExceptionBreakpoints(self, request):
         self.respond(request, {"breakpoints": []})
@@ -527,7 +554,7 @@ def main():
               "on stdin and stdout")
         return 0
     if len(sys.argv) > 1 and sys.argv[1] == "--version":
-        print("bash-dap 0.1")
+        print("bash-dap %s" % __version__)
         return 0
     Adapter(sys.stdin.buffer, sys.stdout.buffer).run()
     return 0

{bash_dap-0.1 → bash_dap-0.3}/bash_dap/harness.sh

@@ -9,14 +9,17 @@
 # "replies", which it reads what the debugger says from, a line each:
 #
 #   commands:  run | step | next | finish | print EXPRESSION | vars | stack
-#   replies:   stopped REASON LINE FUNCTION FILE      (REASON: entry, breakpoint, step)
+#   replies:   stopped REASON LINE FUNCTION FILE      (REASON: entry, breakpoint, function, step)
 #              value TEXT | var NAME TEXT | frame LEVEL FUNCTION LINE FILE | error TEXT
 #              done, after the reply to a command | exited CODE
 #
 # TEXT is quoted as printf %q does, so that a reply is one line.  A command is read only while
 # the script is stopped.  At any time the adapter may write the breakpoints to the file "breaks",
 # FILE:LINE a line, then make the empty file "gen.N" of the next generation N; and stop the
-# script at its next command by writing "step 0" to the file "state".
+# script at its next command by writing "step 0" to the file "state".  A line NAME() of
+# "breaks" is a breakpoint on the function NAME: the script stops at its first command.  After
+# FILE:LINE and a tab, a command of bash is the condition of the breakpoint: the script stops
+# there only when its status is 0.
 #
 # A subshell is a process of its own: what it is told, a step, a breakpoint, goes to the others
 # through these files.  The names of the debugger begin with __bdap_.
@@ -33,11 +36,14 @@ __bdap_state=$__bdap_dir/state
 __bdap_mode=run
 __bdap_depth=0
 # the breakpoints by FILE:LINE, and the generation of the file they came from; __bdap_names has
-# NAME:LINE, the name of the file only, that the trap tests at each command
-declare -A __bdap_breaks=() __bdap_names=()
+# NAME:LINE, the name of the file only, that the trap tests at each command; __bdap_funcs has
+# NAME() of the functions to stop in; __bdap_conds the conditions of FILE:LINE
+declare -A __bdap_breaks=() __bdap_names=() __bdap_funcs=() __bdap_conds=()
 __bdap_gen=0
 __bdap_inside=
 __bdap_prev=  # the place of the command before: a line stops when it is come to, not again
+__bdap_fdepth=0  # the depth of the calls at the command before: more is a function entered
+__bdap_fenter=  # a function to stop in is entered: its first command is next
 
 # the variables of bash itself, and those it makes for a function: not shown
 __bdap_known=" $(compgen -v | tr '\n' ' ') FUNCNAME BASH_ARGC BASH_ARGV BASH_LINENO BASH_SOURCE COLUMNS LINES "
@@ -93,8 +99,18 @@ __bdap_breaks_load () {
     done
     __bdap_breaks=()
     __bdap_names=()
-    while read -r __bdap_place; do
+    __bdap_funcs=()
+    __bdap_conds=()
+    while IFS= read -r __bdap_place; do
         [[ -z $__bdap_place ]] && continue
+        if [[ $__bdap_place == *$'\t'* ]]; then
+            __bdap_conds["${__bdap_place%%$'\t'*}"]=${__bdap_place#*$'\t'}
+            __bdap_place=${__bdap_place%%$'\t'*}
+        fi
+        if [[ $__bdap_place == *"()" ]]; then
+            __bdap_funcs["$__bdap_place"]=1
+            continue
+        fi
         __bdap_breaks["$__bdap_place"]=1
         __bdap_names["${__bdap_place##*/}"]=1
     done <"$__bdap_dir/breaks"
@@ -126,6 +142,7 @@ __bdap_wait () {
     __bdap_resume run 0
     __bdap_breaks=()
     __bdap_names=()
+    __bdap_funcs=()
     trap - DEBUG
 }
 
@@ -138,6 +155,13 @@ __bdap_on_line () {
     [[ -z $__bdap_word || ${__bdap_text[0]-} == *"$__bdap_word"* ]]
 }
 
+# Whether the condition of a breakpoint holds, none always: run in a subshell, it sees the
+# variables of the script and changes none of them
+__bdap_condition () {
+    [[ -z $1 ]] && return 0
+    ( eval "$1" ) </dev/null >/dev/null 2>&1
+}
+
 # Before a command of the script that may stop: what the script has set, -e, -u, -x, is not
 # the debugger's, which runs without
 __bdap_hook () {
@@ -169,9 +193,20 @@ __bdap_check () {
     next) ((__bdap_d <= __bdap_depth)) && __bdap_reason=step ;;
     finish) ((__bdap_d < __bdap_depth)) && __bdap_reason=step ;;
     esac
-    if [[ -z $__bdap_reason && -n ${__bdap_breaks["$__bdap_file:$__bdap_line"]-} ]] && __bdap_on_line; then
+    if [[ -z $__bdap_reason && -n ${__bdap_breaks["$__bdap_file:$__bdap_line"]-} ]] && __bdap_on_line \
+        && __bdap_condition "${__bdap_conds["$__bdap_file:$__bdap_line"]-}"; then
         __bdap_reason=breakpoint
     fi
+    # the first command of a function to stop in: the calls are deeper than at the command
+    # before; bash comes first to the line that defines it, with the call as the command
+    if [[ -z $__bdap_reason && -n ${__bdap_funcs["${FUNCNAME[2]-}()"]-} ]]; then
+        if ((__bdap_d - 1 > __bdap_fdepth)) && [[ $__bdap_command == "${FUNCNAME[2]}"* ]]; then
+            __bdap_fenter=1
+        elif ((__bdap_d - 1 > __bdap_fdepth)) || [[ -n $__bdap_fenter ]]; then
+            __bdap_reason=function
+        fi
+    fi
+    [[ -n $__bdap_reason ]] && __bdap_fenter=
     # the next command of a line is no new place to stop at
     [[ -z $__bdap_reason || $__bdap_prev == "$__bdap_line:${BASH_SOURCE[2]}" ]] && return 0
     # the lines of the frames, the one stopped in first
@@ -195,12 +230,14 @@ trap '__bdap_say "exited $?"' EXIT
 shopt -s extdebug
 set -o functrace
 # the hook only when there may be something to do: a step, a breakpoint in a file of that name
-# on the line, what another process has said; else a command costs a test of two files.  One
-# line: a second one would have LINENO one more
-# (with set -u of the script it runs too: nothing unset is read, BASH_SOURCE is empty at the end)
+# on the line or on the function, what another process has said; else a command costs a test
+# of two files.  One line: a second one would have LINENO one more
+# (with set -u of the script it runs too: nothing unset is read, BASH_SOURCE is empty at the end,
+# FUNCNAME unset out of any function)
 __bdap_trap='[[ -n $__bdap_inside || ( $__bdap_mode == run'
 __bdap_trap+=' && -z ${__bdap_names["${BASH_SOURCE[0]:+${BASH_SOURCE[0]##*/}}:$LINENO"]-}'
+__bdap_trap+=' && -z ${__bdap_funcs["${FUNCNAME[0]-}()"]-}'
 __bdap_trap+=' && ! -e $__bdap_state && ! -e $__bdap_dir/gen.$((__bdap_gen + 1)) ) ]] || __bdap_hook "$BASH_COMMAND";'
-__bdap_trap+=' __bdap_prev=$LINENO:${BASH_SOURCE[0]-}'
+__bdap_trap+=' __bdap_prev=$LINENO:${BASH_SOURCE[0]-} __bdap_fdepth=${FUNCNAME[0]+${#FUNCNAME[@]}}'
 trap "$__bdap_trap" DEBUG
 . "$0" "$@"

{bash_dap-0.1 → bash_dap-0.3}/bash_dap.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bash-dap
-Version: 0.1
+Version: 0.3
 Summary: A debug adapter (Debug Adapter Protocol) for bash scripts, written in bash and Python
 Author-email: Ilia Maslakov <il.smind@gmail.com>
 License: GPL-3.0-or-later
@@ -18,8 +18,9 @@ Dynamic: license-file
 # bash-dap
 
 A debug adapter of the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)
-for bash scripts: breakpoints, steps into, over and out of functions, the call stack, the
-variables (arrays and associative arrays as trees), expressions, pause.
+for bash scripts: breakpoints on lines, with conditions, and on functions, steps into, over and
+out of functions, the call stack, the variables (arrays and associative arrays as trees),
+expressions, pause.
 
 It needs nothing but bash 4.1 or newer and Python 3.8 or newer: no bashdb, no Node.js.  (The bash
 of macOS is 3.2: a newer one, from Homebrew say, is given to the launch as *bash*.)  The debugger itself is a script
@@ -75,13 +76,20 @@ subshell is a process of its own, so what is said to one, a step, a breakpoint,
 others through files of that directory, which every process looks at, at a test of two files a
 command.  A script under the debugger runs some 25 times slower than by itself.
 
+A breakpoint on a function stops at its first command, at each call, in a subshell too;
+what the script defines later, or a file it sources, is found as well, as the name is all
+the debugger looks for.
+
+The condition of a breakpoint is a command of bash, `[[ $f == report.pdf ]]` or
+`(( count > 2 ))`: the script stops there when its status is 0.  It runs in a subshell, so it
+sees the variables of the script and changes none of them.
+
 When the session ends the adapter ends the script by its process group, the session it has to
 itself; never by a parent, never anything else.
 
 ## Not yet
 
-Conditional breakpoints, breakpoints on functions, a script that another script runs with a
-new bash.
+A script that another script runs with a new bash.
 
 ## License
 

{bash_dap-0.1 → bash_dap-0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bash-dap"
-version = "0.1"
+version = "0.3"
 description = "A debug adapter (Debug Adapter Protocol) for bash scripts, written in bash and Python"
 readme = "README.md"
 license = { text = "GPL-3.0-or-later" }

{bash_dap-0.1 → bash_dap-0.3}/tests/test_adapter.py

@@ -198,6 +198,52 @@ class SessionTest(unittest.TestCase):
         c.wait_event("terminated")
         self.assertIn("3 files, 2800 bytes", c.output())
 
+    def test_function_breakpoints(self):
+        c = self.client = Client()
+        c.request("initialize", {"adapterID": "bash-dap", "linesStartAt1": True})
+        c.request("launch", {"program": script("backup.sh"), "cwd": SCRIPTS})
+        c.wait_event("initialized")
+        response = c.request("setFunctionBreakpoints", {"breakpoints": [
+            {"name": "size_of"}, {"name": "not a name"}]})
+        verified = [b["verified"] for b in response["body"]["breakpoints"]]
+        self.assertEqual(verified, [True, False])
+        c.request("configurationDone")
+        # at the first command of the function, in the subshell of $(...)
+        self.assertEqual(c.wait_event("stopped")["body"]["reason"], "function breakpoint")
+        self.assertEqual(c.stop_place(), [("size_of", "backup.sh", 7), ("main", "backup.sh", 15)])
+        # once a call, not at each of its commands
+        c.request("next", {"threadId": 1})
+        c.wait_event("stopped")
+        self.assertEqual(c.stop_place()[0], ("size_of", "backup.sh", 8))
+        c.request("continue", {"threadId": 1})
+        c.wait_event("stopped")
+        self.assertEqual(c.evaluate("$f")["body"]["result"], "photo.jpg")
+        # taken off, the script runs to its end
+        c.request("setFunctionBreakpoints", {"breakpoints": []})
+        c.request("continue", {"threadId": 1})
+        self.assertEqual(c.wait_event("exited")["body"]["exitCode"], 3)
+
+    def test_conditional_breakpoint(self):
+        c = self.client = Client()
+        c.request("initialize", {"adapterID": "bash-dap", "linesStartAt1": True})
+        c.request("launch", {"program": script("backup.sh"), "cwd": SCRIPTS})
+        c.wait_event("initialized")
+        response = c.request("setBreakpoints", {"source": {"path": script("backup.sh")},
+                                                "breakpoints": [
+            {"line": 15, "condition": "[[ $f == photo.jpg ]]"},
+            # an assignment in a condition changes nothing of the script
+            {"line": 16, "condition": "total=1000; false"}]})
+        self.assertTrue(all(b["verified"] for b in response["body"]["breakpoints"]))
+        c.request("configurationDone")
+        self.assertEqual(c.wait_event("stopped")["body"]["reason"], "breakpoint")
+        self.assertEqual(c.stop_place(), [("main", "backup.sh", 15)])
+        self.assertEqual(c.evaluate("$f")["body"]["result"], "photo.jpg")
+        self.assertEqual(c.evaluate("$total")["body"]["result"], "900")
+        # no other round stops, and the total is the script's own
+        c.request("continue", {"threadId": 1})
+        self.assertEqual(c.wait_event("exited")["body"]["exitCode"], 3)
+        self.assertIn("3 files, 2800 bytes", c.output())
+
     def test_pipe_sourced_file_and_dollar_zero(self):
         c = self.client = Client()
         c.start(script("pipe.sh"), [(script("lib.sh"), 3), (script("pipe.sh"), 6)])