Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/clj-commons/potemkin

some ideas which are almost good
https://github.com/clj-commons/potemkin

Last synced: about 2 months ago
JSON representation

some ideas which are almost good

Awesome Lists containing this project

README 

        
[![Clojars Project](https://img.shields.io/clojars/v/potemkin.svg)](https://clojars.org/potemkin)

[![cljdoc badge](https://cljdoc.org/badge/potemkin)](https://cljdoc.org/d/potemkin)

[![CircleCI](https://circleci.com/gh/clj-commons/potemkin.svg?style=svg)](https://circleci.com/gh/clj-commons/potemkin)



Potemkin is a collection of facades and workarounds for things that are more difficult than they should be.  All functions are within the `potemkin` namespace.



### Usage



##### Leiningen

```clojure

[potemkin "0.4.6"]

```



##### deps.edn

```clojure

potemkin/potemkin {:mvn/version "0.4.6"}

```



### `import-vars`



Clojure namespaces conflate the layout of your code and your API.  For larger libraries, this generally means that you either have large namespaces (e.g. clojure.core) or a large number of namespaces that have to be used in concert to accomplish non-trivial tasks (e.g. Ring).



The former approach places an onus on the creator of the library; the various orthogonal pieces of his library all coexist, which can make it difficult to keep everything straight. The latter approach places an onus on the consumers of the library, forcing them to remember exactly what functionality resides where before they can actually use it.



`import-vars` allows functions, macros, and values to be defined in one namespace, and exposed in another.  This means that the structure of your code and the structure of your API can be decoupled.



```clojure

(import-vars

  [clojure.walk

    prewalk

    postwalk]

  [clojure.data

    diff])

```



### `def-map-type`



A Clojure map implements the following interfaces: `clojure.lang.IPersistentCollection`, `clojure.lang.IPersistentMap`, `clojure.lang.Counted`, `clojure.lang.Seqable`, `clojure.lang.ILookup`, `clojure.lang.Associative`, `clojure.lang.IObj`, `java.lang.Object`, `java.util.Map`, `java.util.concurrent.Callable`, `java.lang.Runnable`, and `clojure.lang.IFn`.  Between them, there's a few dozen functions, many with overlapping functionality, all of which need to be correctly implemented.



Despite this, there are only six functions which really matter: `get`, `assoc`, `dissoc`, `keys`, `meta`, and `with-meta`.  `def-map-type` is a variant of `deftype` which, if those six functions are implemented, will look and act like a Clojure map.



For instance, here's a map which will automatically realize any delays, allowing for lazy evaluation semantics:



```clojure

(def-map-type LazyMap [m mta]

  (get [_ k default-value]

    (if (contains? m k)

      (let [v (get m k)]

        (if (instance? clojure.lang.Delay v)

          @v

          v))

      default-value))

  (assoc [_ k v]

    (LazyMap. (assoc m k v) mta))

  (dissoc [_ k]

     (LazyMap. (dissoc m k) mta))

  (keys [_]

    (keys m))

  (meta [_]

    mta)

  (with-meta [_ mta]

    (LazyMap. m mta)))

```



### `def-derived-map`



Often a map is just a view onto another object, especially when dealing with Java APIs.  While we can create a function which converts it into an entirely separate object, for both performance and memory reasons it can be useful to create a map which simply acts as a delegate to the underlying objects:



```clojure

(def-derived-map StringProperties [^String s]

  :base s

  :lower-case (.toLowerCase s)

  :upper-case (.toUpperCase s))

```



Each time the key `:lower-case` is looked up, it will invoke `.toLowerCase.  The resulting datatype behaves exactly like a normal Clojure map; new keys can be added and derived keys can be removed.



### `def-abstract-type` and `deftype+`



The reason it's so laborious to define a map-like data structure is because the implementation cannot be shared between different types.  For instance, `clojure.lang.ISeq` has both `next` and `more` methods.  However, while `more` can be implemented in terms of `next`, as it is in [clojure.lang.ASeq](https://github.com/clojure/clojure/blob/master/src/jvm/clojure/lang/ASeq.java#L129), within Clojure it must be reimplemented anew for each new type.



However, using `def-abstract-type`, we can avoid this:



```clojure

(def-abstract-type ASeq

  (more [this]

    (let [n (next this)]

      (if (empty? n)

        '()

        n)))))

```



This abstract type may be used within the body of `deftype+`, which is just like a vanilla `deftype` except for the support for abstract types.



```clojure

(deftype+ CustomSeq [s]

  ASeq

  clojure.lang.ISeq

  (seq [_] s)

  (cons [_ x] (CustomSeq. (cons x s)))

  (next [_] (CustomSeq. (next s))))

```



### `defprotocol+`



A drop in replacement for `defprotocol` that is more REPL-friendly.



A protocol created with Clojure's `defprotocol` always creates new instance at load time.

If a protocol is reloaded, a `defrecord` in another namespace that is referencing the procotol will not automatically be updated to the new protocol instance.



One telltale symptom of this disconnect can be a `No implementation of method` exception when calling record methods.



Potemkin's `defprotocol+` improves the REPL experience by only creating a new instance of a protocol if the procotol body has changed.



### `definterface+`



Every method on a type must be defined within a protocol or an interface.  The standard practice is to use `defprotocol`, but this imposes a certain overhead in both [time and memory](https://gist.github.com/ztellman/5603216).  Furthermore, protocols don't support primitive arguments.  If you need the extensibility of protocols, then there isn't another option, but often interfaces suffice.



While `definterface` uses an entirely different convention than `defprotocol`, `definterface+` uses the same convention, and automatically defines inline-able functions which call into the interface.  Thus, any protocol which doesn't require the extensibility can be trivially turned into an interface, with all the inherent savings.



### `unify-gensyms`



Gensyms enforce hygiene within macros, but when quote syntax is nested, they can become a pain.  This, for instance, doesn't work:



```clojure

`(let [x# 1]

   ~@(map

       (fn [n] `(+ x# ~n))

       (range 3)))

```



Because `x#` is going to expand to a different gensym in the two different contexts.  One way to work around this is to explicitly create a gensym ourselves:



```clojure

(let [x-sym (gensym "x")]

  `(let [~x-sym 1]

     ~@(map

         (fn [n] `(+ ~x-sym ~n))

         (range 3))))

```



However, this is pretty tedious, since we may need to define quite a few of these explicit gensym names.  Using `unify-gensyms`, however, we can rely on the convention that any var with two hashes at the end should be unified:



```clojure

(unify-gensyms

  `(let [x## 1]

     ~@(map

         (fn [n] `(+ x## ~n))

         (range 3)))

```



### License



Copyright © 2013 Zachary Tellman



Distributed under the [MIT License](http://opensource.org/licenses/MIT).  This means that pieces of this library may be copied into other libraries if they don't wish to have this as an explicit dependency, as long as it is credited within the code.