Merge pull request #94 from VlachJosef/master

Debugger support

Author: NathanLovato

Diff for: README.md

@@ -217,7 +217,8 @@ The following shortcuts are available by default:
   - <kbd>C-c C-b a</kbd> `gdscript-docs-browse-api`
   - <kbd>C-c C-b o</kbd> `gdscript-docs-browse-symbol-at-point`
 - Open hydra:
-  - <kbd>C-c r</kbd> `gdscript-hydra-show` (require hydra package to be installed
+  - <kbd>C-c r</kbd> `gdscript-hydra-show` (require hydra package to be installed)
+  - <kbd>C-c n</kbd> `gdscript-debug-hydra` (require hydra package to be installed)
 
 ## Customization
 
@@ -231,3 +232,112 @@ Code example:
 (setq gdscript-godot-executable "/path/to/godot") ;; Use this executable instead of 'godot' to open the Godot editor.
 (setq gdscript-gdformat-save-and-format t) ;; Save all buffers and format them with gdformat anytime Godot executable is run.
 ```
+
+## Debugger
+
+Use <kbd>C-c C-d b</kbd> to add breakpoint to your GDScript file. Red dot will appear in the left fringe to indicate position where breakpoint is placed.
+Use <kbd>C-c C-d r</kbd> to remove breakpoint.
+
+Once first breakpoint is added to the project, buffer named `* Breakpoints *` is created. This buffer displays all existing breakpoints in a project. Pressing <kbd>D</kbd> on breakpoint line deletes the breakpoint. Pressing <kbd>RET</kbd> on breakpoint line shows GDScript file with that breakpoint in other buffer.
+
+When any breakpoint exists, running project will automatically start debugger server (if one isn't already running) and connect to it.
+Debugger server runs on `localhost` with port specified by `gdscript-debug-port` customizable variable (`6010` by default).
+
+Once breakpoint is hit in your code, Emacs will show two special buffers with information related to a position of the breakpoint:
+
+- `* Stack frame vars *` - Display locals/members/globals variables for current stack point. It show variable name, its type and its value.
+- `* Inspector *` - Display detailed information about selected `ObjectId`. By default it show `self` reference.
+
+Any `ObjectId` in those two buffers can be inspected by pressing <kbd>RET</kbd> when point is on corresponding line.
+
+### Oneline/multiline display
+
+Variable values of types `Dictionary`, `PoolRealArray`, `PoolStringArray`, `PoolVector2Array`, `PoolVector3Array` and `PoolColorArray` could be toggled from one line display to multiline display by pressing `TAB` on corresponding line.
+
+### Fetching `ObjectId` details
+
+Pressing <kbd>d</kbd> in `* Stack frame vars *` or `* Inspector *` buffers (or on Debug Hydra) will fetch on the background data for all `ObjectId`s present in those two buffers and once all `ObjectId`s data are fetched, these two buffer are redisplayed. This redisplay will contain two additional informations about given `ObjectId`:
+ - real type (for example `KinematicBody2D` instead of `ObjectId`)
+ - node path
+
+Also fetched data are cached and not fetched again when said `ObjectId` is inspected later on (until new breakpoint is hit).
+
+On breakpoint hit Debug Hydra will be displayed below `* Stack frame vars *` and `* Inspector *` buffers.
+
+### Debug Hydra
+
+```
+n next  c continue  m step  b breakpoints  s stack  v vars  i inspector  t scene-tree  d details
+o pin   u unpin     q quit
+```
+
+ - <kbd>n</kbd> - Jump to next line and stops there
+ - <kbd>c</kbd> - Continue program execution until another breakpoint is hit
+ - <kbd>m</kbd> - Step into
+ - <kbd>s</kbd> - Show `* Stack dump *` buffer
+ - <kbd>v</kbd> - Show `* Stack frame vars *` buffer
+ - <kbd>i</kbd> - Show `* Inspector *` buffer
+ - <kbd>t</kbd> - Show `* Scene tree *` buffer
+ - <kbd>d</kbd> - Fetch details for all `ObjectId`s present in `* Stack frame vars *` and `* Inspector *` buffers and redisplay them
+ - <kbd>o</kbd> - Pin current `self` `ObjectId` in `* Inspector *` buffer. It stays displayed until it cease to exists or until it get unpinned
+ - <kbd>u</kbd> - Unpin currently pinned `ObjectId`
+ - <kbd>q</kbd> - Close Debug Hydra
+
+### `* Stack frame vars *` buffer
+
+Main source of information about running program. Contains information about locals/members/globals variables.
+
+- Press <kbd>TAB</kbd> to toggling oneline/multiline display for selected types
+- Press <kbd>RET</kbd> on `ObjectId` line to display its details in `* Inspector *`buffer
+- Press <kbd>l</kbd> to display `* Stack dump *` buffer
+- Press <kbd>d</kbd> to display additional details for `ObjectId` variables
+- Press <kbd>p</kbd> to go to previous line
+- Press <kbd>n</kbd> to go to next line
+- Press <kbd>o</kbd> to pin current `ObjectId` in `* Inspector *` buffer
+- Press <kbd>u</kbd> to unpin currently pinned `ObjectId`
+- Press <kbd>q</kbd> to close the buffer
+
+### `* Inspector *` buffer
+
+Contains information about inspected object. By default `self` variable from `* Stack frame vars *` is displayed. Inspected object is kept to be focused until other object is inspected or until inspected object cease to exists, in which case current `self` is displayed instead.
+
+- Press <kbd>TAB</kbd> to toggling oneline/multiline display for selected types
+- Press <kbd>RET</kbd> on `ObjectId` line to display its details
+- Press <kbd>RET</kbd> on `Node/path` line (second line from the top) to show given `ObjectId` in `* Scene Tree *` buffer
+- Press <kbd>l</kbd> deep in nested `ObjectId` to navigate one level up in the structure (ie. back). Pressing `l` while on top level object displays `* Stack frame vars *` buffer
+- Press <kbd>d</kbd> to display additional details for `ObjectId` variables
+- Press <kbd>p</kbd> to go to previous line
+- Press <kbd>n</kbd> to go to next line
+- Press <kbd>o</kbd> to pin current `ObjectId` in `* Inspector *` buffer
+- Press <kbd>u</kbd> to unpin currently pinned `ObjectId`
+- Press <kbd>q</kbd> to close the buffer
+
+### `* Stack dump *` buffer
+
+Contains stack dump information.
+
+- Press <kbd>SPC</kbd> to jump to gdscript file where stack frame points to
+- Press <kbd>RET</kbd> to jump to gdscript file and to show `* Stack frame vars *`, `* Inspector *` buffers and a Debug Hydra
+- Press <kbd>l</kbd> to display `* Stack frame vars *` buffer
+- Press <kbd>p</kbd> to go to previous line
+- Press <kbd>n</kbd> to go to next line
+- Press <kbd>q</kbd> to close the buffer
+
+### `* Breakpoints *` buffer
+
+Contains list of all existing breakpoints.
+
+- Press <kbd>SPC</kbd> to enable/disable all breakpoints
+- Press <kbd>RET</kbd> to open gdscript file where on give breakpoint position
+- Press <kbd>TAB</kbd> to display `* Stack dump *` buffer
+- Press <kbd>D</kbd> to delete the breakpoint
+- Press <kbd>q</kbd> to close the buffer
+
+### `* Scene tree *` buffer
+
+Contains tree visualisation of all `ObjectId`s in the running program.
+
+- Press <kbd>RET</kbd> to open corresponding `ObjectId` in `* Inspector *` buffer
+- Press <kbd>p</kbd> to go to previous line
+- Press <kbd>n</kbd> to go to next line
+- Press <kbd>q</kbd> to close the buffer

Diff for: gdscript-comint.el

@@ -37,6 +37,7 @@
 (require 'comint)
 (require 'compile)
 (require 'gdscript-customization)
+(require 'gdscript-debug)
 (require 'gdscript-format)
 (require 'gdscript-utils)
 
@@ -47,6 +48,7 @@
                                              comint-mode-map))
     (define-key map (kbd "C-a") 'comint-bol)
     (define-key map (kbd "C-c r") 'gdscript-hydra-show)
+    (define-key map (kbd "C-c n") 'gdscript-debug-hydra)
     map)
   "Basic mode map for `godot-mode'.")
 
@@ -76,9 +78,13 @@ When run it will kill existing process if one exists."
 Set process's buffer `inhibit-read-only' temporalily to value t,
 so that `internal-default-process-sentinel' can insert status
 message into the process’s buffer."
-  (with-current-buffer (process-buffer process)
-    (let ((inhibit-read-only t))
-      (internal-default-process-sentinel process event))))
+  (cond
+   ((string-match "hangup: 1\n" event)
+    nil)
+   (t
+    (with-current-buffer (process-buffer process)
+      (let ((inhibit-read-only t))
+        (internal-default-process-sentinel process event))))))
 
 (define-derived-mode godot-mode comint-mode "godot"
   "Major mode for godot.

Diff for: gdscript-customization.el

@@ -139,6 +139,11 @@ directory path containing the file `index.html'."
   :type 'string
   :group 'gdscript)
 
+(defcustom gdscript-debug-port 6010
+  "Debugger server port."
+  :type 'integer
+  :group 'gdscript)
+
 
 (provide 'gdscript-customization)
 ;;; gdscript-customization.el ends here