loggy

v0.1.1

loggy v0.1.1 Loggy

Loggy is a simple logging tool designed for Elixir CLIs, as the default logger does not support colours in escripts. Loggy does not integrate with Logger. Instead, it's tailored around CLI usage.

Loggy supports configuration through direct passthrough of parsed arguments from OptionParser. verbose, debug, and color/colour are supported. verbose supports both a binary flag and multiple levels.

There are two keyword structures that Loggy relies on for what to print and when. These are config and opts.

config is determined by your user and should be passed straight from OptionsParser. It determines whether to use colour, debugging, and verbosity level to use. You shouldn't change config further than what the user does.

opts are the arguments passed to the log function. These are level, verbosity level required to print, whether the error should be fatal, etc. You can override change opts[level] to change default behaviour for a certain level, and opts[:all] to change all.

TODO: full runtime examples

Link to this section Summary

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor

debug(str, opts \\ [])

Wrapper to write debug message, if debugging is enabled. See log/3

error(str, opts \\ [])

Wrapper to write warning, by default to stderr. See log/3 Unlike error!/2, is not fatal and doesn't halt the program

error!(str, opts \\ [])

Wrapper to write error, by default to stderr. See log/3 Unlike error/2, also exits with System.stop(1). Note that this exits from the calling process, not the Loggy agent. As such, it will probably shut down your CLI. Bear this in mind if your program has to perform any clean-up tasks after crashing

get_fn_params()
get_user_opts()
info(str, opts \\ [])

Wrapper to write info message. See log/3

log(str, opts)

Main logging function of loggy. You'll most likely want to use the debug/2, info/2, warn/2, and error/2 functions though, but manually passing the level might be helpful e.g. in order to promote warnings to errors if enough occur

set_fn_params(new)
set_user_opts(new)
start(_, state)

Initialise Loggy and update it with the given options. See configure/1. Note that this will be done automatically if applications has not been made to exclude it in your project's mix.exs

warn(str, opts \\ [])

Wrapper function to write warning message. See log/3

Link to this section Functions

Link to this function

child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

debug(str, opts \\ []) 
debug(String.t(), keyword()) :: :ok | :debug_skip | :verbosity_skip

Wrapper to write debug message, if debugging is enabled. See log/3

Examples 

iex> Loggy.set_user_opts(debug: true)
iex> Loggy.debug("Hello!")
#=> 🐛 Hello!
:ok

iex> Loggy.set_user_opts(debug: false)
iex> Loggy.debug("Hello!")
:debug_skip
Link to this function

error(str, opts \\ []) 
error(String.t(), keyword()) :: :ok | :verbosity_skip

Wrapper to write warning, by default to stderr. See log/3 Unlike error!/2, is not fatal and doesn't halt the program.

Examples 

iex> Loggy.error("You really did it this time.")
#=> đŸšĢ You really did it this time.
:ok
Link to this function

error!(str, opts \\ []) 
error!(String.t(), keyword()) :: no_return()

Wrapper to write error, by default to stderr. See log/3 Unlike error/2, also exits with System.stop(1). Note that this exits from the calling process, not the Loggy agent. As such, it will probably shut down your CLI. Bear this in mind if your program has to perform any clean-up tasks after crashing.

Overrides verbosity to assure that the error is always printed before exiting.

Examples 

iex> Loggy.error("This won't do.", verbose: 1)
:verbosity_skip

Loggy.error!("And that's a wrap!", verbose: 1)
#=> đŸšĢ And that's a wrap!
# [The program exits]
Link to this function

get_fn_params() 
get_fn_params() :: keyword()

Link to this function

get_user_opts() 
get_user_opts() :: keyword()

Link to this function

info(str, opts \\ []) 
info(String.t(), keyword()) :: :ok | :verbosity_skip

Wrapper to write info message. See log/3

Examples 

iex> Loggy.info("Hey hey hey!")
#=>  ℹī¸ Hey hey hey!
:ok
Link to this function

log(str, opts) 
log(String.t(), keyword()) :: :ok | :verbosity_skip | :debug_skip

Main logging function of loggy. You'll most likely want to use the debug/2, info/2, warn/2, and error/2 functions though, but manually passing the level might be helpful e.g. in order to promote warnings to errors if enough occur.

Opts

Valid opts are...

  • level: one of :debug, :info, :warn, and :error
  • verbose: integer or boolean. Internally converted to integer. Note that it's the required verbosity of a logging statement. In other words, a call with verbosity: 2 will only print out if verbosity >= 2 in the Loggy config. Usually, this would be achieved by passing the --verbose flag twice, or -vv for short.
  • fatal: if true, will exit the program with System.stop/1 and an exit value of 1.

TODO: conditional warn/error! example...

Link to this function

set_fn_params(new) 
set_fn_params(keyword()) :: :ok

Link to this function

set_user_opts(new) 
set_user_opts(keyword()) :: :ok

Link to this function

start(_, state) 
start(any(), user_opts: keyword(), fn_params: keyword()) :: {:ok, Loggy}

Initialise Loggy and update it with the given options. See configure/1. Note that this will be done automatically if applications has not been made to exclude it in your project's mix.exs

Examples 

{:ok, pid} = Loggy.start(:normal, user_opts: [verbose: 3, debug: true])
Link to this function

warn(str, opts \\ []) 
warn(String.t(), keyword()) :: :ok | :verbosity_skip

Wrapper function to write warning message. See log/3

Examples 

iex> Loggy.warn("Please do not the.")
#=>  ⚠ī¸ Please do not the.
:ok