Replace evil -- first pass

DSL-Docs.rst

@@ -6,7 +6,7 @@ Symex DSL
 Introduction
 ------------
 
-The Symex.el Emacs package consists of three things: (1) A high-level language (or DSL) for tree operations, (2) A low-level tree abstraction layer, and (3) An Evil modal UI. The modal UI is documented in the `README <https://github.com/countvajhula/symex.el/blob/master/README.rst>`_, and the low-level abstraction layer is fulfilled by third party packages like Paredit and Lispy. This is the documentation for the DSL.
+The Symex.el Emacs package consists of three things: (1) A high-level language (or DSL) for tree operations, (2) A low-level tree abstraction layer, and (3) An Evil modal UI. The modal UI is documented in the `README <https://github.com/drym-org/symex.el/blob/master/README.rst>`_, and the low-level abstraction layer is fulfilled by third party packages like Paredit and Tree-Sitter. This is the documentation for the DSL.
 
 The Symex DSL allows you to specify arbitrary tree traversals in a cursor-oriented manner. That is, instead of describing traversals from an absolute reference point such as a root node, it allows you to describe traversals from the first-person vantage point of the cursor -- what would you do if you were where this cursor is right now? It allows you to describe what you'd like to do in intuitive terms that make sense for movement in a tree. Symex is the language a squirrel might use to describe a traversal to another squirrel.
 
@@ -112,8 +112,8 @@ Examples
 
   (symex-execute-traversal
     (symex-traversal
-      (maneuver (maneuver (move up)
-                          (circuit (move forward)))
+      (maneuver (move up)
+                (circuit (move forward))
                 (move up))))
 
 venture
@@ -431,9 +431,9 @@ Here, you can substitute the contents of ``(symex-traversal ...)`` with whatever
 Using a Debugger (EDebug)
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Another way is to use the ELisp Debugger, EDebug. This can be helpful to see the exact steps the DSL evaluator goes through in executing a traversal, and can be helpful for cases where the traversal isn't doing what you think it should be and you want to understand why (or even if you just want to understand how the evaluator works).
+Another way is to use the ELisp Debugger, EDebug. This allows you to see the exact steps the DSL evaluator goes through in executing a traversal and the effects it has on the code, and can be helpful if you want to understand why a traversal isn't doing what you think it should be doing (or even if you just want to understand how the DSL works). A good debugger isn't just for debugging problems, it's also an exploratory tool for quick feedback at the creative stage when you're implementing new functionality. It can help you be more efficient at every stage of development.
 
-To use it, first evaluate the ``symex-execute-traversal`` function for debugging by placing point somewhere within it and then invoking ``M-x edebug-defun`` (I personally have this bound in an ELisp specific leader / Hydra). Now, if you execute a traversal (e.g. via the REPL as in the recipe above), it will put you in the debugger and allow you to step through the code. Handy commands for EDebug:
+To use it, first evaluate the relevant traversal evaluator (for instance, the ``symex-execute-traversal`` function) for debugging by placing point somewhere within it and then invoking ``M-x edebug-defun`` (I personally have this bound in an ELisp specific leader / Hydra). Now, if you execute a traversal (e.g. via the REPL as in the recipe above, with a test expression in the Scratch buffer -- or even just by invoking the relevant feature on source code while in Symex mode), it will put you in the debugger and allow you to step through the code. Handy commands for EDebug:
 
 * ``s`` -- step forward
 * ``i`` -- step in
@@ -443,10 +443,23 @@ To use it, first evaluate the ``symex-execute-traversal`` function for debugging
 
 There are also lots of other features like setting and unsetting breakpoints (``b`` and ``u``), seeing a backtrace (``d``), evaluating expressions in the evaluation context (``e``), and lots more, making it an indispensible tool for ELisp debugging.
 
-When you're done debugging, you can remove the debugger hooks by just evaluating the debugged functions in the usual way (e.g. via ``M-x eval-defun``).
+When you're done debugging, you can remove the debugger hooks by just evaluating the debugged functions in the usual way (e.g. via ``M-x eval-defun`` or ``M-x eval-buffer``).
 
 Also see `this series on ELisp debugging <https://endlessparentheses.com/debugging-emacs-lisp-part-1-earn-your-independence.html>`__ for more tips.
 
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+Debugging Macros vs Functions
+`````````````````````````````
+
+If you are attempting to debug a feature implemented as a macro like ``symex-define-command``, you would need to evaluate the primitive functions for debugging, rather than the macro, or if necessary, copy the contents of the command to a new function and call that function from the macro, in order to be able to debug it. To be clear, you would need to evaluate the *function* for debugging rather than the macro. Naively, if you attempt to debug the macro, the debugger is triggered at compile time (i.e. as soon as you attempt to evaluate it for debugging!) and not at runtime when you're actually interested in using it. For the same reason, if you attempt to "step into" a macro invocation while the debugger is active, it won't do anything. You can only debug functions. If what you are interested in debugging is not a function, then put it in a function and debug that.
+
+"Buffer is read-only"
+`````````````````````
+
+Sometimes, the debugger appears to get overridden by Evil keybindings, complaining that the "Buffer is read-only" when you attempt to ``s`` to step forward. Saving the buffer (as opposed to debugging an unsaved buffer) seems to solve these issues, and if not, killing and reopening the buffer does.
+
 Print Statements and Asserts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -457,7 +470,7 @@ Minimizing Complexity
 
 Symex uses `advice <https://www.gnu.org/software/emacs/manual/html_node/elisp/Advising-Functions.html>`_ to implement some features such as branch memory. To minimize complexity while debugging, it may be advisable (so to speak) to disable such advice. To do this, find the place in the code where the advice is added and execute the corresponding function to remove it, something like ``(advice-remove #'symex-go-down #'symex--remember-branch-position)``. Of course, if disabling the advice causes the error to go away, then you can focus your efforts on debugging the advice itself in isolation.
 
-It may also be advisable to comment out macros like ``symex-save-excursion`` to see if the problem persists.
+It may also be advisable to comment out macros like ``symex-save-excursion`` to see if the problem persists. Commenting out macros like ``symex--with-undo-collapse`` will also help you use the debugger in code wrapped by such macros.
 
 Gotchas
 ^^^^^^^

Makefile

@@ -43,7 +43,7 @@ lint+less:
 	@$(MAKE) -f $(THIS_FILE) lint 2>&1 | less
 
 lint-no-noise:
-	@$(MAKE) -f $(THIS_FILE) lint 2>&1 | grep -v "start with.*prefix" |grep -v "lexical-binding" |grep -v "non-snapshot.*racket" |grep -v "non-snapshot.*clever" |grep -v "Version.*header is missing" |grep -v "Package-Version"
+	@$(MAKE) -f $(THIS_FILE) lint 2>&1 | grep -v "start with.*prefix" |grep -v "lexical-binding" |grep -v "non-snapshot.*racket" |grep -v "Version.*header is missing" |grep -v "Package-Version"
 
 lint-noiseless:
 	@$(MAKE) -f $(THIS_FILE) lint-no-noise 2>&1 | less

README.rst

@@ -1,5 +1,5 @@
-.. image:: https://github.com/countvajhula/symex.el/actions/workflows/test.yml/badge.svg
-    :target: https://github.com/countvajhula/symex.el/actions
+.. image:: https://github.com/drym-org/symex.el/actions/workflows/test.yml/badge.svg
+    :target: https://github.com/drym-org/symex.el/actions
 
 .. image:: https://melpa.org/packages/symex-badge.svg
     :alt: MELPA
@@ -33,7 +33,7 @@ Symex (pronounced sym-ex, as in symbolic expression) is a modal (like Vim but si
 - Implementing new structure-related features in general is easy [1]_.
 - Keybindings are short and memorable
 
-At the moment, symex mode uses ``paredit``, ``lispy``, and `evil-cleverparens <https://github.com/luxbock/evil-cleverparens>`_ to provide much of its low level functionality. In the future, this layer of primitives may be replaced with a layer that explicitly uses the abstract syntax tree, for still greater precision.
+Under the hood, Symex mode uses ``paredit`` and Tree-Sitter for parsing the code syntax tree.
 
 As of Jan 2023, there is "alpha" support for non-Lisp languages via ``tree-sitter``. While motions and a couple of basic transformations should work across languages (i.e. not only Lisp), it should be considered an early preview rather than production-worthy. Full support is planned for completion as part of the `2.0 release coming in Spring '23 <https://github.com/drym-org/symex.el/pull/71>`__.
 
@@ -50,7 +50,7 @@ Installation
 
 1. Install the package the usual way via MELPA (e.g. :code:`M-x package-install`).
 
-2. Then, assuming you're using `use-package <https://github.com/jwiegley/use-package>`__ to manage your configuration, add the following config to your ``init.d`` (note these instructions have changed as of `version 0.9 <https://github.com/countvajhula/symex.el/releases/tag/0.9>`__):
+2. Then, assuming you're using `use-package <https://github.com/jwiegley/use-package>`__ to manage your configuration, add the following config to your ``init.d`` (note these instructions have changed as of `version 0.9 <https://github.com/drym-org/symex.el/releases/tag/0.9>`__):
 
 ::
 
@@ -69,33 +69,19 @@ The Animated Guide
 
 The best way to learn how to use Symex is to read the `Animated Guide <https://countvajhula.com/2021/09/25/the-animated-guide-to-symex/>`_. Besides animations, it also contains lots of helpful field notes. Go check it out!
 
-Evil or Hydra?
+Symex and Evil
 --------------
 
-Symex provides both an evil state as well as a hydra-based modal interface. Which one should you use?
+At the moment, Symex uses an Evil state to implement its modal interface. Does that mean it's only for Evil users? No! It's just an implementation detail that you needn't be aware of, as Symex does not assume that you are an actual user of Evil.
 
-**TL;DR**: Use the evil option -- this is the default, and it is available to both evil and vanilla emacs users. If you're learning and would like some hand-holding as you familiarize yourself with the keybindings, use the hydra option, but it is likely that hydra will eventually be deprecated here.
+If you do happen to be an Evil user, using Symex should feel familiar, but while there are many similarities to Evil, it's also fairly different.
 
-The evil option is less obtrusive and allows you to, for instance, execute ``M-x`` commands without leaving symex mode. It should feel very similar to using Normal state, and doesn't interfere with normal Emacs usage including any custom keybindings you may be using.
-
-The hydra operates almost identically to the evil state, but it provides a comprehensive menu that can be toggled on and off, and can therefore help you learn the keybindings as you go along. On the other hand, the drawback is that the hydra will exit if you do something not specifically connected to symex mode -- for instance, if you run an ``M-x`` command, or do a text search, or save the buffer, or run a custom command of some kind. You could customize the hydra so that it is more persistent (e.g. "pink" or "amaranth" hydra) but doing so could cause it to interfere with normal Emacs functions, as hydra keybindings take precedence over everything else.
-
-In short, evil provides a more seamless experience, but hydra may be a good option while you are learning to use symex.
-
-Depending on your choice, put one of these in the ``:custom`` `section <https://github.com/jwiegley/use-package#customizing-variables>`__ (not the ``:config`` section) of your ``use-package`` form:
-
-::
-
-  (symex-modal-backend 'evil)
-
-::
-
-  (symex-modal-backend 'hydra)
+Symex has a modal interface, but one that's simpler than Evil. In Evil, the paradigm is composing verbs with nouns (or operators with motions, in Vim parlance), whereas Symex has a "point free" design where the noun is fixed (i.e. it assumes you mean to perform operations on symexes) so you only need to worry about what you are trying to do without bothering about composition. For more on this style of UI, see `Rigpa <https://github.com/countvajhula/rigpa>`_.
 
 Key Bindings
 ------------
 
-The table below lists the key bindings in Symex mode for Evil Symex users. You don't need this with the hydra frontend since you can lookup the keybindings at any time by pulling up the hydra menu (default binding: ``H-m``). Also for the evil frontend, while you don't have the menu, you can always use Emacs's ``C-h k`` to learn what a key does, as another way of learning the bindings.
+The table below lists the key bindings in Symex mode. You can also always use Emacs's ``C-h k`` to learn what a key does, as another way of learning the bindings.
 
 Movement
 ~~~~~~~~
@@ -321,21 +307,12 @@ Control
      - exit
      -
 
-The Menu (Hydra-only)
----------------------
-
-Entering the symex modal interface (via e.g. :code:`s-;`) using the hydra option shows you a comprehensive menu of all possible actions, by default. This is helpful initially, but over time you may prefer to dismiss the menu and bring it up only on demand, in order to conserve screen real estate. To do this, either run ``symex-toggle-menu`` via the menu entry point (``H-m``) while in symex mode, or add this to your ``init.d`` (e.g. in the ``:config`` section of the ``use-package`` form):
-
-::
-
-  (symex-hide-menu)
-
 Up and Down
 -----------
 
 The default keybindings in symex mode treat increasingly nested code as being "higher" and elements closer to the root as "lower." Think going "up" to the nest and "down" to the root. But symex allows you to modify these or any other keybindings to whatever you may find most natural.
 
-If you're using evil, put something resembling this in your configuration *before* the call to ``(symex-initialize)``:
+Put something resembling this in your configuration *before* the call to ``(symex-initialize)``:
 
 ::
 
@@ -347,21 +324,6 @@ If you're using evil, put something resembling this in your configuration *befor
           ("M-j" . symex-goto-highest)
           ("M-k" . symex-goto-lowest)))
 
-If you're using hydra, put something resembling this in your configuration *after* the call to ``(symex-initialize)``:
-
-::
-
-  (defhydra+ hydra-symex (:columns 4
-                          :post (symex-exit-mode)
-                          :after-exit (symex--signal-exit))
-      "Symex mode"
-      ("j" symex-go-up "up")
-      ("k" symex-go-down "down")
-      ("C-j" symex-climb-branch "climb branch")
-      ("C-k" symex-descend-branch "descend branch")
-      ("M-j" symex-goto-highest "go to highest")
-      ("M-k" symex-goto-lowest "go to lowest"))
-
 Branch Memory
 -------------
 
@@ -420,7 +382,7 @@ Tips
 Escaping to Symex Instead of Normal State
 -----------------------------------------
 
-For evil users, when you "escape" from Insert state, you may prefer to enter Symex state rather than Normal state while in Lisp buffers. You could write one-off keybindings to do this (e.g. `this recipe <https://github.com/countvajhula/symex.el/issues/24#issuecomment-815110143>`__ by user @tommy-mor), but if you'd like a more structured and flexible alternative, use `Rigpa <https://github.com/countvajhula/rigpa>`_.
+For evil users, when you "escape" from Insert state, you may prefer to enter Symex state rather than Normal state while in Lisp buffers. You could write one-off keybindings to do this (e.g. `this recipe <https://github.com/drym-org/symex.el/issues/24#issuecomment-815110143>`__ by user @tommy-mor), but if you'd like a more structured and flexible alternative, use `Rigpa <https://github.com/countvajhula/rigpa>`_.
 
 Also see `Easy Entry Into Symex State`_, below, for another option.
 
@@ -471,7 +433,7 @@ You could think of "w" as "wrap" in this context, as in, "to wrap with parenthes
 Learn More
 ==========
 
-Read the documentation for the `Symex DSL <https://github.com/countvajhula/symex.el/blob/master/DSL-Docs.rst>`_.
+Read the documentation for the `Symex DSL <https://github.com/drym-org/symex.el/blob/master/DSL-Docs.rst>`_.
 
 Learn more about the implementation and see some usage examples in the video overview (given at an `Emacs SF <https://www.meetup.com/Emacs-SF/>`_ meetup in 2019):
 

symex-computations.el

@@ -1,6 +1,6 @@
 ;;; symex-computations.el --- An evil way to edit Lisp symbolic expressions as trees -*- lexical-binding: t -*-
 
-;; URL: https://github.com/countvajhula/symex.el
+;; URL: https://github.com/drym-org/symex.el
 
 ;; This program is "part of the world," in the sense described at
 ;; https://drym.org.  From your perspective, this is no different than

symex-custom.el

@@ -1,6 +1,6 @@
 ;;; symex-custom.el --- An evil way to edit Lisp symbolic expressions as trees -*- lexical-binding: t -*-
 
-;; URL: https://github.com/countvajhula/symex.el
+;; URL: https://github.com/drym-org/symex.el
 
 ;; This program is "part of the world," in the sense described at
 ;; https://drym.org.  From your perspective, this is no different than
@@ -45,11 +45,6 @@
   :type 'boolean
   :group 'symex)
 
-(defcustom symex-modal-backend 'evil
-  "Whether to use hydra or evil as the backend for the modal interface."
-  :type 'symbol
-  :group 'symex)
-
 (defcustom symex-quote-prefix-list (list "'" "`")
   "List of prefixes to cycle through while using `symex-cycle-quote`."
   :type 'list

symex-data.el

@@ -1,6 +1,6 @@
 ;;; symex-data.el --- An evil way to edit Lisp symbolic expressions as trees -*- lexical-binding: t -*-
 
-;; URL: https://github.com/countvajhula/symex.el
+;; URL: https://github.com/drym-org/symex.el
 
 ;; This program is "part of the world," in the sense described at
 ;; https://drym.org.  From your perspective, this is no different than
@@ -341,6 +341,39 @@ This is the traversal that will be chosen if the condition is false."
              (nth 0 obj))
     (error nil)))
 
+(defun symex-delete-p (obj)
+  "Check if OBJ specifies a deletion."
+  (condition-case nil
+      (equal 'delete
+             (nth 0 obj))
+    (error nil)))
+
+(defun symex--deletion-what (deletion)
+  "Get the 'what' component of a DELETION."
+  (nth 1 deletion))
+
+(defun symex-paste-p (obj)
+  "Check if OBJ specifies a paste."
+  (condition-case nil
+      (equal 'paste
+             (nth 0 obj))
+    (error nil)))
+
+(defun symex--paste-side (paste)
+  "Get the side component of a PASTE."
+  (nth 1 paste))
+
+(defun symex-operation-p (obj)
+  "Check if OBJ specifies a generic operation."
+  (condition-case nil
+      (equal 'operation
+             (nth 0 obj))
+    (error nil)))
+
+(defun symex--operation-operation (operation)
+  "Get the actual OPERATION to perform."
+  (nth 1 operation))
+
 (defun symex-traversal-p (obj)
   "Check if OBJ specifies a traversal."
   (or (symex-move-p obj)
@@ -350,7 +383,10 @@ This is the traversal that will be chosen if the condition is false."
       (symex-detour-p obj)
       (symex-precaution-p obj)
       (symex-protocol-p obj)
-      (symex-decision-p obj)))
+      (symex-decision-p obj)
+      (symex-delete-p obj)
+      (symex-paste-p obj)
+      (symex-operation-p obj)))
 
 
 (provide 'symex-data)