| Name | hymn JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | |
| Summary | Hy Monad Notation - a monad library for Hy |
| upload_time | 2024-01-07 01:37:20 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | <3.13,>=3.8 |
| license | BSD-New |
| keywords |
hy
lisp
monad
functional
programming
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
==========================================
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
.. code-block:: clojure
=> (import hymn.dsl [cont-m call/cc])
=> ;; computations in continuation passing style
=> (defn double [x] (cont-m.unit (* x 2)))
=> (setv 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) (fn [x] (+ x 1)))
145
=> (.run (square 12) str)
"144"
=> (require hymn.dsl [do-monad-return])
=> (.run (do-monad-return [sqr (square 42)] (.format "answer^2 = {}" sqr)))
"answer^2 = 1764"
The either monad
.. code-block:: clojure
=> (import hymn.dsl [Left Right either failsafe])
=> (require hymn.dsl [do-monad-return])
=> ;; do notation with either monad
=> (do-monad-return [a (Right 1) b (Right 2)] (/ a b))
Right(0.5)
=> (do-monad-return [a (Right 1) b (Left NaN)] (/ a b))
Left(nan)
=> ;; failsafe is a function decorator that wraps return value into either
=> (import hy.pyops [/])
=> (setv 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 calls functions accordingly
=> (either print (fn [x] (+ x 1)) (safe-div 4 2))
3.0
=> (either print (fn [x] (+ x 1)) (safe-div 1 0))
division by zero
The identity monad
.. code-block:: clojure
=> (import hymn.dsl [identity-m])
=> (require hymn.dsl [do-monad-return])
=> ;; do notation with identity monad is like let binding
=> (do-monad-return [a (identity-m 1) b (identity-m 2)] (+ a b))
Identity(3)
The lazy monad
.. code-block:: clojure
=> (import hymn.dsl [force])
=> (require hymn.dsl [lazy])
=> ;; lazy computation implemented as monad
=> ;; macro lazy creates deferred computation
=> (setv 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)
=> ;; calling evaluate again will not trigger the computation
=> (.evaluate a)
42
=> (setv 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
=> (require hymn.dsl [do-monad-return])
=> ;; do notation with lazy monad
=> (setv c (do-monad-return
... [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
.. code-block:: clojure
=> (import hymn.dsl [list-m])
=> (require hymn.dsl [do-monad-return])
=> ;; use list-m contructor to turn sequence into list monad
=> (setv xs (list-m (range 2)))
=> (setv ys (list-m (range 3)))
=> ;; do notation with list monad is list comprehension
=> (list (do-monad-return [x xs y ys :when (not (= 0 y))] (/ x y)))
[0.0 0.0 1.0 0.5]
=> (require hymn.dsl :readers [@])
=> ;; @ is the reader macro for list-m
=> (list
... (do-monad-return
... [x #@ (range 2)
... y #@ (range 3)
... :when (not (= 0 y))]
... (/ x y)))
[0.0 0.0 1.0 0.5]
The maybe monad
.. code-block:: clojure
=> (import hymn.dsl [Just Nothing maybe])
=> (require hymn.dsl [do-monad-return])
=> ;; do notation with maybe monad
=> (do-monad-return [a (Just 1) b (Just 1)] (/ a b))
Just(1.0)
=> ;; Nothing yields Nothing
=> (do-monad-return [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
=> (import hy.pyops [/])
=> (setv safe-div (maybe /))
=> (safe-div 42 42)
Just(1.0)
=> (safe-div 42 'answer)
Nothing
=> (safe-div 42 0)
Nothing
The reader monad
.. code-block:: clojure
=> (import hymn.dsl [lookup-reader])
=> (require hymn.dsl [do-monad-return])
=> ;; do notation with reader monad,
=> ;; lookup assumes the environment is subscriptable
=> (setv r (do-monad-return [a (lookup-reader 'a) b (lookup-reader 'b)] (+ a b)))
=> ;; run reader monad r with environment
=> (.run r {'a 1 'b 2})
3
The state monad
.. code-block::
=> (import hymn.dsl [lookup-state set-value])
=> (require hymn.dsl [do-monad-return])
=> ;; do notation with state monad,
=> ;; set-value sets the value with key in the state
=> (setv s (do-monad-return [x (lookup-state "a") _ (set-value "b" (+ x 1))] x))
=> ;; run state monad s with initial state
=> (.run s {"a" 1})
#(1 {"a" 1 "b" 2})
The writer monad
.. code-block:: clojure
=> (import hymn.dsl [tell])
=> (require hymn.dsl [do-monad-return])
=> ;; do notation with writer monad
=> (do-monad-return [_ (tell "hello") _ (tell " world")] None)
StrWriter((None, 'hello world'))
=> ;; int is monoid, too
=> (.execute (do-monad-return [_ (tell 1) _ (tell 2) _ (tell 3)] None))
6
Operations on monads
.. code-block:: clojure
=> (import hymn.dsl [lift])
=> ;; lift promotes function into monad
=> (import hy.pyops [+])
=> (setv m+ (lift +))
=> ;; lifted function can work on any monad
=> ;; on the maybe monad
=> (import hymn.dsl [Just Nothing])
=> (m+ (Just 1) (Just 2))
Just(3)
=> (m+ (Just 1) Nothing)
Nothing
=> ;; on the either monad
=> (import hymn.dsl [Left Right])
=> (m+ (Right 1) (Right 2))
Right(3)
=> (m+ (Left 1) (Right 2))
Left(1)
=> ;; on the list monad
=> (import hymn.dsl [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
=> (import functools [reduce])
=> (reduce m+ [(Just 1) (Just 2) (Just 3)])
Just(6)
=> (reduce m+ [(Just 1) Nothing (Just 3)])
Nothing
=> ;; <-r is an alias of lookup-reader
=> (import hymn.dsl [<-r])
=> (require hymn.dsl :readers [^])
=> ;; ^ is the reader macro for lift
=> (setv p (#^ print (<-r 'message) :end (<-r 'end)))
=> (.run p {'message "Hello world" 'end "!\n"})
Hello world!
=> ;; pseudo random number - linear congruential generator
=> (import hymn.dsl [state-m get-state set-state])
=> (setv random
... (>> get-state
... (fn [s] (state-m.unit (% (+ (* s 69069) 1) (** 2 32))))
... set-state))
=> (.run random 1234)
#(1234 85231147)
=> ;; random can be even shorter by using modify
=> (import hymn.dsl [modify])
=> (setv random (modify (fn [s] (% (+ (* s 69069) 1) (** 2 32)))))
=> (.run random 1234)
#(1234 85231147)
=> ;; use replicate to do computation repeatly
=> (import hymn.dsl [replicate])
=> (.evaluate (replicate 5 random) 42)
[42 2900899 2793697416 2186085609 1171637142]
=> ;; sequence on writer monad
=> (import hymn.dsl [sequence])
=> (import hymn.dsl [tell])
=> (.execute (sequence (map tell (range 1 101))))
5050
Using Hymn in Python
.. code-block:: 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.27.0
For hy version 0.19, please install hymn 0.9
For hy version 0.14, please install hymn 0.8
For hy version 0.13, please install hymn 0.7.
For hy version 0.12, please install hymn 0.6.
For hy version 0.11 and earlier, please install hymn 0.5.
See Changelog section in documentation for details.
Installation
============
Install from PyPI::
pip install hymn
License
=======
BSD New, see LICENSE for details.
Links
=====
Documentation:
https://hymn.readthedocs.io/
Issue Tracker:
https://github.com/pyx/hymn/issues/
Source Package @ PyPI:
https://pypi.python.org/pypi/hymn/
Git Repository @ Github:
https://github.com/pyx/hymn/
Git Repository @ Gitlab:
https://gitlab.com/pyx/hymn/
Raw data
{
"_id": null,
"home_page": "",
"name": "hymn",
"maintainer": "",
"docs_url": null,
"requires_python": "<3.13,>=3.8",
"maintainer_email": "",
"keywords": "hy lisp monad functional programming",
"author": "",
"author_email": "Philip Xu <pyx@xrefactor.com>",
"download_url": "https://files.pythonhosted.org/packages/8e/57/aa21e9d6bd3435886486a6d47635291c465d0df071d37c444b340b1fdc68/hymn-1.1.0.tar.gz",
"platform": null,
"description": "==========================================\nHy Monad Notation - a monad library for Hy\n==========================================\n\n\nIntroduction\n============\n\nHymn is a monad library for Hy/Python, with do notation for monad\ncomprehension.\n\nCode are better than words.\n\nThe continuation monad\n\n.. code-block:: clojure\n\n => (import hymn.dsl [cont-m call/cc])\n => ;; computations in continuation passing style\n => (defn double [x] (cont-m.unit (* x 2)))\n => (setv length (cont-m.monadic len))\n => ;; chain with bind\n => (.run (>> (cont-m.unit [1 2 3]) length double))\n 6\n => (defn square [n] (call/cc (fn [k] (k (** n 2)))))\n => (.run (square 12))\n 144\n => (.run (square 12) (fn [x] (+ x 1)))\n 145\n => (.run (square 12) str)\n \"144\"\n => (require hymn.dsl [do-monad-return])\n => (.run (do-monad-return [sqr (square 42)] (.format \"answer^2 = {}\" sqr)))\n \"answer^2 = 1764\"\n\nThe either monad\n\n.. code-block:: clojure\n\n => (import hymn.dsl [Left Right either failsafe])\n => (require hymn.dsl [do-monad-return])\n => ;; do notation with either monad\n => (do-monad-return [a (Right 1) b (Right 2)] (/ a b))\n Right(0.5)\n => (do-monad-return [a (Right 1) b (Left NaN)] (/ a b))\n Left(nan)\n => ;; failsafe is a function decorator that wraps return value into either\n => (import hy.pyops [/])\n => (setv safe-div (failsafe /))\n => ;; returns Right if nothing wrong\n => (safe-div 4 2)\n Right(2.0)\n => ;; returns Left when bad thing happened, like exception being thrown\n => (safe-div 1 0)\n Left(ZeroDivisionError('division by zero'))\n => ;; function either tests the value and calls functions accordingly\n => (either print (fn [x] (+ x 1)) (safe-div 4 2))\n 3.0\n => (either print (fn [x] (+ x 1)) (safe-div 1 0))\n division by zero\n\nThe identity monad\n\n.. code-block:: clojure\n\n => (import hymn.dsl [identity-m])\n => (require hymn.dsl [do-monad-return])\n => ;; do notation with identity monad is like let binding\n => (do-monad-return [a (identity-m 1) b (identity-m 2)] (+ a b))\n Identity(3)\n\nThe lazy monad\n\n.. code-block:: clojure\n\n => (import hymn.dsl [force])\n => (require hymn.dsl [lazy])\n => ;; lazy computation implemented as monad\n => ;; macro lazy creates deferred computation\n => (setv a (lazy (print \"evaluate a\") 42))\n => ;; the computation is deferred, notice the value is shown as '_'\n => a\n Lazy(_)\n => ;; evaluate it\n => (.evaluate a)\n evaluate a\n 42\n => ;; now the value is cached\n => a\n Lazy(42)\n => ;; calling evaluate again will not trigger the computation\n => (.evaluate a)\n 42\n => (setv b (lazy (print \"evaluate b\") 21))\n => b\n Lazy(_)\n => ;; force evaluate the computation, same as calling .evaluate on the monad\n => (force b)\n evaluate b\n 21\n => ;; force on values other than lazy return the value unchanged\n => (force 42)\n 42\n => (require hymn.dsl [do-monad-return])\n => ;; do notation with lazy monad\n => (setv c (do-monad-return\n ... [x (lazy (print \"get x\") 1)\n ... y (lazy (print \"get y\") 2)]\n ... (+ x y)))\n => ;; the computation is deferred\n => c\n Lazy(_)\n => ;; do it!\n => (force c)\n get x\n get y\n 3\n => ;; again\n => (force c)\n 3\n\nThe list monad\n\n.. code-block:: clojure\n\n => (import hymn.dsl [list-m])\n => (require hymn.dsl [do-monad-return])\n => ;; use list-m contructor to turn sequence into list monad\n => (setv xs (list-m (range 2)))\n => (setv ys (list-m (range 3)))\n => ;; do notation with list monad is list comprehension\n => (list (do-monad-return [x xs y ys :when (not (= 0 y))] (/ x y)))\n [0.0 0.0 1.0 0.5]\n => (require hymn.dsl :readers [@])\n => ;; @ is the reader macro for list-m\n => (list\n ... (do-monad-return\n ... [x #@ (range 2)\n ... y #@ (range 3)\n ... :when (not (= 0 y))]\n ... (/ x y)))\n [0.0 0.0 1.0 0.5]\n\nThe maybe monad\n\n.. code-block:: clojure\n\n => (import hymn.dsl [Just Nothing maybe])\n => (require hymn.dsl [do-monad-return])\n => ;; do notation with maybe monad\n => (do-monad-return [a (Just 1) b (Just 1)] (/ a b))\n Just(1.0)\n => ;; Nothing yields Nothing\n => (do-monad-return [a Nothing b (Just 1)] (/ a b))\n Nothing\n => ;; maybe is a function decorator that wraps return value into maybe\n => ;; a safe-div with maybe monad\n => (import hy.pyops [/])\n => (setv safe-div (maybe /))\n => (safe-div 42 42)\n Just(1.0)\n => (safe-div 42 'answer)\n Nothing\n => (safe-div 42 0)\n Nothing\n\nThe reader monad\n\n.. code-block:: clojure\n\n => (import hymn.dsl [lookup-reader])\n => (require hymn.dsl [do-monad-return])\n => ;; do notation with reader monad,\n => ;; lookup assumes the environment is subscriptable\n => (setv r (do-monad-return [a (lookup-reader 'a) b (lookup-reader 'b)] (+ a b)))\n => ;; run reader monad r with environment\n => (.run r {'a 1 'b 2})\n 3\n\nThe state monad\n\n.. code-block::\n\n => (import hymn.dsl [lookup-state set-value])\n => (require hymn.dsl [do-monad-return])\n => ;; do notation with state monad,\n => ;; set-value sets the value with key in the state\n => (setv s (do-monad-return [x (lookup-state \"a\") _ (set-value \"b\" (+ x 1))] x))\n => ;; run state monad s with initial state\n => (.run s {\"a\" 1})\n #(1 {\"a\" 1 \"b\" 2})\n\nThe writer monad\n\n.. code-block:: clojure\n\n => (import hymn.dsl [tell])\n => (require hymn.dsl [do-monad-return])\n => ;; do notation with writer monad\n => (do-monad-return [_ (tell \"hello\") _ (tell \" world\")] None)\n StrWriter((None, 'hello world'))\n => ;; int is monoid, too\n => (.execute (do-monad-return [_ (tell 1) _ (tell 2) _ (tell 3)] None))\n 6\n\nOperations on monads\n\n.. code-block:: clojure\n\n => (import hymn.dsl [lift])\n => ;; lift promotes function into monad\n => (import hy.pyops [+])\n => (setv m+ (lift +))\n => ;; lifted function can work on any monad\n => ;; on the maybe monad\n => (import hymn.dsl [Just Nothing])\n => (m+ (Just 1) (Just 2))\n Just(3)\n => (m+ (Just 1) Nothing)\n Nothing\n => ;; on the either monad\n => (import hymn.dsl [Left Right])\n => (m+ (Right 1) (Right 2))\n Right(3)\n => (m+ (Left 1) (Right 2))\n Left(1)\n => ;; on the list monad\n => (import hymn.dsl [list-m])\n => (list (m+ (list-m \"ab\") (list-m \"123\")))\n [\"a1\" \"a2\" \"a3\" \"b1\" \"b2\" \"b3\"]\n => (list (m+ (list-m \"+-\") (list-m \"123\") (list-m \"xy\")))\n [\"+1x\" \"+1y\" \"+2x\" \"+2y\" \"+3x\" \"+3y\" \"-1x\" \"-1y\" \"-2x\" \"-2y\" \"-3x\" \"-3y\"]\n => ;; can be used as normal function\n => (import functools [reduce])\n => (reduce m+ [(Just 1) (Just 2) (Just 3)])\n Just(6)\n => (reduce m+ [(Just 1) Nothing (Just 3)])\n Nothing\n => ;; <-r is an alias of lookup-reader\n => (import hymn.dsl [<-r])\n => (require hymn.dsl :readers [^])\n => ;; ^ is the reader macro for lift\n => (setv p (#^ print (<-r 'message) :end (<-r 'end)))\n => (.run p {'message \"Hello world\" 'end \"!\\n\"})\n Hello world!\n => ;; pseudo random number - linear congruential generator\n => (import hymn.dsl [state-m get-state set-state])\n => (setv random\n ... (>> get-state\n ... (fn [s] (state-m.unit (% (+ (* s 69069) 1) (** 2 32))))\n ... set-state))\n => (.run random 1234)\n #(1234 85231147)\n => ;; random can be even shorter by using modify\n => (import hymn.dsl [modify])\n => (setv random (modify (fn [s] (% (+ (* s 69069) 1) (** 2 32)))))\n => (.run random 1234)\n #(1234 85231147)\n => ;; use replicate to do computation repeatly\n => (import hymn.dsl [replicate])\n => (.evaluate (replicate 5 random) 42)\n [42 2900899 2793697416 2186085609 1171637142]\n => ;; sequence on writer monad\n => (import hymn.dsl [sequence])\n => (import hymn.dsl [tell])\n => (.execute (sequence (map tell (range 1 101))))\n 5050\n\nUsing Hymn in Python\n\n.. code-block:: python\n\n >>> from hymn.dsl import *\n >>> sequence(map(tell, range(1, 101))).execute()\n 5050\n >>> msum = lift(sum)\n >>> msum(sequence(map(maybe(int), \"12345\")))\n Just(15)\n >>> msum(sequence(map(maybe(int), \"12345a\")))\n Nothing\n >>> @failsafe\n ... def safe_div(a, b):\n ... return a / b\n ...\n >>> safe_div(1.0, 2)\n Right(0.5)\n >>> safe_div(1, 0)\n Left(ZeroDivisionError(...))\n\n\nRequirements\n============\n\n- hy >= 0.27.0\n\nFor hy version 0.19, please install hymn 0.9\n\nFor hy version 0.14, please install hymn 0.8\n\nFor hy version 0.13, please install hymn 0.7.\n\nFor hy version 0.12, please install hymn 0.6.\n\nFor hy version 0.11 and earlier, please install hymn 0.5.\n\nSee Changelog section in documentation for details.\n\n\nInstallation\n============\n\nInstall from PyPI::\n\n pip install hymn\n\n\nLicense\n=======\n\nBSD New, see LICENSE for details.\n\n\nLinks\n=====\n\nDocumentation:\n https://hymn.readthedocs.io/\n\nIssue Tracker:\n https://github.com/pyx/hymn/issues/\n\nSource Package @ PyPI:\n https://pypi.python.org/pypi/hymn/\n\nGit Repository @ Github:\n https://github.com/pyx/hymn/\n\nGit Repository @ Gitlab:\n https://gitlab.com/pyx/hymn/\n",
"bugtrack_url": null,
"license": "BSD-New",
"summary": "Hy Monad Notation - a monad library for Hy",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/pyx/hymn/"
},
"split_keywords": [
"hy",
"lisp",
"monad",
"functional",
"programming"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "527378245384eb3bb60c3e30b7ca3108e3d6b7a8ba9ee104ced6d0361581a0d5",
"md5": "80723d2ac73ae622521f3855f60199f5",
"sha256": "9943f332b3661ca03de078d64beec0de9166a03c9fc23344fae848262d50678a"
},
"downloads": -1,
"filename": "hymn-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "80723d2ac73ae622521f3855f60199f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8",
"size": 21435,
"upload_time": "2024-01-07T01:37:18",
"upload_time_iso_8601": "2024-01-07T01:37:18.794455Z",
"url": "https://files.pythonhosted.org/packages/52/73/78245384eb3bb60c3e30b7ca3108e3d6b7a8ba9ee104ced6d0361581a0d5/hymn-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8e57aa21e9d6bd3435886486a6d47635291c465d0df071d37c444b340b1fdc68",
"md5": "b256e0cf1b9206ab7b87755dad750834",
"sha256": "854e6e2db7490e80423c68b0248bd462679a8d38821dd39c2bd4202c97081f6d"
},
"downloads": -1,
"filename": "hymn-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b256e0cf1b9206ab7b87755dad750834",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8",
"size": 25776,
"upload_time": "2024-01-07T01:37:20",
"upload_time_iso_8601": "2024-01-07T01:37:20.612083Z",
"url": "https://files.pythonhosted.org/packages/8e/57/aa21e9d6bd3435886486a6d47635291c465d0df071d37c444b340b1fdc68/hymn-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-07 01:37:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyx",
"github_project": "hymn",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hymn"
}
