Owl.LiveScreen (Owl v0.1.0) View Source

A server that handles live updates in terminal.

It partially implements The Erlang I/O Protocol, so it is possible to use Owl.LiveScreen as an I/O-device in Logger.Backends.Console and functions like Owl.IO.puts/2, IO.puts/2. When used as I/O-device, then output is printed above dynamic blocks.

Example

require Logger
Logger.configure_backend(:console, device: Owl.LiveScreen)

Owl.LiveScreen.add_block(:dependency,
  state: :init,
  render: fn
    :init -> "init..."
    dependency -> ["dependency: ", Owl.Tag.new(dependency, :yellow)]
  end
)

Owl.LiveScreen.add_block(:compiling,
  render: fn
    :init -> "init..."
    filename -> ["compiling: ", Owl.Tag.new(to_string(filename), :cyan)]
  end
)

["ecto", "phoenix", "ex_doc", "broadway"]
|> Enum.each(fn dependency ->
  Owl.LiveScreen.update(:dependency, dependency)

  1..5
  |> Enum.map(&"filename#{&1}.ex")
  |> Enum.each(fn filename ->
    Owl.LiveScreen.update(:compiling, filename)
    Process.sleep(1000)
    Logger.debug("#{filename} compiled for dependency #{dependency}")
  end)
end)

Link to this section Summary

Types

add_block_option()

block_id()

start_option()

Functions

add_block(server \\ __MODULE__, block_id, params)

Adds a sticky block to the bottom of the screen that can be updated using update/3.

flush(server \\ __MODULE__)

Renders data in buffer and detaches blocks.

start_link(opts)

Starts a server.

stop(server \\ __MODULE__)

Renders data in buffer and terminates a server.

update(server \\ __MODULE__, block_id, block_state)

Updates a state of the block for using it in the next render iteration.

Link to this section Types

add_block_option()

Specs

add_block_option() ::
  {:state, any()} | {:render, (block_state :: any() -> Owl.Data.t())}

block_id()

Specs

block_id() :: any()

start_option()

Specs

start_option() ::
  {:name, GenServer.name()}
  | {:refresh_every, pos_integer()}
  | {:terminal_width, pos_integer() | :auto}

Link to this section Functions

add_block(server \\ MODULE, block_id, params)

Specs

add_block(GenServer.server(), block_id(), add_block_option()) :: :ok

Adds a sticky block to the bottom of the screen that can be updated using update/3.

Options

:render - a function that accepts state and returns a view of the block. Defaults to Function.identity/1, which means that state has to have type Owl.Data.t/0.
:state - initial state of the block. Defaults to nil.

Example

Owl.LiveScreen.add_block(:footer, state: "starting...")
# which is equivalent to
Owl.LiveScreen.add_block(:footer, render: fn
  nil -> "starting..."
  data -> data
end)

flush(server \\ MODULE)

Specs

flush(GenServer.server()) :: :ok

Renders data in buffer and detaches blocks.

start_link(opts)

Specs

start_link([start_option()]) :: GenServer.on_start()

Starts a server.

Server is started automatically by :owl application as a named process.

Options

:name - used for name registration as described in the "Name registration" section in the documentation for GenServer. Defaults to Owl.LiveScreen
:refresh_every - a period of refreshing a screen in milliseconds. Defaults to 100.
:terminal_width - a width of terminal in symbols. Defaults to :auto, which gets value from Owl.IO.columns/0. If terminal is now a available, then the server won't be started.

stop(server \\ MODULE)

Specs

stop(GenServer.server()) :: :ok

Renders data in buffer and terminates a server.

update(server \\ MODULE, block_id, block_state)

Specs

update(GenServer.server(), block_id(), block_state :: any()) :: :ok

Updates a state of the block for using it in the next render iteration.

Example

Owl.LiveScreen.add_block(:footer, "starting...")
Process.sleep(1000)
Owl.LiveScreen.update(:footer, "...almost done...")
Process.sleep(1000)
Owl.LiveScreen.update(:footer, "done!!!")