runpipe, getvalue -> exitpipe

Technologicat · Technologicat · commit 055c808be9e0 · 2020-03-07T00:11:10.000+02:00
Rename and deprecation (waiting until 0.15 to ax the old names). Getting rid of
silly duplication by more descriptive naming.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -55,6 +55,7 @@ If you're still stuck on 3.4 and find something in the latest `unpythonic` 0.14.
 
 - `setescape`/`escape` have been renamed `catch`/`throw`, to match the standard terminology in the Lisp family. **The old nonstandard names are now deprecated, and will be removed in 0.15.0.**
 - The parameters of `raisef` are now more pythonic, just the object `exc` and an optional keyword-only `cause`. **Old-style parameters are now deprecated, and will be removed in 0.15.0.** See [#30](https://github.com/Technologicat/unpythonic/issues/30).
+- `runpipe` and `getvalue` are now both replaced by a single unified name `exitpipe`. This is just a rename, with no functionality changes. **The old names are now deprecated, and will be removed in 0.15.0.**
 - The `dbg[]` macro now works in the REPL, too. See [#12](https://github.com/Technologicat/unpythonic/issues/12).
 - The `namedlambda` block macro now also names lambdas that are:
   - Passed as a named argument of a function call, as in ``foo(f=lambda ...: ...)``; or
diff --git a/doc/features.md b/doc/features.md
@@ -727,40 +727,42 @@ assert x == 85
 
 We also provide ``pipec``, which curries the functions before applying them. Useful with passthrough (see below on ``curry``).
 
-Optional **shell-like syntax**, with purely functional updates:
+Optional **shell-like syntax**, with purely functional updates.
+
+*Changed in v0.14.2*. Both `getvalue` and `runpipe` are now known by the single unified name `exitpipe`. This is just a rename, with no functionality changes. The old names are now deprecated, and will be removed in 0.15.0.
 
 ```python
-from unpythonic import piped, getvalue
+from unpythonic import piped, exitpipe
 
-x = piped(42) | double | inc | getvalue
+x = piped(42) | double | inc | exitpipe
 assert x == 85
 
 p = piped(42) | double
 assert p | inc | getvalue == 85
-assert p | getvalue == 84  # p itself is never modified by the pipe system
+assert p | exitpipe == 84  # p itself is never modified by the pipe system
 ```
 
 Set up a pipe by calling ``piped`` for the initial value. Pipe into the sentinel ``getvalue`` to exit the pipe and return the current value.
 
-**Lazy pipes**, useful for mutable initial values. To perform the planned computation, pipe into the sentinel ``runpipe``:
+**Lazy pipes**, useful for mutable initial values. To perform the planned computation, pipe into the sentinel ``exitpipe``:
 
 ```python
-from unpythonic import lazy_piped1, runpipe
+from unpythonic import lazy_piped1, exitpipe
 
 lst = [1]
 def append_succ(l):
     l.append(l[-1] + 1)
     return l  # this return value is handed to the next function in the pipe
 p = lazy_piped1(lst) | append_succ | append_succ  # plan a computation
 assert lst == [1]        # nothing done yet
-p | runpipe              # run the computation
+p | exitpipe             # run the computation
 assert lst == [1, 2, 3]  # now the side effect has updated lst.
 ```
 
 Lazy pipe as an unfold:
 
 ```python
-from unpythonic import lazy_piped, runpipe
+from unpythonic import lazy_piped, exitpipe
 
 fibos = []
 def nextfibo(a, b):      # multiple arguments allowed
@@ -769,13 +771,13 @@ def nextfibo(a, b):      # multiple arguments allowed
 p = lazy_piped(1, 1)     # load initial state
 for _ in range(10):      # set up pipeline
     p = p | nextfibo
-p | runpipe
+p | exitpipe
 assert fibos == [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
 ```
 
 Both one-in-one-out (*1-to-1*) and n-in-m-out (*n-to-m*) pipes are provided. The 1-to-1 versions have names suffixed with ``1``. The use case is one-argument functions that return one value (which may also be a tuple).
 
-In the n-to-m versions, when a function returns a tuple, it is unpacked to the argument list of the next function in the pipe. At ``getvalue`` or ``runpipe`` time, the tuple wrapper (if any) around the final result is discarded if it contains only one item. (This allows the n-to-m versions to work also with a single value, as long as it is not a tuple.) The main use case is computations that deal with multiple values, the number of which may also change during the computation (as long as there are as many "slots" on both sides of each individual connection).
+In the n-to-m versions, when a function returns a tuple, it is unpacked to the argument list of the next function in the pipe. At ``exitpipe`` time, the tuple wrapper (if any) around the final result is discarded if it contains only one item. (This allows the n-to-m versions to work also with a single value, as long as it is not a tuple.) The main use case is computations that deal with multiple values, the number of which may also change during the computation (as long as there are as many "slots" on both sides of each individual connection).
 
 
 ## Batteries
diff --git a/unpythonic/seq.py b/unpythonic/seq.py
@@ -3,7 +3,7 @@
 
 __all__ = ["begin", "begin0", "lazy_begin", "lazy_begin0",
            "pipe1", "piped1", "lazy_piped1",
-           "pipe", "piped", "getvalue", "lazy_piped", "runpipe",
+           "pipe", "piped", "getvalue", "lazy_piped", "runpipe", "exitpipe",
            "pipec",  # w/ curry
            "do", "do0", "assign"]
 
@@ -144,6 +144,10 @@ def __repr__(self):
 getvalue = Getvalue()
 runpipe = getvalue  # same thing as getvalue, but semantically better name for lazy pipes
 
+# New unified name for v0.15.0; deprecating the separate "getvalue" and "runpipe" as of v0.14.2.
+# TODO: Now that we have symbols, in v0.15.0, change this to `sym("exitpipe")` and delete the `Getvalue` class.
+exitpipe = getvalue
+
 class piped1:
     """Shell-like piping syntax.
 
@@ -188,7 +192,7 @@ class lazy_piped1:
           the pipeline.
 
         - ``lazy_piped`` just sets up a computation, and performs it when eventually
-          piped into ``runpipe``. The computation always looks up the latest state
+          piped into ``exitpipe``. The computation always looks up the latest state
           of the initial value.
 
     Another way to say this is that ``lazy_piped`` looks up the initial value
@@ -204,7 +208,7 @@ def __init__(self, x, *, _funcs=None):
     def __or__(self, f):
         """Pipe the value into f; but just plan to do so, don't perform it yet.
 
-        To run the stored computation, pipe into ``runpipe``.
+        To run the stored computation, pipe into ``exitpipe``.
 
         Examples::
 
@@ -214,7 +218,7 @@ def append_succ(l):
                 return l  # important, handed to the next function in the pipe
             p = lazy_piped1(lst) | append_succ | append_succ  # plan a computation
             assert lst == [1]        # nothing done yet
-            p | runpipe              # run the computation
+            p | exitpipe              # run the computation
             assert lst == [1, 2, 3]  # now the side effect has updated lst.
 
             # lazy pipe as an unfold
@@ -226,10 +230,10 @@ def nextfibo(state):
             p = lazy_piped1((1, 1))  # load initial state into a lazy pipe
             for _ in range(10):      # set up pipeline
                 p = p | nextfibo
-            p | runpipe
+            p | exitpipe
             print(fibos)
         """
-        if f is runpipe:  # compute now
+        if f is exitpipe:  # compute now
             v = self._x
             for g in self._funcs:
                 v = g(v)
@@ -340,7 +344,7 @@ class lazy_piped:
         p3 = p2 | (lambda x, y, s: (x * 2, y + 1, "got {}".format(s)))
         p4 = p3 | (lambda x, y, s: (x + y, s))
         # nothing done yet!
-        assert (p4 | runpipe) == (13, "got foo")
+        assert (p4 | exitpipe) == (13, "got foo")
 
         # lazy pipe as an unfold
         fibos = []
@@ -350,7 +354,7 @@ def nextfibo(a, b):    # now two arguments
         p = lazy_piped(1, 1)
         for _ in range(10):
             p = p | nextfibo
-        p | runpipe
+        p | exitpipe
         print(fibos)
     """
     def __init__(self, *xs, _funcs=None):
@@ -362,7 +366,7 @@ def __init__(self, *xs, _funcs=None):
         self._funcs = _funcs or ()
     def __or__(self, f):
         """Pipe the values into f; but just plan to do so, don't perform it yet."""
-        if f is runpipe:  # compute now
+        if f is exitpipe:  # compute now
             vs = self._xs
             for g in self._funcs:
                 if isinstance(vs, tuple):
diff --git a/unpythonic/test/test_seq.py b/unpythonic/test/test_seq.py
@@ -2,8 +2,8 @@
 
 from ..seq import begin, begin0, lazy_begin, lazy_begin0, \
                   pipe1, pipe, pipec, \
-                  piped1, piped, getvalue, \
-                  lazy_piped1, lazy_piped, runpipe, \
+                  piped1, piped, exitpipe, \
+                  lazy_piped1, lazy_piped, \
                   do, do0, assign
 
 from ..ec import call_ec
@@ -69,11 +69,11 @@ def test():
         assert False  # error if the curry context exits with args remaining
 
     # optional shell-like syntax
-    assert piped1(42) | double | inc | getvalue == 85
+    assert piped1(42) | double | inc | exitpipe == 85
 
     y = piped1(42) | double
-    assert y | inc | getvalue == 85
-    assert y | getvalue == 84  # y is never modified by the pipe system
+    assert y | inc | exitpipe == 85
+    assert y | exitpipe == 84  # y is never modified by the pipe system
 
     # lazy pipe: compute later
     lst = [1]
@@ -82,7 +82,7 @@ def append_succ(l):
         return l  # important, handed to the next function in the pipe
     p = lazy_piped1(lst) | append_succ | append_succ  # plan a computation
     assert lst == [1]        # nothing done yet
-    p | runpipe              # run the computation
+    p | exitpipe              # run the computation
     assert lst == [1, 2, 3]  # now the side effect has updated lst.
 
     # lazy pipe as an unfold
@@ -94,28 +94,28 @@ def nextfibo(state):
     p = lazy_piped1((1, 1))  # load initial state into a lazy pipe
     for _ in range(10):      # set up pipeline
         p = p | nextfibo
-    p | runpipe
+    p | exitpipe
     assert fibos == [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
 
     # multi-arg version
     f = lambda x, y: (2 * x, y + 1)
     g = lambda x, y: (x + 1, 2 * y)
-    x = piped(2, 3) | f | g | getvalue  # --> (5, 8)
+    x = piped(2, 3) | f | g | exitpipe  # --> (5, 8)
     assert x == (5, 8)
 
     # abuse multi-arg version for single-arg case
-    assert piped(42) | double | inc | getvalue == 85
+    assert piped(42) | double | inc | exitpipe == 85
 
     # multi-arg lazy pipe
     p1 = lazy_piped(2, 3)
     p2 = p1 | (lambda x, y: (x + 1, 2 * y, "foo"))
     p3 = p2 | (lambda x, y, s: (x * 2, y + 1, "got {}".format(s)))
     p4 = p3 | (lambda x, y, s: (x + y, s))
     # nothing done yet, and all computations purely functional:
-    assert (p1 | runpipe) == (2, 3)
-    assert (p2 | runpipe) == (3, 6, "foo")      # runs the chain up to p2
-    assert (p3 | runpipe) == (6, 7, "got foo")  # runs the chain up to p3
-    assert (p4 | runpipe) == (13, "got foo")
+    assert (p1 | exitpipe) == (2, 3)
+    assert (p2 | exitpipe) == (3, 6, "foo")      # runs the chain up to p2
+    assert (p3 | exitpipe) == (6, 7, "got foo")  # runs the chain up to p3
+    assert (p4 | exitpipe) == (13, "got foo")
 
     # multi-arg lazy pipe as an unfold
     fibos = []
@@ -125,7 +125,7 @@ def nextfibo(a, b):    # now two arguments
     p = lazy_piped(1, 1)
     for _ in range(10):
         p = p | nextfibo
-    p | runpipe
+    p | exitpipe
     assert fibos == [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
 
     # do: improved begin() that can name intermediate results
