defmodule Kino do
  @moduledoc ~S'''
  Client-driven interactive widgets for Livebook.

  Kino is the library used by Livebook to render rich and interactive
  outputs directly from your Elixir code.

  ## Getting started

  Livebook is distributed with a set of interactive tutorials and
  examples, including some that specifically focus on Kino. If you're
  just getting started, going through these is highly recommended.

  You can access these notebooks by starting Livebook and clicking
  on "Learn" in the sidebar.

  ## Built-in kinos

  Kino provides several built-in kinos. The `Kino.Shorts` module
  provides a facade to access and use most of the Kinos in this
  project, although you can also use their modules directly as
  listed in the sidebar.

  For user interactions, `Kino.Input` and `Kino.Control` provide
  a set of widgets for entering data and capturing user events.
  See the respective module documentation for examples.

  Kino also provides facilities to aid debugging, such as
  `Kino.Process` and a custom `dbg()` implementation that integrates
  with Livebook.

  ## Custom kinos

  Kino renders any data structure that implements the `Kino.Render`
  protocol, falling back to the `Kernel.inspect/2` representation
  whenever an implementation is not available. You can customize
  how your own data structures are rendered by implementing the
  `Kino.Render` protocol.

  You can also implement your own kinos by writing custom JavaScript,
  see `Kino.JS` and `Kino.JS.Live` for more details.

  > #### Packaging {: .info}
  > When publishing custom kinos and smart cells, please consider
  > the following guidelines:
  >   * prefix package name with `kino_`, usually followed by the
  >     name of the integration, such as `kino_vega_lite`, `kino_ecto`
  >   * namespace all modules under `KinoExample`, not `Kino.Example`.
  >     Note that official packages maintained by the Livebook team
  >     expose public APIs under `Kino.`, because they are essentially
  >     direct extensions of `Kino` and we make sure no conflicting
  >     modules exist. Unofficial packages should follow the usual
  >     Elixir conventions with respect to module names

  import Kernel, except: [inspect: 1]

  require Logger

  @type nothing :: :"do not show this result in output"

  @doc """
  Renders the given term as cell output.

  This effectively allows any Livebook cell to have multiple
  evaluation results.
  @spec render(term()) :: term()
  def render(term) do
    output = Kino.Render.to_livebook(term)

  @doc """
  Inspects the given term as cell output.

  This works essentially the same as `IO.inspect/2`, except it
  always produces colored text and respects the configuration
  set with `configure/1`.

  Opposite to `render/1`, it does not attempt to render the given
  term as a kino.
  @spec inspect(term(), keyword()) :: term()
  def inspect(term, opts \\ []) do
    label = if label = opts[:label], do: "#{label}: ", else: ""

    output = Kino.Output.inspect(term, opts)
    output = update_in(output.text, &(label <> &1))


  @doc """
  Configures Kino.

  The supported options are:

    * `:inspect`

  They are discussed individually in the sections below.

  ## Inspect

  A keyword list containing inspect options used for printing
  usual evaluation results. Defaults to pretty formatting with
  a limit of 50 entries.

  To show more entries, you configure a higher limit:

      Kino.configure(inspect: [limit: 200])

  You can also show all entries by setting the limit to `:infinity`,
  but keep in mind that for large data structures it is memory-expensive
  and is not an advised configuration in this case. Instead prefer
  the use of `IO.inspect/2` with `:infinity` limit when needed.

  See `Inspect.Opts` for the full list of options.
  @spec configure(keyword()) :: :ok
  def configure(options) do

  @doc ~S"""
  Renders a kino that periodically calls the given function
  to render a new result.

  The callback receives a stream element and should return a term
  to be rendered.

  This function uses `Kino.Frame` as the underlying kino.
  It returns nothing (a non-printable result).

  ## Examples

  An animation is created by turning a stream of values into
  subsequent animation frames:

      |> Stream.take(100)
      |> Kino.animate(fn i ->"**Iteration: `#{i}`**")

  Alternatively an integer may be passed as a shorthand for

      # Render new Markdown every 100ms
      Kino.animate(100, fn i ->"**Iteration: `#{i}`**")
  @spec animate(Enumerable.t() | pos_integer(), (term() -> any())) :: nothing()
  def animate(stream_or_interval_ms, fun) when is_function(fun, 1) do
    animate(stream_or_interval_ms, nil, fn item, nil ->
      {:cont, fun.(item), nil}

  @doc ~S"""
  A stateful version of `animate/2`.

  The callback receives a stream element and the accumulated state
  and it should return either of:

    * `{:cont, term_to_render, state}` - the continue

    * `:halt` - to no longer schedule callback evaluation

  ## Examples

  This function is primarily useful to consume `Kino.Control` events:

      button = Kino.Control.button("Click")

      |> Kino.animate(0, fn _event, counter ->
        new_counter = counter + 1
        md ="**Clicks: `#{new_counter}`**")
        {:cont, md, new_counter}
  @spec animate(
          Enumerable.t() | pos_integer(),
          (term(), state -> {:cont, term(), state} | :halt)
        ) :: nothing()
        when state: term()
  def animate(stream_or_interval_ms, state, fun)

  def animate(interval_ms, state, fun) when is_integer(interval_ms) and is_function(fun, 2) do
    animate(Stream.interval(interval_ms), state, fun)

  def animate(stream, state, fun) when is_function(fun, 2) do
    frame = |> Kino.render()

    listen(stream, state, fn item, state ->
      case safe_apply(fun, [item, state], "Kino.animate") do
        {:ok, {:cont, term, state}} ->
          Kino.Frame.render(frame, term)
          {:cont, state}

        {:ok, :halt} ->

        {:error, _, _} ->
          {:cont, state}


  @doc ~S"""
  Starts a process that consumes a stream with `fun` without blocking execution.

  It returns the PID of the started process. The process can be terminated
  with `Kino.terminate_child/1`.

  Note that events are processed by `fun` sequentially. If you want
  to process them concurrently, use `async_listen/2`.

  ## Examples

  This function is primarily useful to consume `Kino.Control` events:

      |> Kino.listen(fn event -> IO.inspect(event) end)

  You can also merge multiple controls into a single stream. For example,
  in order to merge them and tag each with a distinct event:

      button = Kino.Control.button("Hello")
      input = Kino.Input.checkbox("Check")

      stream = Kino.Control.tagged_stream([hello: button, check: input])

      Kino.listen(stream, fn
        {:hello, event} -> ...
        {:check, event} -> ...

  Any other stream works as well:

      |> Stream.take(10)
      |> Kino.listen(fn i -> IO.puts("Ping #{i}") end)

  Finally, an integer may be passed as a shorthand for `Stream.interval/1`:

      Kino.listen(100, fn i -> IO.puts("Ping #{i}") end)

  @spec listen(Enumerable.t() | pos_integer(), (term() -> any())) :: pid()
  def listen(stream_or_interval_ms, fun)

  def listen(interval_ms, fun) when is_integer(interval_ms) and is_function(fun, 1) do
    listen(Stream.interval(interval_ms), fun)

  def listen(stream, fun) when is_function(fun, 1) do
    async(fn -> Enum.each(stream, &safe_apply(fun, [&1], "Kino.listen")) end)

  @doc ~S"""
  A stateful version of `listen/2`.

  The callback should return either of:

    * `{:cont, state}` - the continue

    * `:halt` - to stop listening

  ## Examples

      button = Kino.Control.button("Click")

      Kino.listen(button, 0, fn _event, counter ->
        new_counter = counter + 1
        IO.puts("Clicks: #{new_counter}")
        {:cont, new_counter}

  @spec listen(
          Enumerable.t() | pos_integer(),
          (term(), state -> {:cont, state} | :halt)
        ) :: pid()
        when state: term()
  def listen(stream_or_interval_ms, state, fun)

  def listen(interval_ms, state, fun) when is_integer(interval_ms) and is_function(fun, 2) do
    listen(Stream.interval(interval_ms), state, fun)

  def listen(stream, state, fun) when is_function(fun, 2) do
    async(fn ->
      Enum.reduce_while(stream, state, fn item, state ->
        case safe_apply(fun, [item, state], "Kino.listen") do
          {:ok, {:cont, state}} -> {:cont, state}
          {:ok, :halt} -> {:halt, state}
          {:error, _, _} -> {:cont, state}

  defp safe_apply(fun, args, context) do
    try do
      {:ok, apply(fun, args)}
      kind, error ->
          "#{context} with #{Kernel.inspect(fun)} failed with reason:\n\n" <>
            Exception.format(kind, error, __STACKTRACE__)

        {:error, kind, error}

  defp async(fun) do
    {:ok, pid} =
        id: Task,
        start: {Kino.Terminator, :start_task, [self(), fun]},
        restart: :temporary


  @doc """
  Same as `listen/2`, except each event is processed concurrently.
  @spec async_listen(Enumerable.t() | pos_integer(), (term() -> any())) :: pid()
  def async_listen(stream_or_interval_ms, fun)

  def async_listen(interval_ms, fun) when is_integer(interval_ms) and is_function(fun, 1) do
    async_listen(Stream.interval(interval_ms), fun)

  def async_listen(stream, fun) when is_function(fun, 1) do
    async(fn ->
      # For organization purposes we start all tasks under a separate
      # supervisor and only that supervisor is started with Kino.start_child/1

      start_fun = fn ->
        {:ok, task_supervisor} = start_child(Task.Supervisor)

      reducer = fn event, task_supervisor ->
        {[{event, task_supervisor}], task_supervisor}

      after_fun = fn task_supervisor ->
        for {_, pid, _, _} <- DynamicSupervisor.which_children(task_supervisor),
            Process.alive?(pid) do
          ref = Process.monitor(pid)

          receive do
            {:DOWN, ^ref, _, _, _} -> :ok

        DynamicSupervisor.terminate_child(Kino.DynamicSupervisor, task_supervisor)

      |> Stream.transform(start_fun, reducer, after_fun)
      |> Enum.each(fn {event, task_supervisor} ->
        Task.Supervisor.start_child(task_supervisor, fn ->
          safe_apply(fun, [event], "Kino.async_listen")

  @doc """
  Returns a special value that results in no visible output.

  ## Examples

  This is especially handy when you wish to suppress the default output
  of a cell. For instance, a cell containing this would normally result
  in verbose response output:

      resp = Req.get!("")

  That output can be suppressed by appending a call to `nothing/0`:

      resp = Req.get!("")
  @spec nothing() :: nothing()
  def nothing() do
    :"do not show this result in output"

  @doc """
  Starts a process under the Kino supervisor.

  The process is automatically terminated when the current process
  terminates or the current cell reevaluates.

  If you want to terminate the started process, use
  `terminate_child/1`. If you terminate the process manually,
  the Kino supervisor might restart it if the child's `:restart`
  strategy says so.

  > #### Nested start {: .warning}
  > It is not possible to use `start_child/1` while initializing
  > another process started this way. In other words, you generally
  > cannot call `start_child/1` inside callbacks such as `c:GenServer.init/1`
  > or `c:Kino.JS.Live.init/2`. If you do that, starting the process
  > will block forever.
  > Note that creating many kinos uses `start_child/1` underneath,
  > hence the same restriction applies to starting those. See
  > `c:Kino.JS.Live.init/2` for more details.
  @spec start_child(
          | {module(), term()}
          | module()
        ) :: DynamicSupervisor.on_start_child()
  def start_child(child_spec) do
    %{start: start} = child_spec = Supervisor.child_spec(child_spec, [])
    parent = self()
    gl = Process.group_leader()
    child_spec = %{child_spec | start: {Kino.Terminator, :start_child, [start, parent, gl]}}
    DynamicSupervisor.start_child(Kino.DynamicSupervisor, child_spec)

  @doc """
  Similar to `start_child/2` but returns the new pid or raises an error.
  @spec start_child!(Supervisor.child_spec() | {module(), term()} | module()) :: pid()
  def start_child!(child_spec) do
    case start_child(child_spec) do
      {:ok, pid} ->

      {:ok, pid, _info} ->

      {:error, reason} ->
        raise "failed to start child with the spec #{Kernel.inspect(child_spec)}.\n" <>
                "Reason: #{start_supervised_error(reason)}"

  defp start_supervised_error({{:EXIT, reason}, info}) when is_tuple(info),
    do: Exception.format_exit(reason)

  defp start_supervised_error({reason, info}) when is_tuple(info),
    do: Exception.format_exit(reason)

  defp start_supervised_error(reason), do: Exception.format_exit(reason)

  @doc """
  Terminates a child started with `start_child/1`.

  Returns `:ok` if the child was found and terminated, or
  `{:error, :not_found}` if the child was not found.
  @doc since: "0.9.1"
  @spec terminate_child(pid()) :: :ok | {:error, :not_found}
  def terminate_child(pid) when is_pid(pid) do
    DynamicSupervisor.terminate_child(Kino.DynamicSupervisor, pid)

  @doc ~S"""
  Interrupts evaluation with the given message.

  This function raises a specific error to let Livebook known that
  evaluation should be stopped. The error message and a `Continue`
  button are shown to the user, who can then attempt to resolve the
  source of the interrupt before resuming execution.

  > #### Do not use interrupt inside listeners {: .warning}
  > Since `interrupt!/2` aborts the execution, it cannot be used
  > inside `Kino.listen/2` or other event listeners. In such cases,
  > you can use `Kino.Frame` and render any messages directly within
  > the frame, using `Kino.Text` or `Kino.Markdown`.

  ## Examples

      text =
        |> Kino.render()

      if text == "" do
        Kino.interrupt!(:error, "Input required")

      # This will not be run if the `interrupt!` is called above"**You entered:** #{text}")
  @spec interrupt!(:normal | :error, String.t()) :: no_return()
  def interrupt!(variant, message) when variant in [:normal, :error] and is_binary(message) do
    raise Kino.InterruptError, variant: variant, message: message

  @doc """
  Returns a temporary directory that gets removed when the runtime
  @spec tmp_dir() :: String.t() | nil
  def tmp_dir() do
    case Kino.Bridge.get_tmp_dir() do
      {:ok, path} -> path
      {:error, _} -> nil