Skip to content

Entrypoint & Internal API

ensure.sh

Entrypoint as well as internal API for writing Ensure functions, for platform-independent nice logging, error handline, sudo support, etc.

This file can be used in the following two ways:

  1. To use Ensure for your own script, source this file in your script, and you can use all the ensure_... functions.
  2. To write your own functions, create a file named ensure_<name>.sh in the same directory as this file, and define your functions there.

This ensure.sh file will source all files named ensure_*.sh in the same directory. You must not include this file from any ensure_*.sh file in this directory!

Functions

__ensure_caller

Logging helper to get the first call-stack file:line that's not from ensure, should be the line where an ensure_... function is called from.

Standard output

  • /path/to/file.sh:12

__ensure_funcname

Logging helper to get the first call-stack function that's not ensure-internal, i.e. the line where an __ensure_... function is called from.

Standard output

  • ensure_... or main

__ensure_warn

Print a warning message in Ensure's standard format.

Arguments
  • {msg...}:

    The message to print.

Standard output

  • [WARN] $funcname: $* ($caller)

__ensure_fail

Print a failure message in Ensure's standard format.

Warning: This function is just for logging and does not return an error code, you still have to return/exit yourself afterwards!

Arguments
  • {msg...}:

    The message to print.

Standard output

  • [FAIL] $funcname: $* ($caller)

__ensure_info

Print an informational message in Ensure's standard format.

Arguments
  • {msg...}:

    The message to print.

Standard output

  • [INFO] $funcname: $* ($caller)

__ensure_debug

Print a debug message in Ensure's standard format.

Arguments
  • {msg...}:

    The message to print.

Pre-conditions

  • If $ENSURE_QUIET is 0, this function does nothing.

Standard output

  • [DEBUG] $funcname: $* ($caller)

__ensure_sudo

Run a command as root with either sudo, or whatever is configured as the privilege escalation command on the system.

You should always use this function instead of directly calling sudo when you want to do something as root.

Arguments
  • {cmd...}:

    The command to run as root.

__ensure_is_writable

Check whether the next-highest existing path component (including the file itself if it exists) is writable by the current user, and in the case of directories whether it is executable as well. You can then continue with e.g. mkdir -p "$(dirname "$file")" and then create the file without having to worry about permissions.

Arguments
  • {file}:

    The file that should be checked.

Return codes
  • Returns:

    1 if the current user does not have write permissions, 0 otherwise.

__ensure_sudo_if_unwritable

Run a command with sudo if a given file is unaccessible, or without sudo otherwise.

Arguments
  • {file}:

    The file that needs to be writable to skip sudo.

  • {cmd...}:

    The command or other arguments to __ensure_sudo.