bob::Cmd Class Reference

Represents a command to be executed in the operating system shell. More...

#include <bob.hpp>

Public Member Functions
	Cmd ()=default
	Creates an empty command.
	Cmd (vector< string > &&parts, path root=".")
Cmd &	push (const string &part)
Cmd &	push_many (const vector< string > &parts)
string	render () const
CmdFuture	run_async () const
int	run ()
void	check ()
void	clear ()
bool	poll_future (CmdFuture &fut)
int	await_future (CmdFuture &fut)

Public Attributes
bool	capture_output = false
	If true, the command's output will be captured.
bool	silent = false
	If true, the command will not print its output to stdout.
string	output_str = ""
	The command's output captured during execution (stdout and stderr).
path	root = "."
	The root directory from which the command is executed.

Detailed Description

Represents a command to be executed in the operating system shell.

This class allows building command lines from parts (strings or paths), running them synchronously or asynchronously, and optionally capturing their output. It supports managing execution context such as the root directory and controlling output visibility (using the silent field).

Example - Synchronous Command Execution

Cmd compile({"g++", I("src"), "-o", "output"});
compile.capture_output = true;
int status = compile.run();
if (status != 0) {
    std::cerr << "Compilation failed:\n" << compile.output_str;
}

Example - Asynchronous Command Execution

Cmd cmd({"sleep", "3"}); // Heavy work
CmdFuture fut = cmd.run_async();
while (!fut.done) {
    cmd.poll_future(fut);
    std::cout << "waiting for command to finish...\n";
    usleep(100000); // sleep for 100ms
}
std::cout << "Command finished with exit code: " << fut.exit_code << "\n";

Examples

minimal/bob.cpp, parallel-cmds/bob.cpp, and recipe/bob.cpp.

Constructor & Destructor Documentation

Cmd()

bob::Cmd::Cmd	(	vector< string > &&	parts,
		path	root = "."
	)

Creates a command from a list of parts and optional root directory.

Parameters

parts	The command and its arguments as string parts.
root	The root directory where the command runs (default is current directory).

Example

Cmd compile({"g++", "-o", "app"}, "/home/user/project");

Member Function Documentation

await_future()

int bob::Cmd::await_future

(

CmdFuture &

fut

)

Waits for an asynchronous command to finish and captures its output.

Parameters

fut	The CmdFuture object representing the running command.

Returns

The command's exit status.

Example

Cmd cmd({"sleep", "3"});
CmdFuture fut = cmd.run_async();
int exit_code = cmd.await_future(fut);

check()

void bob::Cmd::check

(

)

Runs the command and throws if the exit status is not zero.

Exceptions

std::runtime_error

if the command exits with a non-zero status.

Example

Cmd cmd({"echo", "Hello, World!"});
cmd.check(); // throws if command failed

clear()

void bob::Cmd::clear

(

)

Clears all parts of the command so it can be reused.

Example

Cmd cmd({"echo", "Hello"});
cmd.run();
 
cmd.clear();
cmd.push("echo").push(" world!");
cmd.run();

poll_future()

bool bob::Cmd::poll_future

(

CmdFuture &

fut

)

Polls an ongoing asynchronous command to check if it has finished. Captures and prints output based on the capture_output and silent fields.

Parameters

fut	The CmdFuture object representing the running command.

Returns

True if the command has completed; false otherwise.

Example

Cmd cmd({"sleep", "3"}); // Heavy work
CmdFuture fut = cmd.run_async();
while (!cmd.poll_future(fut)) {
    std::cout << "Waiting..." << std::endl;
}
std::cout << "Done!" << std::endl;;

push()

Cmd & bob::Cmd::push

(

const string &

part

)

Adds a single part (argument or command) to the command.

Parameters

part	The part to add.

Returns

Reference to this command (for chaining).

Example

Cmd cmd;
cmd.push("g++").push("app.c").push("-o").push("app");

Examples

parallel-cmds/bob.cpp, and recipe/bob.cpp.

push_many()

Cmd & bob::Cmd::push_many

(

const vector< string > &

parts

)

Adds multiple string parts to the command.

Parameters

parts

The parts to add.

Returns

Reference to this command.

Example

const vector<string> FLAGS = {"-Wall", "-O2"};
const string COMPILER = "g++";
Cmd cmd;
cmd
    .push_many({COMPILER, "app.c", "-o", "app"})
    .push_many(FLAGS);

render()

string bob::Cmd::render

(

)

const

Creates a printable string representation of the command.

Returns

The command rendered as a string.

Example

Cmd cmd({"ls", "-la"});
std::cout << cmd.render() << std::endl; // prints: "ls -la"

run()

int bob::Cmd::run

(

)

Runs the command synchronously and returns its exit status.

Returns

The command's exit code.

Example

Cmd cmd({"seq", "1000"});
int status = cmd.run();
if (status != 0) { /* handle error *‍/ }

Examples

minimal/bob.cpp, parallel-cmds/bob.cpp, and recipe/bob.cpp.

run_async()

CmdFuture bob::Cmd::run_async

(

)

const

Runs the command asynchronously and returns a future object.

Returns

A CmdFuture object representing the running command.

Example

Cmd cmd({"sleep", "3"}); // Heavy work
CmdFuture fut = cmd.run_async();
// Do other work, then await or poll fut...

---

The documentation for this class was generated from the following file:

• bob.hpp