A list of ANSI styles representing the basic 16 terminal colors, 8 standard and 8 bright.

A list of ANSI styles representing non-color display effects.

Retrieves a list of strings corresponding to any extra arguments passed when invoking a runtime—via gleam run, for example.

Examples

// $ gleam run -- pizza --order=5 --anchovies=false
arguments()
// -> ["pizza", "--order=5", "--anchovies=false"]

// $ gleam run --target=javascript
arguments()
// -> []

Converts a list of "background" style labels into a StyleFlags.

Examples

style(
  "awesome",
  with: background(["yellow", "brightgreen", "bodacious"]),
  custom: [],
)
// -> "\u{1b}[43;102mawesome\u{1b}[0m\u{1b}[K"

Converts a list of "color" style labels into a StyleFlags.

Examples

style(
  "uh...",
  with: color(["yellow", "brightgreen", "gnarly"]),
  custom: [],
)
// -> "\u{1b}[33;92muh...\u{1b}[0m\u{1b}[K"

Results in any output captured from the given executable on success, or an Error on failure.

An Error result wraps a tuple in which the first element is an OS error status code and the second is a message about what went wrong (or an empty string).

The executable is given arguments and run from within the given directory.

Any number of CommandOpt options can be given to alter the behavior of this function.

The standard error stream is by default redirected to the standard output stream, and both are captured. When targeting JavaScript, anything captured from the standard error stream is appended to anything captured from the standard output stream.

The standard input stream is by default handled in raw mode when targeting JavaScript, allowing full interaction with the spawned process. When targeting Erlang, however, it’s always handled in cooked mode.

Note that while shellout aims for near feature parity between runtimes, some discrepancies exist and are documented herein.

Examples

command(run: "echo", with: ["-n", "Cool!"], in: ".", opt: [])
// -> Ok("Cool!")

command(run: "echo", with: ["Cool!"], in: ".", opt: [LetBeStdout])
// Cool!
// -> Ok("")

// $ stat -c '%a %U %n' /tmp/dimension_x
// 700 root /tmp/dimension_x
command(run: "ls", with: ["dimension_x"], in: "/tmp", opt: [])
// -> Error(#(2, "ls: cannot open directory 'dimension_x': Permission denied\n"))

command(run: "dimension_x", with: [], in: ".", opt: [])
// -> Error(#(1, "command `dimension_x` not found\n"))

// $ ls -p
// gleam.toml  manifest.toml  src/  test/
command(run: "echo", with: [], in: "dimension_x", opt: [])
// -> Error(#(2, "The directory \"dimension_x\" does not exist\n"))

Converts a list of "display" style labels into a StyleFlags.

Examples

style(
  "radical",
  with: display(["bold", "italic", "tubular"]),
  custom: [],
)
// -> "\u{1b}[1;3mradical\u{1b}[0m\u{1b}[K"

Halts the runtime and passes the given status code to the operating system.

A status code of 0 typically indicates success, while any other integer represents an error.

Examples

// $ gleam run && echo "Pizza time!"
exit(0)
// Pizza time!

// $ gleam run || echo "Ugh, shell shock ..."
exit(1)
// Ugh, shell shock ...

Applies ANSI styles to a string, resetting styling at the end.

If a style label isn’t found within a Lookup associated with the corresponding StyleFlags key’s category, that label is silently ignored.

Examples

import gleam/dict
pub const lookups: Lookups = [
  #(
    ["color", "background"],
    [
      #("buttercup", ["252", "226", "174"]),
      #("mint", ["182", "255", "234"]),
      #("pink", ["255", "175", "243"]),
    ],
  ),
]
style(
  "cowabunga",
  with: display(["bold", "italic", "awesome"])
  |> dict.merge(color(["pink", "righteous"]))
  |> dict.merge(background(["brightblack", "excellent"])),
  custom: lookups,
)
// -> "\u{1b}[1;3;38;2;255;175;243;100mcowabunga\u{1b}[0m\u{1b}[K"

Results in a path to the given executable on success, or an Error when no such path is found.

Examples

which("echo")
// -> Ok("/sbin/echo")

which("./priv/party")
// -> Ok("./priv/party")

which("dimension_x")
// -> Error("command `dimension_x` not found")