v0.0.2

Author: ericentin

.gitignore

@@ -1,5 +1,7 @@
 /_build
 /cover
 /deps
+/doc
+/docs
 erl_crash.dump
 *.ez

.travis.yml

@@ -0,0 +1,24 @@
+language: elixir
+elixir:
+  - 1.2.5
+otp_release:
+  - 18.3
+sudo: false
+env:
+  - MIX_ENV=test
+  - MIX_ENV=test ELIXIR_ERL_OPTIONS="+T 9"
+before_script:
+  - mix compile --warnings-as-errors
+  - mix dialyzer.plt
+script:
+  - mix coveralls.travis
+  - mix dialyzer --halt-exit-status
+  - mix credo --strict
+after_script:
+  - mix deps.get --only docs
+  - MIX_ENV=docs mix inch.report
+cache:
+  directories:
+    - .dialyxir
+    - _build
+    - deps

README.md

@@ -1,38 +1,43 @@
-# DOCS IN PROGRESS!
+[![Build Status](https://travis-ci.org/antipax/tqdm_elixir.svg?branch=master)](https://travis-ci.org/antipax/tqdm_elixir) [![Coverage Status](https://coveralls.io/repos/github/antipax/tqdm_elixir/badge.svg?branch=master)](https://coveralls.io/github/antipax/tqdm_elixir?branch=master) [![Inline docs](http://inch-ci.org/github/antipax/tqdm_elixir.svg?branch=master)](http://inch-ci.org/github/antipax/tqdm_elixir)
 
 # Tqdm
 
-Add a progress bar to your enumerables in a second.
+Tqdm easily adds a CLI progress bar to any enumerable.
 
 A (partial) port of Python's [tqdm](https://github.com/tqdm/tqdm) to Elixir. Thanks noamraph and all other contributors for the original library!
 
-Wrap your favorite enumerables (i.e. Lists, Maps, Streams, anything that implements Enumerable!) with tqdm, and see progress in detail!
-
-For example:
+Just wrap Lists, Maps, Streams, or anything else that implements Enumerable with `Tqdm.tqdm`:
 
 ```elixir
 for _ <- Tqdm.tqdm(1..1000) do
   :timer.sleep(10)
 end
-```
 
-will give you a nice progress bar like:
+# or
 
-```
-|######----| 665/1000 67.0% [elapsed: 00:00:10.522247 left: 00:00:05, 63.2 iters/sec]
+1..1000
+|> Tqdm.tqdm()
+|> Enum.map(fn _ -> :timer.sleep(10) end)
+
+# or even...
+
+1..1000
+|> Stream.map(fn -> :timer.sleep(10) end)
+|> Tqdm.tqdm()
+|> Stream.run()
+
+# |###-------| 392/1000 39.0% [elapsed: 00:00:04.627479 left: 00:00:07, 84.71 iters/sec]
 ```
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed as:
-
   1. Add tqdm to your list of dependencies in `mix.exs`:
 
         def deps do
-          [{:tqdm, "~> 0.0.1"}]
+          [{:tqdm, "~> 0.0.2"}]
         end
 
-  2. Ensure tqdm is started before your application:
+  2. Ensure tqdm is added to your list of applications:
 
         def application do
           [applications: [:tqdm]]

lib/tqdm.ex

@@ -1,25 +1,110 @@
 defmodule Tqdm do
+  @moduledoc """
+  Tqdm easily adds a CLI progress bar to any enumerable.
 
-  @num_bars 10
+  Just wrap Lists, Maps, Streams, or anything else that implements Enumerable
+  with `Tqdm.tqdm`:
 
-  def tqdm(enumerable, opts \\ []) do
-    now = :erlang.monotonic_time()
+      for _ <- Tqdm.tqdm(1..1000) do
+        :timer.sleep(10)
+      end
+
+      # or
+
+      1..1000
+      |> Tqdm.tqdm()
+      |> Enum.map(fn _ -> :timer.sleep(10) end)
+
+      # or even...
+
+      1..1000
+      |> Stream.map(fn -> :timer.sleep(10) end)
+      |> Tqdm.tqdm()
+      |> Stream.run()
+
+      # |###-------| 392/1000 39.0% [elapsed: 00:00:04.627479 \
+  left: 00:00:07, 84.71 iters/sec]
+  """
+
+
+  @type option ::
+    {:description, String.t} |
+    {:total, non_neg_integer} |
+    {:clear, boolean} |
+    {:device, IO.device} |
+    {:min_interval, non_neg_integer} |
+    {:min_iterations, non_neg_integer} |
+    {:total_segments, non_neg_integer}
+
+  @type options :: [option]
+
+  @doc """
+  Wrap the given `enumerable` and print a CLI progress bar.
+
+  `options` may be provided:
+
+    * `:description` - a short string that is displayed on the progress bar.
+      For example, if the string `"Processing values"` is provided for this
+      option:
+
+          # Processing values: |###-------| 349/1000 35.0% [elapsed: \
+  00:00:06.501472 left: 00:00:12, 53.68 iters/sec]
+
+    * `:total` - by default, `Tdqm` will use `Enum.count` to count how many
+      elements are in the given `enumerable`. For large amounts of data, or
+      streams, this may not be appropriate. You can provide your own total with
+      this option. You may provide an estimate, and if the actual count
+      exceeds this value, the progress bar will change to an indeterminate mode:
+
+          # 296 [elapsed: 00:00:03.500038, 84.57 iters/sec]
+
+      You can also force the indeterminate mode by passing `0`.
+
+    * `:clear` - by default, `Tqdm` will clear the progress bar after the
+      enumeration is complete. If you pass `false` for this option, the progress
+      bar will persist, instead.
+
+    * `:device` - by default, `Tqdm` writes to `:stderr`. You can provide any
+      `IO.device` to this option to use it instead of the default.
+
+    * `:min_interval` - by default, `Tqdm` will only print progress updates
+      every 100ms. You can increase or decrease this value using this option.
+
+    * `:min_iterations` - by default, `Tqdm` will check if the `:min_interval`
+      has passed for every iteration. Passing a value for this option will skip
+      this check until at least `:min_iterations` iterations have passed.
+
+    * `:total_segments` - by default, `Tqdm` will split its progress bar into 10
+      segments. You can customize this by passing a different value for this
+      option.
+  """
+  @spec tqdm(Enumerable.t, options) :: Enumerable.t
+  def tqdm(enumerable, options \\ []) do
+    start_fun = fn ->
+      now = :erlang.monotonic_time()
+
+      get_total = fn -> Enum.count(enumerable) end
+
+      %{
+        n: 0,
+        last_print_n: 0,
+        start_time: now,
+        last_print_time: now,
+        last_printed_length: 0,
+        prefix: options |> Keyword.get(:description, "") |> prefix(),
+        total: Keyword.get_lazy(options, :total, get_total),
+        clear: Keyword.get(options, :clear, true),
+        device: Keyword.get(options, :device, :stderr),
+        min_interval:
+          options
+          |> Keyword.get(:min_interval, 100)
+          |> :erlang.convert_time_unit(:milli_seconds, :native),
+        min_iterations: Keyword.get(options, :min_iterations, 1),
+        total_segments: Keyword.get(options, :total_segments, 10)
+      }
+    end
 
-    state = %{
-      n: 0,
-      last_print_n: 0,
-      start_time: now,
-      last_print_time: now,
-      last_printed_length: 0,
-      prefix: Keyword.get(opts, :description, "") |> prefix(),
-      total: Keyword.get_lazy(opts, :total, fn -> Enum.count(enumerable) end),
-      clear: Keyword.get(opts, :clear, true),
-      device: Keyword.get(opts, :device, :stderr),
-      min_interval: Keyword.get(opts, :min_interval, 100),
-      min_iterations: Keyword.get(opts, :min_iterations, 1)
-    }
-
-    Stream.transform(enumerable, fn -> state end, &do_tqdm/2, &do_tqdm_after/1)
+    Stream.transform(enumerable, start_fun, &do_tqdm/2, &do_tqdm_after/1)
   end
 
   defp prefix(""), do: ""
@@ -29,26 +114,40 @@ defmodule Tqdm do
     {[element], %{print_status(state, :erlang.monotonic_time()) | n: 1}}
   end
 
-  defp do_tqdm(element, %{n: n, last_print_n: last_print_n, min_iterations: min_iterations} = state)
-  when n - last_print_n < min_iterations,
+  defp do_tqdm(
+    element,
+    %{n: n, last_print_n: last_print_n, min_iterations: min_iterations} = state
+  ) when n - last_print_n < min_iterations,
     do: {[element], %{state | n: n + 1}}
 
-  defp do_tqdm(element, %{n: n, last_print_time: last_print_time, min_interval: min_interval} = state) do
+  defp do_tqdm(element, state) do
     now = :erlang.monotonic_time()
 
-    if :erlang.convert_time_unit(now - last_print_time, :native, :milli_seconds) >= min_interval do
-      state = %{print_status(state, now) | last_print_n: n, last_print_time: :erlang.monotonic_time()}
-    end
+    time_diff =
+      now - state.last_print_time
+
+    state =
+      if time_diff >= state.min_interval do
+        Map.merge(print_status(state, now), %{
+          last_print_n: state.n,
+          last_print_time: :erlang.monotonic_time()
+        })
+      else
+        state
+      end
 
-    {[element], %{state | n: n + 1}}
+    {[element], %{state | n: state.n + 1}}
   end
 
   defp do_tqdm_after(state) do
     state = print_status(state, :erlang.monotonic_time())
 
     finish =
       if state.clear do
-        "\r" <> String.duplicate(" ", String.length(state.prefix) + state.last_printed_length) <> "\r"
+        prefix_length = String.length(state.prefix)
+        total_bar_chars = prefix_length + state.last_printed_length
+
+        "\r" <> String.duplicate(" ", total_bar_chars) <> "\r"
       else
         "\n"
       end
@@ -60,48 +159,71 @@ defmodule Tqdm do
     status = format_status(state, now)
     status_length = String.length(status)
 
-    padding = String.duplicate(" ", max(state.last_printed_length - status_length, 0))
+    num_padding_chars = max(state.last_printed_length - status_length, 0)
+    padding = String.duplicate(" ", num_padding_chars)
 
     IO.write(state.device, "\r#{state.prefix}#{status}#{padding}")
 
     %{state | last_printed_length: status_length}
   end
 
-  defp format_status(%{n: n, total: total, start_time: start_time}, now) do
-    elapsed = :erlang.convert_time_unit(now - start_time, :native, :micro_seconds)
-
-    total = if n <= total, do: total
+  defp format_status(state, now) do
+    elapsed =
+      :erlang.convert_time_unit(now - state.start_time, :native, :micro_seconds)
 
     elapsed_str = format_interval(elapsed, false)
 
-    rate = if elapsed > 0, do: Float.round(n / (elapsed / 1_000_000), 2), else: "?"
+    rate = format_rate(elapsed, state.n)
+
+    format_status(state, elapsed, rate, elapsed_str)
+  end
 
-    if total do
+  defp format_status(state, elapsed, rate, elapsed_str) do
+    n = state.n
+    total = state.total
+    total_segments = state.total_segments
+
+    if n <= total and total != 0 do
       progress = n / total
 
-      num_bars = trunc(progress * @num_bars)
-      bar = String.duplicate("#", num_bars) <> String.duplicate("-", @num_bars - num_bars)
+      num_segments = trunc(progress * total_segments)
+
+      bar = format_bar(num_segments, total_segments)
 
       percentage = "#{Float.round(progress * 100)}%"
 
-      left_str = if n > 0, do: format_interval(elapsed / n * (total - n), true), else: "?"
+      left = format_left(n, elapsed, total)
 
-      "|#{bar}| #{n}/#{total} #{percentage} [elapsed: #{elapsed_str} left: #{left_str}, #{rate} iters/sec]"
+      "|#{bar}| #{n}/#{total} #{percentage} " <>
+      "[elapsed: #{elapsed_str} left: #{left}, #{rate} iters/sec]"
     else
       "#{n} [elapsed: #{elapsed_str}, #{rate} iters/sec]"
     end
   end
 
+  defp format_rate(elapsed, n) when elapsed > 0,
+    do: Float.round(n / (elapsed / 1_000_000), 2)
+  defp format_rate(_elapsed, _n),
+    do: "?"
+
+  defp format_bar(num_segments, total_segments) do
+    String.duplicate("#", num_segments) <>
+    String.duplicate("-", total_segments - num_segments)
+  end
+
+  defp format_left(n, elapsed, total) when n > 0,
+    do: format_interval(elapsed / n * (total - n), true)
+  defp format_left(_n, _elapsed, _total),
+    do: "?"
+
   defp format_interval(elapsed, trunc_seconds) do
     minutes = trunc(elapsed / 60_000_000)
     hours = div(minutes, 60)
     rem_minutes = minutes - hours * 60
     micro_seconds = elapsed - minutes * 60_000_000
     seconds = micro_seconds / 1_000_000
 
-    if trunc_seconds do
-      seconds = trunc(seconds)
-    end
+    seconds = if trunc_seconds, do: trunc(seconds), else: seconds
 
     hours_str = format_time_component(hours)
     minutes_str = format_time_component(rem_minutes)
@@ -110,13 +232,8 @@ defmodule Tqdm do
     "#{hours_str}:#{minutes_str}:#{seconds_str}"
   end
 
-  defp format_time_component(time) do
-    time_string = to_string(time)
-
-    if time < 10 do
-      "0" <> time_string
-    else
-      time_string
-    end
-  end
+  defp format_time_component(time) when time < 10,
+    do: "0#{time}"
+  defp format_time_component(time),
+    do: to_string(time)
 end