The arrows Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The arrows Reference Manual

This is the arrows Reference Manual, version 0.2.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Apr 08 12:56:16 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Arrows

Implements threading macros, inspired by Clojure (both core and the swiss-arrows library).

This is an ASDF system providing the package arrows. Its home is at https://gitlab.com/Harleqin/arrows, with a mirror at https://github.com/Harleqin/arrows.

Overview

You get:

As far as I see, ->* and as->* are new. Their purpose is to be nested in other threading forms to temporarily supplant their behaviour (see “Nesting” below).

Other arrow libraries

Notable differences to Clojure and swiss-arrows

Notable differences to arrow-macros

Nesting

One useful idiom is to nest these arrows. The basic example is to use ->> inside ->:

(-> deeply-nested-plist
    (getf :foo)
    (getf :bar)
    (->> (mapcar #'reverse)))

This inspired the discovery of ->*, which enables the inverse nesting:

(->> deeply-nested-alist
     (assoc :foo)
     cdr
     (assoc :bar)
     cdr
     (->* (mod 3))
     (expt 2))

Generally useful for overriding defaults are as-> and as->*:

(-> 3
    (as-> $
          (< x $ y))
    not)

(some->> 15
         (as->* $
                (progn
                  (format t debug-formatter $)
                  $))
         (/ 75))

However, don't overdo it! This quickly leads to an unreadable mess. You may well be better off with a few explicit let bindings.

Documentation

-> initial-form &rest forms => results

[macro] Inserts INITIAL-FORM as first argument into the first of FORMS, the result into the next, etc., before evaluation. FORMS are treated as list designators.

->> initial-form &rest forms => results

[macro] Like ->, but the forms are inserted as last argument instead of first.

->* &rest forms => results

[macro] Like ->, but the last form is used as initial form, then the remainung forms as in ->. This is intended for inversing the default in a ->> form.

-<> initial-form &rest forms => results

[macro] Like ->, but if a form in FORMS has one or more symbols named <> as top-level element, each such symbol is substituted by the primary result of the form accumulated so far, instead of it being inserted as first argument. Also known as diamond wand.

-<>> initial-form &rest forms => results

[macro] Like -<>, but if a form in FORMS has no symbols named <> as top-level element, insertion is done like in ->>. Also known as diamond spear.

as-> initial-form var &rest forms => results

[macro] Binds INITIAL-FORM to VAR, then successively each of FORMS to VAR, finally returns the last value of VAR.

as->* var &rest forms => results

[macro] Shorthand for the combination of ->* and as->: the last form is used for initial binding, then the remaining forms used as in as->. This is intended for overriding the default in a ->> form.

some-> initial-form &rest forms => results

[macro] Like ->, but short-circuits to nil as soon as either INITIAL-FORM or any of FORMS return nil. This is like all these forms are lifted to the maybe monad.

some->> initial-form &rest forms => results

[macro] Like some->, but with insertion behaviour as in ->>.

cond-> initial-form &rest clauses => results

[macro] CLAUSES is a list of clauses similar to COND clauses, each clause comprising first a test form, then a body of further forms. Cond-> evaluates INITIAL-FORM to a value, then for each clause whose test evaluates to true, pipes (as in ->) the value through each form in the body of the clause. Note that unlike in COND, there is no short-circuiting: each clause gets tested regardless of the outcome of the clauses before.

cond->> initial-form &rest clauses => results

[macro] Like cond->, but with insertion behaviour as in ->>.

Examples

(-> 3
    /)  ; insert into designated list (/)
=> 1/3

(-> 3
    (expt 2))  ; insert as first argument
=> 9

(->> 3
     (expt 2))  ; insert as last argument
=> 8

(-<>> (list 1 2 3)
      (remove-if #'oddp <> :count 1 :from-end t) ; substitute <>
      (reduce #'+)                               ; insert last
      /)                                         ; list designator
=> 1/3

(let ((x 3))
  (-<> (incf x)     ; (let ((r (incf x)))
       (+ <> <>)))  ;   (+ r r))
=> 8

(->> 3
     (/ 12)         ; (/ 12 3) => 4
     (->* (/ 2)))   ; (/ 4 2)  => 2
=> 2

(flet ((say (n)
         (cond->> nil
                  ((zerop (mod n 3)) (cons "Fizz"))
                  ((zerop (mod n 5)) (cons "Buzz"))
                  (t (->* (or (list (princ-to-string n))))
                     reverse
                     (apply #'concatenate 'string)))))
  (mapcar #'say '(9 10 11 12 13 14 15)))
=> ("Fizz" "Buzz" "11" "Fizz" "1

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 arrows

Author

Svante von Erichsen <svante.v.erichsen@web.de>

License

CC0

Description

Implements -> and ->> from Clojure, as well as several expansions on the idea.

Version

0.2.0

Source

arrows.asd (file)

Component

arrows.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 arrows.asd

Location

arrows.asd

Systems

arrows (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 arrows/arrows.lisp

Parent

arrows (system)

Location

arrows.lisp

Packages

arrows

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 arrows

Source

arrows.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: -<> INITIAL-FORM &rest FORMS

Like ->, but if a form in FORMS has one or more symbols named <> as top-level element, each such symbol is substituted by the primary result of the form accumulated so far, instead of it being inserted as first argument. Also known as diamond wand.

Package

arrows

Source

arrows.lisp (file)

Macro: -<>> INITIAL-FORM &rest FORMS

Like -<>, but if a form has no symbol named <>, the insertion is done at the end like in ->>. Also known as diamond spear.

Package

arrows

Source

arrows.lisp (file)

Macro: -> INITIAL-FORM &rest FORMS

Inserts INITIAL-FORM as first argument into the first of FORMS, the result into the next, etc., before evaluation. FORMS are treated as list designators.

Package

arrows

Source

arrows.lisp (file)

Macro: ->* &rest FORMS

Like ->, but the last form is used as initial form, then the remaining forms used as in ->. This is intended for inversing the default in a ->> form.

Example:

(->> 3
(/ 12)
(->* (/ 2)))
=> 2

Package

arrows

Source

arrows.lisp (file)

Macro: ->> INITIAL-FORM &rest FORMS

Like ->, but the forms are inserted as last argument instead of first.

Package

arrows

Source

arrows.lisp (file)

Macro: as-> INITIAL-FORM VAR &rest FORMS

Binds INITIAL-FORM to VAR, then successively each of FORMS to VAR, finally returns the last value of VAR.

Package

arrows

Source

arrows.lisp (file)

Macro: as->* VAR &rest FORMS

Shorthand for the combination of ->* and as->: the last form is used for initial binding, then the remaining forms used as in as->. This is intended for overriding the default in a ->> form.

Package

arrows

Source

arrows.lisp (file)

Macro: cond-> INITIAL-FORM &rest CLAUSES

CLAUSES is a list of clauses similar to COND clauses, each clause comprising first a test form, then a body of further forms. Cond-> evaluates INITIAL-FORM to a value, then for each clause whose test evaluates to true, pipes (as in ->) the value through each form in the body of the clause. Note that unlike in COND, there is no short-circuiting: each clause gets tested regardless of the outcome of the clauses before.

Package

arrows

Source

arrows.lisp (file)

Macro: cond->> INITIAL-FORM &rest CLAUSES

Like cond->, but with insertion behaviour as in ->>.

Package

arrows

Source

arrows.lisp (file)

Macro: some-> INITIAL-FORM &rest FORMS

Like ->, but short-circuits to nil as soon as either INITIAL-FORM or any of FORMS return nil. This is like all these forms are lifted to the maybe monad.

Package

arrows

Source

arrows.lisp (file)

Macro: some->> INITIAL-FORM &rest FORMS

Like some->, but with insertion behaviour as in ->>.

Package

arrows

Source

arrows.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: <>p FORM

Predicate identifying the placeholders for the -<> and -<>> macros.

Package

arrows

Source

arrows.lisp (file)

Function: cond-inserter INSERT-FUN
Package

arrows

Source

arrows.lisp (file)

Function: diamond-inserter INSERT-FUN
Package

arrows

Source

arrows.lisp (file)

Function: expand-arrow INITIAL-FORM FORMS INSERT-FUN
Package

arrows

Source

arrows.lisp (file)

Function: expand-cond INITIAL-FORM CLAUSES INSERT-FUN
Package

arrows

Source

arrows.lisp (file)

Function: expand-some INITIAL-FORM FORMS INSERT-FUN
Package

arrows

Source

arrows.lisp (file)

Function: insert-first ARG SURROUND

Inserts ARG into the list form SURROUND as its first argument, after the operator.

Package

arrows

Source

arrows.lisp (file)

Function: insert-last ARG SURROUND

Inserts ARG into the list form SURROUND as its last argument.

Package

arrows

Source

arrows.lisp (file)

Function: simple-inserter INSERT-FUN
Package

arrows

Source

arrows.lisp (file)

Function: some-inserter INSERT-FUN
Package

arrows

Source

arrows.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   A   F   L  
Index Entry  Section

A
arrows.asd: The arrows<dot>asd file
arrows/arrows.lisp: The arrows/arrows<dot>lisp file

F
File, Lisp, arrows.asd: The arrows<dot>asd file
File, Lisp, arrows/arrows.lisp: The arrows/arrows<dot>lisp file

L
Lisp File, arrows.asd: The arrows<dot>asd file
Lisp File, arrows/arrows.lisp: The arrows/arrows<dot>lisp file

Jump to:   A   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   -   <  
A   C   D   E   F   I   M   S  
Index Entry  Section

-
-<>: Exported macros
-<>>: Exported macros
->: Exported macros
->*: Exported macros
->>: Exported macros

<
<>p: Internal functions

A
as->: Exported macros
as->*: Exported macros

C
cond->: Exported macros
cond->>: Exported macros
cond-inserter: Internal functions

D
diamond-inserter: Internal functions

E
expand-arrow: Internal functions
expand-cond: Internal functions
expand-some: Internal functions

F
Function, <>p: Internal functions
Function, cond-inserter: Internal functions
Function, diamond-inserter: Internal functions
Function, expand-arrow: Internal functions
Function, expand-cond: Internal functions
Function, expand-some: Internal functions
Function, insert-first: Internal functions
Function, insert-last: Internal functions
Function, simple-inserter: Internal functions
Function, some-inserter: Internal functions

I
insert-first: Internal functions
insert-last: Internal functions

M
Macro, -<>: Exported macros
Macro, -<>>: Exported macros
Macro, ->: Exported macros
Macro, ->*: Exported macros
Macro, ->>: Exported macros
Macro, as->: Exported macros
Macro, as->*: Exported macros
Macro, cond->: Exported macros
Macro, cond->>: Exported macros
Macro, some->: Exported macros
Macro, some->>: Exported macros

S
simple-inserter: Internal functions
some->: Exported macros
some->>: Exported macros
some-inserter: Internal functions

Jump to:   -   <  
A   C   D   E   F   I   M   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   A   P   S  
Index Entry  Section

A
arrows: The arrows system
arrows: The arrows package

P
Package, arrows: The arrows package

S
System, arrows: The arrows system

Jump to:   A   P   S