From ec05c142257e3fc246ce01e4e60b8dccb4b92180 Mon Sep 17 00:00:00 2001 From: Nathan Marz Date: Tue, 7 Jun 2016 14:34:32 -0400 Subject: [PATCH] document exact semantics of select*/transform* needed for Navigator --- src/clj/com/rpl/specter/protocols.cljx | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/clj/com/rpl/specter/protocols.cljx b/src/clj/com/rpl/specter/protocols.cljx index b448a9d..8ccbfc8 100644 --- a/src/clj/com/rpl/specter/protocols.cljx +++ b/src/clj/com/rpl/specter/protocols.cljx @@ -1,8 +1,20 @@ (ns com.rpl.specter.protocols) (defprotocol Navigator - (select* [this structure next-fn]) - (transform* [this structure next-fn])) + (select* [this structure next-fn] + "An implementation of `select*` must call `next-fn` on each + subvalue of `structure`. The result of `select*` is specified + as follows: + + 1. `NONE` if `next-fn` never called + 2. `NONE` if all calls to `next-fn` return `NONE` + 3. Otherwise, any non-`NONE` return value from calling `next-fn` + ") + (transform* [this structure next-fn] + "An implementation of `transform*` must use `next-fn` to transform + any subvalues of `structure` and then merge those transformed values + back into `structure`. Everything else in `structure` must be unchanged." + )) (defprotocol Collector (collect-val [this structure]))