3 API Reference

contents ← prev up next →

3 API Reference🔗

syntax
(~> form clause ...)

clause = bare-id
| 'datum
| (head arg ...)
| (pre ... _ post ...)

“Threads” form through each clause, from top to bottom, as described in How ~> works. More precisely, ~> expands according to the following rules:

(~> form) expands to simply form.
(~> form bare-id) expands to (bare-id form).
(~> form 'datum) expands to ('datum form).
(~> form (head arg ...)) expands to (head form arg ...)
(~> form (pre ... _ post ...)) expands to (pre ... form post ...).
(~> form clause1 clause2 ...) expands to (~> (~> form clause1) clause2 ...).

The special treatment of 'datum clauses is unlikely to be useful to programs written in #lang racket, but it may be useful in languages that provide an alternate binding for #%app.

Examples:

> (~> '(1 2 3)
      (map add1 _)
      second
      (* 2))
6
> (~> "foo"
      string->bytes/utf-8
      bytes->list
      (map (λ~> (* 2)) _)
      list->bytes)
#"\314\336\336"

Changed in version 1.3 of package threading-lib: Removed the restriction that at least one pre form must be present in a clause containing _.

syntax
(lambda~> clause ...)
syntax
(λ~> clause ...)

Equivalent to (λ (x) (~> x clause ...)).

Example:

> (map (λ~> add1 (* 2)) (range 5))
'(2 4 6 8 10)

syntax
(lambda~>* clause ...)
syntax
(λ~>* clause ...)

Equivalent to (λ args (~> args clause ...)).

Example:

> ((λ~>* second sqr) 1 2 3)
4

syntax
(and~> expr clause ...)

Works like ~>, but if any of the intermediate expressions returns #f, threading stops, and the result of the whole expression is #f. Like and, and~> is short-circuiting, so the remaining steps will not be evaluated.

Examples:

> (and~> '(1 3 5)
         (map add1 _)
         (findf even? _))
2
> (and~> '(2 4 6)
         (map add1 _)
         (findf even? _))
#f

syntax
(tee~> expr clause ...)

See Pipeline splitting: tee~> for an example of using tee~>.

Evaluates expr, then threads the result through each clause as in ~>. The result of expr is the result of the tee~> expression.

tee~> is equivalent to the following:

(let ([tmp expr])
(~> tmp clause ...)
tmp)

Added in version 2.0 of package threading-lib.

3.1 Conditional Operators🔗

syntax
(when~> val-expr test-expr clause ...)

Evaluates val-expr and test-expr. If the result of test-expr is #f, the result of the when~> expression is the result of val-expr. Otherwise, the result of val-expr is threaded through each clause as in ~>.

when~> is equivalent to the following:

(let ([tmp val-expr])
  (if test-expr
      (~> tmp clause ...)
      tmp))

The when~> form is intended to be used as part of a larger ~> pipeline; see Conditional pipelines: when~>, unless~>, and cond~> for an example.

Added in version 2.0 of package threading-lib.

syntax
(unless~> val-expr test-expr clause ...)

Equivalent to (when~> val-expr (not test-expr) clause ...).

Added in version 2.0 of package threading-lib.

syntax
(cond~> val-expr cond-clause ... maybe-else-clause)

cond-clause = [test-expr clause ...]

maybe-else-clause =
| [else clause ...]

Evaluates val-expr, then evaluates each test-expr, from top to bottom, until one of them produces a value other than #f. The result of val-expr is threaded through each clause associated with the test-expr that produced a non-#f value.

If all test-expr expressions produce #f and an else clause was provided, the result of val-expr is threaded through each clause contained in the else clause. Otherwise, the result is the result of val-expr.

cond~> is equivalent to the following:

(let ([tmp val-expr])
  (cond
    [test-expr (~> tmp clause ...)] ...
    [else (~> tmp clause ...)]))

Like when~>, cond~> is intended to be used as a part of a larger ~> pipeline.

Examples:

> (define (f n)
    (~> 11
        (cond~>
          [(= n 1) add1 (* 2)]
          [(= n 2) sub1 (/ 2)]
          [else    -])))
> (f 1)
24
> (f 2)
5
> (f 3)
-11

Added in version 2.0 of package threading-lib.

3.2 Deprecated Forms🔗

syntax
(~>> form clause ...)

NOTE: This form is deprecated; use ~>, instead.

Equivalent to ~>, except that form is inserted at the end of a clause of the form (head arg ...), rather than between the head and arg forms.

Changed in version 2.0 of package threading-lib: Deprecated in favor of using ~> with _.

syntax
(and~>> expr clause ...)

NOTE: This form is deprecated; use and~>, instead.

Combines the threading behavior of ~>> and the short-circuiting behavior of and~>.

Changed in version 2.0 of package threading-lib: Deprecated in favor of using and~> with _.

syntax
(lambda~>> clause ...)
syntax
(λ~>> clause ...)
syntax
(lambda~>>* clause ...)
syntax
(λ~>>* clause ...)
syntax
(lambda-and~> clause ...)
syntax
(λ-and~> clause ...)
syntax
(lambda-and~>> clause ...)
syntax
(λ-and~>> clause ...)
syntax
(lambda-and~>* clause ...)
syntax
(λ-and~>* clause ...)
syntax
(lambda-and~>>* clause ...)
syntax
(λ-and~>>* clause ...)

NOTE: This form is deprecated; use lambda~>, lambda~>*, and and~>, instead.

Like lambda~>, but uses ~>> instead of ~>.

Changed in version 2.0 of package threading-lib: Deprecated in favor of combining other forms.

contents ← prev up next →

1	Introduction: Reducing nesting with ~>
2	Pipeline Helpers
3	API Reference