@spec animate(Enumerable.t() | pos_integer(), (term() -> any())) :: nothing()

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

Examples

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

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

Alternatively an integer may be passed as a shorthand for Stream.interval/1:

# Render new Markdown every 100ms
Kino.animate(100, fn i ->
  Kino.Markdown.new("**Iteration: `#{i}`**")
end)

@spec animate(
  Enumerable.t() | pos_integer(),
  state,
  (term(), state -> {:cont, term(), state} | :halt)
) :: nothing()
when state: term()

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

Examples

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

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

button
|> Kino.Control.stream()
|> Kino.animate(0, fn _event, counter ->
  new_counter = counter + 1
  md = Kino.Markdown.new("**Clicks: `#{new_counter}`**")
  {:cont, md, new_counter}
end)

@spec async_listen(Enumerable.t() | pos_integer(), (term() -> any())) :: pid()

Same as listen/2, except each event is processed concurrently.

@spec configure(keyword()) :: :ok

Configures Kino.

The supported options are:

• :inspect

They are discussed individually in the sections below.

inspect

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 inspect(
  term(),
  keyword()
) :: term()

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 interrupt!(:normal | :error, String.t()) :: no_return()

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

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

Examples

text =
  Kino.Input.text("Input")
  |> Kino.render()
  |> Kino.Input.read()

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

# This will not be run if the `interrupt!` is called above
Kino.Markdown.new("**You entered:** #{text}")

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

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

Examples

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

Kino.Control.button("Greet")
|> 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} -> ...
end)

Any other stream works as well:

Stream.interval(100)
|> 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(),
  state,
  (term(), state -> {:cont, state} | :halt)
) :: pid()
when state: term()

A stateful version of listen/2.

The callback should return either of:

• {:cont, state} - the continue

• :halt - to stop listening

examples

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}
end)

@spec nothing() :: nothing()

Returns a special value that results in no visible output.

examples

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!("https://example.org")

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

resp = Req.get!("https://example.org")
Kino.nothing()

@spec render(term()) :: term()

Renders the given term as cell output.

This effectively allows any Livebook cell to have multiple evaluation results.

@spec start_child(Supervisor.child_spec() | {module(), term()} | module()) ::
  DynamicSupervisor.on_start_child()

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

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 GenServer.init/1 or 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 Kino.JS.Live.init/2 for more details.

@spec start_child!(Supervisor.child_spec() | {module(), term()} | module()) :: pid()

Similar to start_child/2 but returns the new pid or raises an error.

@spec terminate_child(pid()) :: :ok | {:error, :not_found}

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.

@spec tmp_dir() :: String.t() | nil

Returns a temporary directory that gets removed when the runtime terminates.