From 4e11175c98e0ea3c8fe5fac6469e52afd00eeb22 Mon Sep 17 00:00:00 2001
From: xificurC <xificurC@gmail.com>
Date: Mon, 19 Sep 2022 20:56:40 +0200
Subject: [PATCH] deprecate rcf/! for rcf/tap

Users found the name confusing, everyone can relate to the name tap.
---
 README.md                             | 18 +++++++++---------
 example/example.cljc                  | 18 +++++++++---------
 src/hyperfiddle/rcf.cljc              | 10 ++++++----
 src/hyperfiddle/rcf/impl.clj          |  8 ++++----
 test/hyperfiddle/rcf/cljs_test.cljs   | 12 ++++++------
 test/hyperfiddle/rcf/example_test.clj | 22 ++++++++++++----------
 test/hyperfiddle/rcf_test.cljc        |  6 +++---
 7 files changed, 49 insertions(+), 45 deletions(-)

diff --git a/README.md b/README.md
index b6d4988..3ff5209 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,7 @@ Tests are run when you send a file or form to your Clojure/Script REPL. In Cursi
 
 ```clojure
 (ns example
-  (:require [hyperfiddle.rcf :refer [tests ! %]]))
+  (:require [hyperfiddle.rcf :refer [tests tap %]]))
 
 (tests
   "equality"
@@ -122,7 +122,7 @@ Loading src/example.cljc...
 ```Clojure
 (ns example
   (:require [clojure.core.async :refer [chan >! go go-loop <! timeout close!]]
-            [hyperfiddle.rcf :as rcf :refer [tests ! %]]
+            [hyperfiddle.rcf :as rcf :refer [tests tap %]]
             [missionary.core :as m]))
 
 (rcf/set-timeout! 100)
@@ -131,17 +131,17 @@ Loading src/example.cljc...
   "async tests"
   #?(:clj  (tests
              (future
-               (rcf/! 1) (Thread/sleep 10)        ; tap value to queue
-               (rcf/! 2) (Thread/sleep 200)
-               (rcf/! 3))
+               (rcf/tap 1) (Thread/sleep 10)        ; tap value to queue
+               (rcf/tap 2) (Thread/sleep 200)
+               (rcf/tap 3))
              % := 1                               ; pop queue
              % := 2
              % := ::rcf/timeout)
      :cljs (tests
              (defn setTimeout [f ms] (js/setTimeout ms f))
-             (rcf/! 1) (setTimeout 10 (fn []
-             (rcf/! 2) (setTimeout 200 (fn []
-             (rcf/! 3)))))
+             (rcf/tap 1) (setTimeout 10 (fn []
+             (rcf/tap 2) (setTimeout 200 (fn []
+             (rcf/tap 3)))))
              % := 1
              % := 2
              % := ::rcf/timeout))
@@ -151,7 +151,7 @@ Loading src/example.cljc...
   (go-loop [x (<! c)]
     (when x
       (<! (timeout 10))
-      (! x)
+      (tap x)
       (recur (<! c))))
   (go (>! c :hello) (>! c :world))
   % := :hello
diff --git a/example/example.cljc b/example/example.cljc
index d72bee9..646d965 100644
--- a/example/example.cljc
+++ b/example/example.cljc
@@ -1,7 +1,7 @@
 (ns example
   (:require [clojure.core.async :refer [chan >! go go-loop <! timeout close!]]
             [clojure.test :as t]
-            [hyperfiddle.rcf :as rcf :refer [tests ! %]]
+            [hyperfiddle.rcf :as rcf :refer [tests tap %]]
             [missionary.core :as m]))
 
 (defn get-extension [path]
@@ -67,17 +67,17 @@
   "async tests"
   #?(:clj  (tests
             (future
-              (rcf/! 1) (Thread/sleep 10)
-              (rcf/! 2) (Thread/sleep 200)
-              (rcf/! 3))
+              (rcf/tap 1) (Thread/sleep 10)
+              (rcf/tap 2) (Thread/sleep 200)
+              (rcf/tap 3))
             % := 1
             % := 2
             % := ::rcf/timeout)
      :cljs (tests
             (defn set-timeout [f ms] (js/setTimeout ms f))
-            (rcf/! 1) (set-timeout 10 (fn []
-                                       (rcf/! 2) (set-timeout 200 (fn []
-                                                                   (rcf/! 3)))))
+            (rcf/tap 1) (set-timeout 10 (fn []
+                                       (rcf/tap 2) (set-timeout 200 (fn []
+                                                                   (rcf/tap 3)))))
             % := 1
             % := 2
             % := ::rcf/timeout
@@ -91,7 +91,7 @@
   (go-loop [x (<! c)]
     (when x
       (<! (timeout 10))
-      (! x)
+      (tap x)
       (recur (<! c))))
   (go (>! c :hello) (>! c :world))
   % := :hello
@@ -101,7 +101,7 @@
 (tests
   "missionary"
   (def !x (atom 0))
-  (def dispose ((m/reactor (m/stream! (m/ap (! (inc (m/?< (m/watch !x)))))))
+  (def dispose ((m/reactor (m/stream! (m/ap (tap (inc (m/?< (m/watch !x)))))))
                 (fn [_] #_(prn ::done)) #(prn ::crash %)))
   % := 1
   (swap! !x inc)
diff --git a/src/hyperfiddle/rcf.cljc b/src/hyperfiddle/rcf.cljc
index 785accf..97c73eb 100644
--- a/src/hyperfiddle/rcf.cljc
+++ b/src/hyperfiddle/rcf.cljc
@@ -38,13 +38,15 @@
 #?(:clj  (def ^:dynamic *generate-tests*  (= "true" (System/getProperty "hyperfiddle.rcf.generate-tests"))))
 
 (def ^{:doc "
-Function to push value to async queue, e.g. `(! 42)`. RCF redefines this var in tests context. For REPL
+Function to push value to async queue, e.g. `(tap 42)`. RCF redefines this var in tests context. For REPL
 convenience, defaults to println outside of tests context."}
-  ! (fn [x] (doto x println)))
+  tap (fn [x] (doto x println)))
+
+(def ^{:doc "Deprecated alias for `tap`." :deprecated true} ! tap)
 
 (comment
-  "! outside of tests macro"
-  (is (= (with-out-str (! 1)) "1\n")))
+  "tap outside of tests macro"
+  (is (= (with-out-str (tap 1)) "1\n")))
 
 (def ^{:doc "Queue behaving as a value. Assert `% := _` to pop from it. Async, will time out after `:timeout` option, default to 1000 (ms)."}
   %)
diff --git a/src/hyperfiddle/rcf/impl.clj b/src/hyperfiddle/rcf/impl.clj
index abef5c6..9147d24 100644
--- a/src/hyperfiddle/rcf/impl.clj
+++ b/src/hyperfiddle/rcf/impl.clj
@@ -65,20 +65,20 @@
 (defn has-%? [ast] (some? (first (filter %? (ana/ast-seq ast)))))
 (defn maybe-add-queue-support [env ast]
   (if (has-%? ast)
-    (-> (ana/analyze env `(let [[~'RCF__! ~'RCF__% ~'RCF__set-timeout!] (hyperfiddle.rcf/make-queue :hyperfiddle.rcf/timeout)]))
+    (-> (ana/analyze env `(let [[~'RCF__tap ~'RCF__% ~'RCF__set-timeout!] (hyperfiddle.rcf/make-queue :hyperfiddle.rcf/timeout)]))
         (ana/resolve-syms-pass)
         (ana/macroexpand-pass)
         (update-in [:body :statements] conj ast))
     ast))
 
-(defn rewrite-!-% [env ast]
+(defn rewrite-tap-% [env ast]
   (if-not (has-%? ast)
     ast
     (ana/postwalk
      (ana/only-nodes #{:var}
                      (fn [var-ast]
                        (condp = (ana/var-sym (:var var-ast))
-                         'hyperfiddle.rcf/! (assoc var-ast :form 'RCF__!)
+                         'hyperfiddle.rcf/tap (assoc var-ast :form 'RCF__tap)
                          'hyperfiddle.rcf/set-timeout! (assoc var-ast :form 'RCF__set-timeout!)
                          'hyperfiddle.rcf/%  (if (ana/cljs? env)
                                                var-ast
@@ -278,7 +278,7 @@
   (->> ast
        (maybe-add-stars-support env)
        (maybe-add-queue-support env)
-       (rewrite-!-% env)
+       (rewrite-tap-% env)
        (rewrite-infix-pass env)
        (rewrite-async-assert env)
        (rewrite-doc env)
diff --git a/test/hyperfiddle/rcf/cljs_test.cljs b/test/hyperfiddle/rcf/cljs_test.cljs
index a567d53..9867918 100644
--- a/test/hyperfiddle/rcf/cljs_test.cljs
+++ b/test/hyperfiddle/rcf/cljs_test.cljs
@@ -1,6 +1,6 @@
 (ns hyperfiddle.rcf.cljs-test
   (:require [clojure.core.async :refer [chan >! go go-loop <! timeout close!]]
-            [hyperfiddle.rcf :as rcf :refer [tests ! %]]
+            [hyperfiddle.rcf :as rcf :refer [tests tap %]]
             [missionary.core :as m]))
 
 (tests
@@ -62,9 +62,9 @@
  "async tests"
  (tests
   (defn set-timeout [f ms] (js/setTimeout ms f))
-  (rcf/! 1) (set-timeout 10 (fn []
-                              (rcf/! 2) (set-timeout 200 (fn []
-                                                           (rcf/! 3)))))
+  (rcf/tap 1) (set-timeout 10 (fn []
+                              (rcf/tap 2) (set-timeout 200 (fn []
+                                                           (rcf/tap 3)))))
   % := 1
   % := 2
   % := ::rcf/timeout))
@@ -75,7 +75,7 @@
  (go-loop [x (<! c)]
    (when x
      (<! (timeout 10))
-     (! x)
+     (tap x)
      (recur (<! c))))
  (go (>! c :hello) (>! c :world))
  % := :hello
@@ -85,7 +85,7 @@
 (tests
  "missionary"
  (def !x (atom 0))
- (def dispose ((m/reactor (m/stream! (m/ap (! (inc (m/?< (m/watch !x)))))))
+ (def dispose ((m/reactor (m/stream! (m/ap (tap (inc (m/?< (m/watch !x)))))))
                (fn [_] #_(prn ::done)) #(prn ::crash %)))
  % := 1
  (swap! !x inc)
diff --git a/test/hyperfiddle/rcf/example_test.clj b/test/hyperfiddle/rcf/example_test.clj
index 7de38c0..9f34413 100644
--- a/test/hyperfiddle/rcf/example_test.clj
+++ b/test/hyperfiddle/rcf/example_test.clj
@@ -1,11 +1,13 @@
 (ns hyperfiddle.rcf.example-test
   (:require [clojure.core.async :refer [chan >! go go-loop <! timeout close!]]
-            [hyperfiddle.rcf :as rcf :refer [tests ! % with]]
+            [hyperfiddle.rcf :as rcf :refer [tests tap % with]]
             [missionary.core :as m]))
 
+(rcf/enable!)
+
 (tests
- "equality"
- (inc 1) := 2)
+  "equality"
+  (inc 1) := 2)
 
 (tests
  "nested tests"
@@ -58,19 +60,19 @@
 
 (tests
  "Async queue"
- (! 1) % := 1
- (future (Thread/sleep 300) (! 2))
+ (tap 1) % := 1
+ (future (Thread/sleep 300) (tap 2))
  % := 2
  )
 
 (tests
- (tests (future (Thread/sleep 100) (! :a) :b) %)
+ (tests (future (Thread/sleep 100) (tap :a) :b) %)
  := :a)
 
 (tests
  "missionary"
  (def !x (atom 0))
- (def dispose ((m/reactor (m/stream! (m/ap (! (inc (m/?< (m/watch !x)))))))
+ (def dispose ((m/reactor (m/stream! (m/ap (tap (inc (m/?< (m/watch !x)))))))
                (fn [_] (prn ::done)) #(prn ::crash %)))
  % := 1
  (swap! !x inc)
@@ -86,7 +88,7 @@
  (go-loop [x (<! c)]
    (when x
      (<! (timeout 10))
-     (! x)
+     (tap x)
      (recur (<! c))))
  (go  (>! c :hello) (>! c :world))
  % := :hello
@@ -94,7 +96,7 @@
  (close! c))
 
 (tests
-  (def task (fn [success! failure!] (success! 1) (fn cancel [] (! ::dispose))))
-  (with (task ! !)
+  (def task (fn [success! failure!] (success! 1) (fn cancel [] (tap ::dispose))))
+  (with (task tap tap)
     % := 1)
   % := ::dispose)
diff --git a/test/hyperfiddle/rcf_test.cljc b/test/hyperfiddle/rcf_test.cljc
index 3caceb9..850da12 100644
--- a/test/hyperfiddle/rcf_test.cljc
+++ b/test/hyperfiddle/rcf_test.cljc
@@ -4,9 +4,9 @@
             #_[hyperfiddle.rcf.analyzer :as ana])
   #?(:cljs (:require-macros [hyperfiddle.rcf-test])))
 
-(deftest !-outside-tests
-  (is (= (with-out-str (rcf/! 1)) "1\n"))
-  (is (= (rcf/! 1) 1)))
+(deftest tap-outside-tests
+  (is (= (with-out-str (rcf/tap 1)) "1\n"))
+  (is (= (rcf/tap 1) 1)))
 
 (defmacro my-def [x]
   `(def ~(vary-meta x assoc