Please API

The Please API can be imported and used on any of the JavaScript files in the Please repository, there is no need to install it. The please API can be accessed under @please.dev/lib namespace.

Core

Please core exports three functions:

core

const { core } = require("@please.dev/lib/core");
core({ argv, cargv })

The core async function gets parsed please arguments in argv, and raw command arguments in cargv. It reads the please configuration, bootstraps the repository, and finally runs the command using the @please.dev/lib/core/run function.

run

const { run } = require("@please.dev/lib/core/run");
run(command, argv, config);

The run async function expects a command name, an argv to be passed to the command, and the please specific config argument. It checks for the existence of the command in the current environment, if it exists it will be spawned and the process will be returned, otherwise depending on the configuration, one of the install, prebuilt, build or script files (if found) will run. If method is script, the run function of the script gets executed and the result is returned, otherwise the command is spawned and returned after the installation is complete.

getCommand

const { getCommand } = require("@please.dev/lib/core/get");
getCommand(command, config);

The getCommand async function expects a command name and the please specific config argument. It checks for the preferred installation method in the config, gets appropriate file names for the current environment, runs the first matched file and returns the result.

Utils

The utils submodule provides a few useful functions for doing simple but repetitive tasks.

sudo

const { sudo } = require("@please.dev/lib/utils/sudo");
sudo(command);

The sudo function expects a command name or a full command. It checks if the user is root, and if the sudo command is available. If both checks pass, it will prefix the input command with sudo and return it.

home

const { home } = require("@please.dev/lib/utils/home");
home(...names);

The home function expects one or more names. It joins the home directory of the current user and names together using the path.join node module, then returns it as its result.

spawn

const { spawn } = require("@please.dev/lib/utils/spawn");
spawn(command, argv, config);

The spawn command expects a command name, an argv to be passed to the command, and the please config argument. It simply checks if the stdio should be silenced based on the provided config or not, then it will spawn the command using the appropriate stdio and return the spawned process.

Log

The log submodule includes all the functions used for logging.

info

const { info } = require("@please.dev/lib/log");
info({ text, config, level = 3, progress = false });

The info function expects an object as input. The level field defines the importance level of the info message, use 3 for important, and 4 for non-important messages. Depending on the level field and the log level defined in the config, the info function may or may not display the value of the text field to the user. If progress is set to true, an animated circular progress symbol will be displayed to the user before the text field, in that case the function returns a progress object. The spinner can be stoped using the progress.stop() method.

progress

const { progress } = require("@please.dev/lib/log");
progress({ text, config, level = 3 });

Calls the info function, setting progress field to true.

warn

const { warn } = require("@please.dev/lib/log");
warn({ text, config });

The warn function expects an object as input. Depending on the log level defined in the config, the warn function may or may not display the value of the text field to the user.

error

const { error } = require("@please.dev/lib/log");
error({ text, config, exit = true });

The error function expects an object as input. Depending on the log level defined in the config, the error function may or may not display the value of the text field to the user. If exit is set to true, the error function will exit the process after displaying the error message, this is the default behavior.

message

const { message } = require("@please.dev/lib/log");
message({ text, progress, color, config, level });

The message function expects an object as input. The message is used to implement all the above log functions. The text field gets printed depending on the importance level of the message and also the log level defined in the config. The color field defines the color of the progress symbol, if the progress field is set to true. In order to print a colorized message, you must use chalk to colorize the text field yourself.

OS

The os module contains functions to get information about the current environment, and also provides the utilities to work with common operating systems and their package managers.

getOSInfo

const { getOSInfo } = require("@please.dev/lib/os");
getOSInfo();

The getOSInfo async function, once called returns the following information about the current environment:

{ os, arch, variant, release }

Where

• os is one of linux, windows, macos, or bsd.
• arch is the value returned by the os.arch() function of Node.js modules.
• variant is the distro name for Linux, major.minor version number for Windows, release name for macOS, and one of freebsd or openbsd for BSD.
• release is the distro version number for Linux, build number for Windows, Darwin kernel version for macOS, release version for BSD.

managers

const { managers } = require("@please.dev/lib/os");

The managers object holds all manager objects defined by the os.managers submodule. The keys of the managers object are the OS names, and the values are the manager objects for the key OS respectively. The following operating systems are currently implemented:

Name	Key
Apine	alpine
Arch	arch
Debian	debian
macOS	macos
Raspbian	raspbian
Ubuntu	ubuntu

Note that managers can be imported directly and individually:

const { ubuntu } = require("@please.dev/lib/os/managers/ubuntu");

manager.install

const { managers } = require("@please.dev/lib/os");
managers.ubuntu.install(names, argv, config);

The install function expects an array of names to install, an array argv to pass to the install command, and the Please config object. This command executes a package installation using the default package manager of the chosen OS.

manager.uninstall

const { managers } = require("@please.dev/lib/os");
managers.ubuntu.uninstall(names, argv, config);

The uninstall function expects an array of names to uninstall, an array argv to pass to the uninstall command, and the Please config object. This command executes a package uninstallation using the default package manager of the chosen OS.

manager.repo

const { managers } = require("@please.dev/lib/os");
managers.ubuntu.repo

The repo object includes functions to manage software repositories for the default package manager of the chosen OS.

manager.repo.update

const { managers } = require("@please.dev/lib/os");
managers.ubuntu.repo.update(argv, config)

The repo.update function, expects an array of argv to pass to the repository update command, and also the Please config to decide on its stdio. This function simply fetches the latest repository data and updates the repository database for the default package manager of the chosen OS.

Examples

You can check out the Ubuntu docker install file for example usage of the above functions.