Process

Process related utilities. More...

Classes
struct	sourcemeta::core::ProcessInput
struct	sourcemeta::core::ProcessOutput
class	sourcemeta::core::ProcessProgramNotFoundError
class	sourcemeta::core::ProcessSpawnError

Functions
SOURCEMETA_CORE_PROCESS_EXPORT auto	sourcemeta::core::spawn (const std::string &program, std::initializer_list< std::string_view > arguments, const ProcessInput &input={}) -> int
SOURCEMETA_CORE_PROCESS_EXPORT auto	sourcemeta::core::spawn (const std::string &program, std::span< const std::string_view > arguments, const ProcessInput &input={}) -> int
SOURCEMETA_CORE_PROCESS_EXPORT auto	sourcemeta::core::spawn_and_capture (const std::string &program, std::initializer_list< std::string_view > arguments, const ProcessInput &input={}) -> ProcessOutput
SOURCEMETA_CORE_PROCESS_EXPORT auto	sourcemeta::core::spawn_and_capture (const std::string &program, std::span< const std::string_view > arguments, const ProcessInput &input={}) -> ProcessOutput

Detailed Description

Process related utilities.

This functionality is included as follows:

#include <sourcemeta/core/process.h>

---

Class Documentation

sourcemeta::core::ProcessInput

struct sourcemeta::core::ProcessInput

The settings for running a program.

Every member carries a default so that naming only the ones that matter stays free of missing-initializer warnings.

Public Attributes
std::filesystem::path	directory {std::filesystem::current_path()}
std::optional< std::map< std::string_view, std::string_view > >	environment
std::string_view	standard_input {}

Member Data Documentation

directory

std::filesystem::path sourcemeta::core::ProcessInput::directory {std::filesystem::current_path()}

The working directory of the program. It must be an absolute path to an existing directory

environment

std::optional<std::map<std::string_view, std::string_view> > sourcemeta::core::ProcessInput::environment

Initial value:

{
      std::nullopt}

The entire environment of the program, replacing rather than extending the environment of the caller. Without a value, the caller's environment is inherited as it stands. The referenced names and values must outlive the call

standard_input

std::string_view sourcemeta::core::ProcessInput::standard_input {}

The bytes to feed the program on its standard input. The referenced buffer must outlive the call

sourcemeta::core::ProcessOutput

struct sourcemeta::core::ProcessOutput

The result of running a program while capturing what it writes.

Public Attributes
std::optional< int >	exit_code {std::nullopt}
std::string	standard_output {}
	Everything the program wrote to its standard output.
std::string	standard_error {}
	Everything the program wrote to its standard error.

Member Data Documentation

exit_code

std::optional<int> sourcemeta::core::ProcessOutput::exit_code {std::nullopt}

The code the program exited with, or no value if it terminated abnormally, such as by a signal

sourcemeta::core::ProcessProgramNotFoundError

class sourcemeta::core::ProcessProgramNotFoundError

An executable program could not be found

Inheritance diagram for sourcemeta::core::ProcessProgramNotFoundError:

Public Member Functions
	ProcessProgramNotFoundError (const std::string_view program)
	Construct the error given the offending program.
auto	program () const noexcept -> std::string_view
	The offending program.

sourcemeta::core::ProcessSpawnError

class sourcemeta::core::ProcessSpawnError

A spawned process terminated abnormally

Inheritance diagram for sourcemeta::core::ProcessSpawnError:

Public Member Functions
	ProcessSpawnError (const std::string_view program, std::initializer_list< std::string_view > arguments)
	Construct the error given the offending program and its arguments.
	ProcessSpawnError (const std::string_view program, std::span< const std::string_view > arguments)
	Construct the error given the offending program and its arguments.
auto	program () const noexcept -> std::string_view
	The offending program.
auto	arguments () const noexcept -> const std::vector< std::string > &
	The arguments the program was spawned with.

Function Documentation

spawn() [1/2]

SOURCEMETA_CORE_PROCESS_EXPORT auto sourcemeta::core::spawn	(	const std::string &	program,
		std::initializer_list< std::string_view >	arguments,
		const ProcessInput &	input = {} ) -> int

Spawn a program piping its output to the current stdio configuration.

#include <sourcemeta/core/process.h>
#include <cassert>
 
const auto exit_code{sourcemeta::core::spawn("echo", {"foo"})};
assert(exit_code == 0);

spawn() [2/2]

SOURCEMETA_CORE_PROCESS_EXPORT auto sourcemeta::core::spawn	(	const std::string &	program,
		std::span< const std::string_view >	arguments,
		const ProcessInput &	input = {} ) -> int

Spawn a program piping its output to the current stdio configuration. This overload accepts a span for dynamic argument lists.

#include <sourcemeta/core/process.h>
#include <vector>
#include <string_view>
#include <cassert>
 
std::vector<std::string_view> arguments{"foo", "bar"};
const auto exit_code{sourcemeta::core::spawn("echo", arguments)};
assert(exit_code == 0);

spawn_and_capture() [1/2]

SOURCEMETA_CORE_PROCESS_EXPORT auto sourcemeta::core::spawn_and_capture	(	const std::string &	program,
		std::initializer_list< std::string_view >	arguments,
		const ProcessInput &	input = {} ) -> ProcessOutput

Spawn a program, feeding it the given input and capturing both of its output streams in full.

#include <sourcemeta/core/process.h>
#include <cassert>
 
const auto result{sourcemeta::core::spawn_and_capture("echo", {"foo"})};
assert(result.exit_code.value() == 0);
assert(result.standard_output == "foo\n");

spawn_and_capture() [2/2]

SOURCEMETA_CORE_PROCESS_EXPORT auto sourcemeta::core::spawn_and_capture	(	const std::string &	program,
		std::span< const std::string_view >	arguments,
		const ProcessInput &	input = {} ) -> ProcessOutput

Spawn a program, feeding it the given input and capturing both of its output streams in full. This overload accepts a span for dynamic argument lists.

#include <sourcemeta/core/process.h>
#include <vector>
#include <string_view>
#include <cassert>
 
std::vector<std::string_view> arguments{"foo", "bar"};
const auto result{sourcemeta::core::spawn_and_capture("echo", arguments)};
assert(result.exit_code.value() == 0);
assert(result.standard_output == "foo bar\n");