Workspace.Cli (Workspace v0.2.1)
View SourceHelper functions for the mix tasks
Summary
Functions
Prints a debug message.
Format the data and apply any custom styling
Highlights the given text
with the given ansi codes
Highlights the given string based on it's type.
Helper function for console log messages
Helper function for logging a message with a title
Merges the common options with the extra
Format the project name with the default styling and status info if needed.
Returns the color code for the given status.
Functions
@spec debug(message :: IO.ANSI.ansidata()) :: :ok
Prints a debug message.
The message is printed only if debugging messages are enabled. In order to
enable them you need to set the WORKSPACE_DEV
environment variable to
"true"
.
@spec format(ansidata :: IO.ANSI.ansidata(), emit? :: boolean()) :: IO.ANSI.ansidata()
Format the data and apply any custom styling
It will return an ansidata
list with the styling applied. Notice
that if emit?
is set to false, ANSI escape sequences are not emitted.
An exception will be raised if an ANSI sequence is invalid.
The returned list may still contain atoms. These will be handled by the
IO.ANSI.format
when the message is printed.
Examples
iex> Workspace.Cli.format("Hello")
[[], "Hello"]
iex> Workspace.Cli.format(:red)
[[], :red]
iex> Workspace.Cli.format(:red, false)
[]
iex> Workspace.Cli.format([:affected, "project", :reset])
[[[[], [[[], "[38;5;179m"], :bright]], "project"], :reset]
iex> Workspace.Cli.format(:invalid, false)
** (ArgumentError) invalid ANSI sequence specification: :invalid
@spec highlight( text :: IO.ANSI.ansidata(), ansi_codes :: IO.ANSI.ansicode() | [IO.ANSI.ansicode()] ) :: IO.ANSI.ansidata()
Highlights the given text
with the given ansi codes
This helper just wraps the text
with the given ansi codes and
adds a :reset
afterwards.
Examples
iex> Workspace.Cli.highlight("a blue text", :blue)
[:blue, ["a blue text"], :reset]
iex> Workspace.Cli.highlight(["some ", "text"], :blue)
[:blue, ["some ", "text"], :reset]
iex> Workspace.Cli.highlight("some text", [:bright, :green])
[:bright, :green, ["some text"], :reset]
@spec hl(text :: String.t(), type :: atom()) :: IO.ANSI.ansidata()
Highlights the given string based on it's type.
The following types are currently supported:
:code
- highlighted with:light_cyan
@spec log( message :: IO.ANSI.ansidata(), opts :: Keyword.t() ) :: :ok
Helper function for console log messages
The message can be a rich formatted list. On top of the default elixir
styles, various workspace
related styles are supported for consistency
across the cli apps. For more details on the supported style specifications
check format_style/1
.
Options
:prefix
the prefix to be used. You can either specify the actual header or set one of the following options::header
: corresponds to "==> ".- if set to
false
no prefix is applied. - if not set then no prefix is applied.
@spec log_with_title( section :: IO.ANSI.ansidata(), message :: IO.ANSI.ansidata(), opts :: Keyword.t() ) :: :ok
Helper function for logging a message with a title
Each log message consists of the following sections:
prefix
a prefix for each log message, defaults to "==> ". Can be configured through theprefix
option. If set tofalse
no prefix is applied.title
a string representing the title of the log message, e.g. an application name, a command or a log level.separator
separator between the title and the main message, defaults to a space.message
the message to be printed, can be any text
Options
:prefix
- the prefix to be used, defaults to==>
:separator
- the separator to be used between title and message, defaults to-
Examples
You can combine it with other helper CLI functions like highlight
for
rich text log messages.
# Default invocation
Cli.log(":foo", "a message") ##> ==> :foo - a message
# with a different prefix
Cli.log(":foo", "a message", prefix: "> ") ##> > :foo - a message
# with highlighted sections
Cli.log(project_name(project, show_status: true), highlight(message, [:bright, :red]))
Merges the common options with the extra
@spec project_name(project :: Workspace.Project.t(), opts :: keyword()) :: IO.ANSI.ansidata()
Format the project name with the default styling and status info if needed.
Options
:show_status
- if set totrue
it color codes the name based on the status of the project and appends status icons as following::modified
-✚
(bright red):affected
-●
(bright yellow):unaffected
-✔
(:bright green)
:default_style
- can be used to change the default style (:light_cyan
)
@spec status_color(status :: :error | :error_ignore | :ok | :skip | :warn) ::
:green | :magenta | :red | :white | :yellow
Returns the color code for the given status.