#+title: PacmanProgressBar in Elixir

Command line progress bar like the one from Arch Linux's pacman package manager.

I got my inspiration from [[https://dennisbeatty.com/cool-clis-in-elixir-with-io-write-2/][Cool CLIs in Elixir with IO.write/2 by Dennis Beatty]], [[https://github.com/henrik/progress_bar][progress_bar by henrik]], my own old project [[https://gitlab.com/Pistrie/pacmanprogressbar][PacmanProgressBar in Java]], and of course the [[https://wiki.archlinux.org/title/pacman][pacman package manager]].

* Table of contents :toc:
  - [[#usage][Usage]]
  - [[#examples][Examples]]
  - [[#installation][Installation]]
  - [[#license][License]]

** Usage

You can render the progress bar using PacmanProgressBar.render/2. You specify the total amount of tasks being executed and the amount of tasks completed. This uses IO.write/2 to print the bar, and the bar is preceded by a carriage return character to replace the previous bar like so: IO.write("\r[---C o..."

#+begin_src elixir
PacmanProgressBar.render(30, 7)

#=> [-----------------------c  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  ]  23%
#+end_src

Running this function multiple times will overwrite the last result.

#+begin_src elixir
PacmanProgressBar.render(30, 7)
PacmanProgressBar.render(30, 12)

#=> [---------------------------------------c o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  ]  40%
#+end_src

You can also get this progress bar in the form of a string, in case that's something you would need.

#+begin_src elixir
PacmanProgressBar.raw(30, 7)

#=> "[-----------------------c  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  ]  23%"
#+end_src

When the progress bar is complete it will automatically print a newline character.

*** Bar size

You can change the size of the bar by supplying the `:bar_size` option:

#+begin_src elixir
PacmanProgressBar.render(30, 7, bar_size: 47)

#=> [-----------c  o  o  o  o  o  o  o  o  o  o  o  ]  23%
#+end_src

*** Pacman color

You can make pacman yellow by supplying the `:use_color` option:

#+begin_src elixir
PacmanProgressBar.raw(30, 7, use_color: true)

#=> "[-----------------------\e[33mc\e[0m  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  o  ]  23%"
#+end_src

The ANSI codes will be read by IO.write to turn the `c` yellow.

** Examples

You can try the example script by cloning this repo and running the example script:

#+begin_src
mix run examples/pacman.exs

mix run examples/pacman_no_color.exs
#+end_src

** Installation

The package can be installed by adding ~pacman_progress_bar~ to your list of dependencies in ~mix.exs~:

#+begin_src elixir
def deps do
  [
    {:pacman_progress_bar, "> 0.0.0"}
  ]
end
#+end_src

** License

Released under the [[https://www.gnu.org/licenses/lgpl-3.0.html][LGPL]]. This means that your code can freely use this library. It can even be used in proprietary code. The copyleft license only applies to this library itself. See the LGPL page for more information.