hymn 0.3

Hy Monad Notation - a monad library for Hy

Introduction

Hymn is a monad library for Hy/Python, with do notation for monad comprehension.

Code are better than words.

The continuation monad

=> (require hymn.dsl)
=> (import [hymn.types.continuation [cont-m call-cc]])
=> ;; computations in continuation passing style
=> (defn double [x] (cont-m.unit (* x 2)))
=> (def length (cont-m.monadic len))
=> ;; chain with bind
=> (.run (>> (cont-m.unit [1 2 3]) length double))
6
=> (defn square [n] (call-cc (fn [k] (k (** n 2)))))
=> (.run (square 12))
144
=> (.run (square 12) inc)
145
=> (.run (square 12) str)
'144'
=> (.run (do-monad [sqr (square 42)] (.format "answer^2 = {}" sqr)))
'answer^2 = 1764'

The either monad

=> (require hymn.dsl)
=> (import [hymn.types.either [Left Right either failsafe]])
=> ;; do notation with either monad
=> (do-monad [a (Right 1) b (Right 2)] (/ a b))
Right(0.5)
=> (do-monad [a (Right 1) b (Left 'nan)] (/ a b))
Left(nan)
=> ;; failsafe is a function decorator that wraps return value into either
=> (def safe-div (failsafe /))
=> ;; returns Right if nothing wrong
=> (safe-div 4 2)
Right(2.0)
=> ;; returns Left when bad thing happened, like exception being thrown
=> (safe-div 1 0)
Left(ZeroDivisionError('division by zero',))
=> ;; function either tests the value and call functions accordingly
=> (either print inc (safe-div 4 2))
3.0
=> (either print inc (safe-div 1 0))
division by zero

The identity monad

=> (require hymn.dsl)
=> (import [hymn.types.identity [identity-m]])
=> ;; do notation with identity monad is like let binding
=> (do-monad [a (identity-m 1) b (identity-m 2)] (+ a b))
Identity(3)

The lazy monad

=> (require hymn.dsl)
=> (import [hymn.types.lazy [force]])
=> ;; lazy computation implemented as monad
=> ;; macro lazy create deferred computation
=> (def a (lazy (print "evaluate a") 42))
=> ;; the computation is deferred, notice the value is shown as '_'
=> a
Lazy(_)
=> ;; evaluate it
=> (.evaluate a)
evaluate a
42
=> ;; now the value is cached
=> a
Lazy(42)
=> ;; evaluate again will not trigger the computation
=> (.evaluate a)
42
=> (def b (lazy (print "evaluate b") 21))
=> b
Lazy(_)
=> ;; force evaluate the computation, same as calling .evaluate on the monad
=> (force b)
evaluate b
21
=> ;; force on values other than lazy return the value unchanged
=> (force 42)
42
=> ;; do notation with lazy monad
=> (def c (do-monad [x (lazy (print "get x") 1) y (lazy (print "get y") 2)] (+ x y)))
=> ;; the computation is deferred
=> c
Lazy(_)
=> ;; do it!
=> (force c)
get x
get y
3
=> ;; again
=> (force c)
3

The list monad

=> (require hymn.dsl)
=> (import [hymn.types.list [list-m]])
=> ;; use list-m contructor to turn sequence into list monad
=> (def xs (list-m (range 2)))
=> (def ys (list-m (range 3)))
=> ;; do notation with list monad is list comprehension
=> (list (do-monad [x xs y ys :when (not (zero? y))] (/ x y)) )
[0.0, 0.0, 1.0, 0.5]
=> ;; * is the reader macro for list-m
=> (list (do-monad [x #*(range 2) y #*(range 3) :when (not (zero? y))] (/ x y)) )
[0.0, 0.0, 1.0, 0.5]

The maybe monad

=> (require hymn.dsl)
=> (import [hymn.types.maybe [Just Nothing maybe]])
=> ;; do notation with maybe monad
=> (do-monad [a (Just 1) b (Just 1)] (/ a b))
Just(1.0)
=> ;; Nothing yields Nothing
=> (do-monad [a Nothing b (Just 1)] (/ a b))
Nothing
=> ;; maybe is a function decorator that wraps return value into maybe
=> ;; a safe-div with maybe monad
=> (def safe-div (maybe /))
=> (safe-div 42 42)
Just(1.0)
=> (safe-div 42 'answer)
Nothing
=> (safe-div 42 0)
Nothing

The reader monad

=> (require hymn.dsl)
=> (import [hymn.types.reader [lookup]])
=> ;; do notation with reader monad, lookup assumes the environment is subscriptable
=> (def r (do-monad [a (lookup 'a) b (lookup 'b)] (+ a b)))
=> ;; run reader monad r with environment
=> (.run r {'a 1 'b 2})
3

The state monad

=> (require hymn.dsl)
=> (import [hymn.types.state [lookup set-value]])
=> ;; do notation with state monad, set-value sets the value with key in the state
=> (def s (do-monad [a (lookup 'a) _ (set-value 'b (inc a))] a))
=> ;; run state monad s with initial state
=> (.run s {'a 1})
(, 1 {'a 1 'b 2})

The writer monad

=> (require hymn.dsl)
=> (import [hymn.types.writer [tell]])
=> ;; do notation with writer monad
=> (do-monad [_ (tell "hello") _ (tell " world")] nil)
StrWriter((None, 'hello world'))
=> ;; int is monoid, too
=> (.execute (do-monad [_ (tell 1) _ (tell 2) _ (tell 3)] nil))
6

Operations on monads

=> (require hymn.dsl)
=> (import [hymn.operations [lift]])
=> ;; lift promotes function into monad
=> (def m+ (lift +))
=> ;; lifted function can work on any monad
=> ;; on the maybe monad
=> (import [hymn.types.maybe [Just Nothing]])
=> (m+ (Just 1) (Just 2))
Just(3)
=> (m+ (Just 1) Nothing)
Nothing
=> ;; on the either monad
=> (import [hymn.types.either [Left Right]])
=> (m+ (Right 1) (Right 2))
Right(3)
=> (m+ (Left 1) (Right 2))
Left(1)
=> ;; on the list monad
=> (import [hymn.types.list [list-m]])
=> (list (m+ (list-m "ab") (list-m "123")))
['a1', 'a2', 'a3', 'b1', 'b2', 'b3']
=> (list (m+ (list-m "+-") (list-m "123") (list-m "xy")))
['+1x', '+1y', '+2x', '+2y', '+3x', '+3y', '-1x', '-1y', '-2x', '-2y', '-3x', '-3y']
=> ;; can be used as normal function
=> (reduce m+ [(Just 1) (Just 2) (Just 3)])
Just(6)
=> (reduce m+ [(Just 1) Nothing (Just 3)])
Nothing
=> ;; <- is an alias of lookup
=> (import [hymn.types.reader [<-]])
=> ;; ^ is the reader macro for lift
=> (def p (#^print (<- 'message) :end (<- 'end)))
=> (.run p {'message "Hello world" 'end "!\n"})
Hello world!
=> ;; random number - linear congruential generator
=> (import [hymn.types.state [get-state set-state]])
=> (def random (>> get-state (fn [s] (-> s (* 69069) inc (% (** 2 32)) set-state))))
=> (.run random 1234)
(1234, 85231147)
=> ;; random can be even shorter by using modify
=> (import [hymn.types.state [modify]])
=> (def random (modify (fn [s] (-> s (* 69069) inc (% (** 2 32))))))
=> (.run random 1234)
(1234, 85231147)
=> ;; use replicate to do computation repeatly
=> (import [hymn.operations [replicate]])
=> (.evaluate (replicate 5 random) 42)
[42, 2900899, 2793697416, 2186085609, 1171637142]
=> ;; sequence on writer monad
=> (import [hymn.operations [sequence]])
=> (import [hymn.types.writer [tell]])
=> (.execute (sequence (map tell (range 1 101))))
5050

Using Hymn in Python

>>> from hymn.dsl import *
>>> sequence(map(tell, range(1, 101))).execute()
5050
>>> msum = lift(sum)
>>> msum(sequence(map(maybe(int), "12345")))
Just(15)
>>> msum(sequence(map(maybe(int), "12345a")))
Nothing
>>> @failsafe
... def safe_div(a, b):
...     return a / b
...
>>> safe_div(1.0, 2)
Right(0.5)
>>> safe_div(1, 0)
Left(ZeroDivisionError(...))

Requirements

• hy >= 0.11.0

Installation

Install from PyPI:

pip install hymn

Install from source, download source package, decompress, then cd into source directory, run:

make install

License

BSD New, see LICENSE for details.

Links

Documentation:

http://hymn.readthedocs.org/

Issue Tracker:

https://github.com/pyx/hymn/issues/

Source Package @ PyPI:

https://pypi.python.org/pypi/hymn/

Mercurial Repository @ bitbucket:

https://bitbucket.org/pyx/hymn/

Git Repository @ Github:

https://github.com/pyx/hymn/