# -*- coding: utf-8 -*-

"""The Reader monad — a read-only shared environment.

**Mind-bending parts inside.**

Something between a container and a computation. On the one hand,

``Reader e a`` is essentially just the function type ``e -> a`` with a

monad API wrapped around it; on the other, like ``State``, the

environment only becomes bound when we ``.run`` the Reader — until

then, everything is just planning.

A ``Reader e a`` wraps a function ``e -> a``, where ``e`` is some

environment (configuration, dependency-injection context, etc.). Binding

threads a single environment ``e`` through the chain; each sub-computation

can ``.ask()`` for the environment and do something with it.

Does **not** inherit from ``LiftableMonad`` — the teaching code leaves

``Reader.lift`` unimplemented, and there's no canonical shape for it.

Based on:

- https://wiki.haskell.org/Monads_as_containers

- https://www.mjoldfield.com/atelier/2014/08/monads-reader.html

- https://blog.ssanj.net/posts/2014-09-23-A-Simple-Reader-Monad-Example.html

- https://stackoverflow.com/questions/14178889/what-is-the-purpose-of-the-reader-monad

"""

__all__ = ["Reader"]

from collections.abc import Callable

from typing import Any

from .abc import Monad

class Reader(Monad):

"""The Reader monad. Wraps a function ``e -> a``.

**What bind does**: taking a computation that may read from the

environment before producing a value of type ``a``, and a function

from values of type ``a`` to computations that may read from the

environment before returning a value of type ``b``, and composing

these — yielding a computation that may read from the (shared)

environment before returning a value of type ``b``.

Uses the default ``Monad.__rshift__`` (``fmap . join``); no override

needed, the generic definition fits Reader perfectly.

Usage::

from unpythonic.monads import Reader

# A config-reading chain.

config = {"multiplier": 3, "offset": 10}

chain = (Reader.asks(lambda e: e["multiplier"])

>> (lambda m: Reader.asks(lambda e: e["offset"])

>> (lambda o: Reader.unit(m * 5 + o))))

result = chain.run(config)

# result == 25

"""

def __init__(self, f: Callable) -> None:

"""Wrap a reader function ``f: e -> a``.

Essentially, ``Reader e a = (e -> a)``, with a thin monad wrapper.

"""

if not callable(f):

raise TypeError(f"Expected a callable e -> a, got {f!r}")

self.r = f

@classmethod

def unit(cls, x: Any) -> "Reader":

"""Unit: ``a -> Reader e a``. Ignores the environment."""

return cls(lambda _: x)

def run(self, env: Any) -> Any:

"""Run the reader against an environment ``env: e``. Returns ``a``."""

return self.r(env)

@classmethod

def ask(cls) -> "Reader":

"""Yield the environment itself as the data value. ``-> Reader e e``."""

return cls(lambda env: env)

@classmethod

def asks(cls, f: Callable) -> "Reader":

"""Apply ``f: e -> a`` to the environment; yield ``a`` as data."""

return cls.ask() >> (lambda env: cls.unit(f(env)))

def local(self, f: Callable) -> "Reader":

"""Run this computation in an ``f``-modified environment. ``f: e -> e``."""

return self.__class__(lambda env: self.run(f(env)))

def fmap(self, f: Callable) -> "Reader":

"""``fmap: Reader e a -> (a -> b) -> Reader e b``"""

cls = self.__class__

return cls(lambda env: f(self.run(env)))

def join(self) -> "Reader":

"""``join: Reader e (Reader e a) -> Reader e a``

Given a reader that yields another reader, run the outer reader to

get the inner, then run the inner with the same environment.

"""

cls = self.__class__

return cls(lambda env: self.run(env).run(env))

def __repr__(self) -> str: # pragma: no cover

return f"{self.__class__.__name__}({self.r!r})"