@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])
[[[[], [[[], ""], :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 the prefix option. If set to false 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]))

@spec options(common :: [atom()], extra :: keyword()) :: keyword()

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 to true 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.