gleamyshell

Types

AbortReason

Represents the reason why the execution of a command was aborted.

Most of these reasons are common POSIX errors.

pub type AbortReason {
  Enomem
  Eagain
  Enametoolong
  Emfile
  Enfile
  Eacces
  Enoent
  OtherAbortReason(String)
}

Constructors

```
Enomem
```
Not enough memory.
```
Eagain
```
Resource temporarily unavailable.
```
Enametoolong
```
Too long file name.
```
Emfile
```
Too many open files.
```
Enfile
```
File table overflow.
```
Eacces
```
Insufficient permissions.
```
Enoent
```
No such file or directory.
```
OtherAbortReason(String)
```
An error not represented by the other options.

CommandError

</>

Represents information about why a command execution failed.

pub type CommandError {
  Failure(output: String, exit_code: Int)
  Abort(reason: AbortReason)
}

Constructors

```
Failure(output: String, exit_code: Int)
```
The command could be executed but returned a non-zero exit code.
```
Abort(reason: AbortReason)
```
The command could not be executed completely and was aborted. You usually don’t want to pattern match the specific reason and when targeting Bun, you won’t receive any reason besides Enoent due to Bun’s limitations here.

Os

</>

Represents names of operating systems.

pub type Os {
  Darwin
  FreeBsd
  OpenBsd
  Linux
  SunOs
  OtherOs(String)
}

Constructors

```
Darwin
```
The Unix operating system used by Apple as a core for its operating systems (e.g., macOS).
```
FreeBsd
```
A free Unix-like operating system descended from AT&T’s UNIX.
```
OpenBsd
```
A free Unix-like operating system forked from NetBSD.
```
Linux
```
The Linux kernel is the base for many Unix-like operating systems like Debian.
```
SunOs
```
The Unix-like operating system SunOS is used as a core for other distributions like Solaris.
```
OtherOs(String)
```
An operating system not represented by the other options.

OsFamily

</>

Represents families of operating systems.

pub type OsFamily {
  Unix(Os)
  Windows
}

Constructors

```
Unix(Os)
```
The operating system is part of the Unix family.
```
Windows
```
The operating system is part of the Windows family.

Functions

cwd

</>

pub fn cwd() -> Option(String)

Returns the current working directory.

This function returns an Option because it can fail on Unix-like systems in rare circumstances.

Example

case gleamyshell.cwd() {
  Some(working_directory) ->
    io.println("Current working directory: " <> working_directory)
  None -> io.println("Couldn't detect the current working directory.")
}

env

</>

pub fn env(identifier: String) -> Option(String)

Returns the value of the given environment variable if it is set.

Example

case gleamyshell.env("JAVA_HOME") {
  Some(dir) -> io.println("Java runtime location: " <> dir)
  None -> 
    io.println("The location of the Java runtime could not be found.")
}

execute

</>

pub fn execute(
  executable: String,
  in working_directory: String,
  args args: List(String),
) -> Result(String, CommandError)

Executes the given command with arguments.

Example

case gleamyshell.execute("whoami", in: ".", args: []) {
  Ok(username) ->
    io.println("Hello there, " <> string.trim(username) <> "!")
  Error(Failure(output, exit_code)) ->
    io.println(
      "Whoops!\nError ("
      <> int.to_string(exit_code)
      <> "): "
      <> string.trim(output),
    )
  Error(Abort(_)) -> io.println("Something went terribly wrong.")
}

home_directory

</>

pub fn home_directory() -> Option(String)

Returns the home directory of the current user.

This function returns an Option because it can fail in rare circumstances.

Example

case gleamyshell.home_directory() {
  Some(home_directory) -> io.println("Home directory: " <> home_directory)
  None ->
    io.println("Couldn't detect the home directory of the current user.")
}

os

</>

pub fn os() -> OsFamily

Returns information about the host’s operating system.

Example

case gleamyshell.os() {
  Windows -> io.println("Doing stuff on Windows.")
  Unix(_) -> io.println("Doing stuff on a Unix(-like) system.")
}

set_env

</>

pub fn set_env(
  name identifier: String,
  value value: String,
) -> Bool

Sets an environment variable.

Due to portability and sanity reasons, identifiers of environment variables must consist solely of digits, letters and underscores, and must not begin with a digit.

In a nutshell, the identifier must match this regex pattern: ^[a-zA-Z_]+[a-zA-Z0-9_]*$

Example

case gleamyshell.set_env(name: "FANCY_ENV", value: "fancy value") {
  True -> io.println("Now we can do fancy things.")
  False -> io.println("It probably wasn't fancy enough.")
}

unset_env

</>

pub fn unset_env(identifier: String) -> Bool

Unsets an environment variable.

Example

case gleamyshell.unset_env("DELETE_ME") {
  True -> io.println("Bye bye!")
  False -> io.println("This shouldn't have happened …")
}

which

</>

pub fn which(executable: String) -> Option(String)

Returns the location of the given executable if it could be found.

Example

case gleamyshell.which("git") {
  Some(_) -> io.println("Doing something with Git.")
  None -> io.println("Git could not be found.")
}