View Source Mix.Shell behaviour (Mix v1.17.3)

Defines Mix.Shell contract.

Summary

Callbacks

cmd(command)

Executes the given command and returns its exit status.

cmd(command, options)

Executes the given command and returns its exit status.

error(message)

Prints the given ANSI error to the shell.

info(message)

Prints the given ANSI message to the shell.

print_app()

Prints the current application to the shell if it was not printed yet.

prompt(message)

Prompts the user for input.

yes?(message)

Prompts the user for confirmation.

yes?(message, options)

Prompts the user for confirmation.

Functions

cmd(command, options \\ [], callback)

Executes the given command as a shell command and invokes the callback for the streamed response.

printable_app_name()

Returns the printable app name.

Callbacks

Link to this callback

cmd(command)

View Source 
@callback cmd(command :: String.t()) :: integer()

Executes the given command and returns its exit status.

Shortcut for cmd/2 with empty options.

Link to this callback

cmd(command, options)

View Source 
@callback cmd(command :: String.t(), options :: keyword()) :: integer()

Executes the given command and returns its exit status.

Options

This callback should support the following options:

  • :print_app - when false, does not print the app name when the command outputs something

  • :stderr_to_stdout - when false, does not redirect stderr to stdout

  • :quiet - when true, do not print the command output

  • :env - environment options to the executed command

  • :cd (since v1.11.0) - the directory to run the command in

All the built-in shells support these.

Link to this callback

error(message)

View Source 
@callback error(message :: IO.ANSI.ansidata()) :: :ok

Prints the given ANSI error to the shell.

Link to this callback

info(message)

View Source 
@callback info(message :: IO.ANSI.ansidata()) :: :ok

Prints the given ANSI message to the shell.

Link to this callback

print_app()

View Source 
@callback print_app() :: :ok

Prints the current application to the shell if it was not printed yet.

Link to this callback

prompt(message)

View Source 
@callback prompt(message :: binary()) :: binary()

Prompts the user for input.

Link to this callback

yes?(message)

View Source 
@callback yes?(message :: binary()) :: boolean()

Prompts the user for confirmation.

Shortcut for yes?/2 with empty options.

Link to this callback

yes?(message, options)

View Source 
@callback yes?(message :: binary(), options :: keyword()) :: boolean()

Prompts the user for confirmation.

Options

  • :default - :yes or :no (the default is :yes)

Functions

Link to this function

cmd(command, options \\ [], callback)

View Source 
@spec cmd(String.t(), keyword(), (binary() -> term())) ::
  exit_status :: non_neg_integer()

Executes the given command as a shell command and invokes the callback for the streamed response.

This is most commonly used by shell implementations but can also be invoked directly.

callback takes the output data of the command. Its return value is ignored.

Options

  • :cd (since v1.11.0) - the directory to run the command in

  • :stderr_to_stdout - redirects stderr to stdout, defaults to true, unless use_stdio is set to false

  • :use_stdio - controls whether the command should use stdin / stdout / stdrr, defaults to true

  • :env - a list of environment variables, defaults to []

  • :quiet - overrides the callback to no-op

Link to this function

printable_app_name()

View Source 
@spec printable_app_name() :: atom() | nil

Returns the printable app name.

This function returns the current application name, but only if the application name should be printed.

Calling this function automatically toggles its value to false until the current project is re-entered. The goal is to avoid printing the application name multiple times.