alib::system::TShellCommand< TAllocator > Class Template Reference

Description:

template<typename TAllocator = lang::HeapAllocator>
class alib::system::TShellCommand< TAllocator >

TShellCommand provides a lightweight interface for executing external shell commands and capturing their output. It reads from the command’s standard output stream and accumulates the text in a buffer. The captured output is split into individual lines and stored in the class’s underlying TStringVector;StringVector". \par Usage options: - Pure static usage: Call the static Run method with a target buffer and an optional vector for collecting lines. The new output is appended to the provided buffer; if a vector is supplied, the newly captured portion is tokenized into lines and added to it. - Instance-based usage: Create an instance and call its non-static Run method. By default, this clears the instance’s buffer and line vector before executing. To preserve the current content and append new output, pass Keep. Method Run can be sequentially invoked multiple times to aggregate the output of several shell commands. With the static Run variant, the same buffer and vector is to be passed to continue appending. With the non-static Run, parameter <span>keepCurrent</span> controls whether existing content is retained or not. @see This is a very simple wrapper type. For example, no blocking or timely shell commands can be handled. While simple, relient commands can be invoked with this class, more complicated cases should be handled with alternatives, as: - <a href="https://www.boost.org/doc/libs/latest/libs/process/doc/html/index.html" >boost.process <img src="external_link.svg" height="12" width="10"></a> - <a href="https://docs.pocoproject.org/current/Poco.Process.html" >POCO Process <img src="external_link.svg" height="12" width="10"></a>, or - <a href="https://github.com/arun11299/cpp-subprocess" >cpp-subprocess <img src="external_link.svg" height="12" width="10">.

Definition at line 43 of file shellcommand.inl.

Inheritance diagram for alib::system::TShellCommand< TAllocator >:

Public Type Index:
using	AllocatorType = TAllocator
	The allocator type that TAllocator specifies.
using	StringVector = strings::util::TStringVector<nchar, TAllocator>
	The base type of this class.
Public Type Index: inherited from alib::strings::util::TStringVector< nchar, lang::HeapAllocator >
using	AllocatorType
	The allocator type that TAllocator specifies.

Public Static Method Index:
static int	Run (const NCString &cmd, strings::TAString< nchar, AllocatorType > &readBuffer, StringVector *lines=nullptr)

Public Field Index:
strings::TAString< nchar, AllocatorType >	ReadBuffer
	The input buffer, collecting the output of the invoked shell command(s).

Public Method Index:
	TShellCommand ()
	Default constructor. Usable with type HeapAllocator.
	TShellCommand (AllocatorType &ma)
int	Run (const NCString &cmd, lang::CurrentData keepData=lang::CurrentData::Clear)
Public Method Index: inherited from alib::strings::util::TStringVector< nchar, lang::HeapAllocator >
	TStringVector ()
	Constructor.
	TStringVector (AllocatorType &pAllocator)
	~TStringVector ()=default
	Destructor.
integer	Add (const strings::TString< nchar > &src)
AllocatorType &	GetAllocator () noexcept
integer	Size () const noexcept
String	TryGet (integer idx)

Additional Inherited Members
Protected Type Index: inherited from alib::strings::util::TStringVector< nchar, lang::HeapAllocator >
using	vectorBase
	The vector type that TAllocator specifies.

Type Definition Details:

AllocatorType

template<typename TAllocator = lang::HeapAllocator>

using alib::system::TShellCommand< TAllocator >::AllocatorType = TAllocator

The allocator type that TAllocator specifies.

Definition at line 47 of file shellcommand.inl.

StringVector

template<typename TAllocator = lang::HeapAllocator>

using alib::system::TShellCommand< TAllocator >::StringVector = strings::util::TStringVector<nchar, TAllocator>

The base type of this class.

Definition at line 50 of file shellcommand.inl.

Field Details:

ReadBuffer

template<typename TAllocator = lang::HeapAllocator>

strings::TAString<nchar, AllocatorType> alib::system::TShellCommand< TAllocator >::ReadBuffer

The input buffer, collecting the output of the invoked shell command(s).

Definition at line 53 of file shellcommand.inl.

Constructor(s) / Destructor Details:

TShellCommand() [1/2]

template<typename TAllocator = lang::HeapAllocator>

alib::system::TShellCommand< TAllocator >::TShellCommand ( )

inline

Default constructor. Usable with type HeapAllocator.

Definition at line 56 of file shellcommand.inl.

TShellCommand() [2/2]

template<typename TAllocator = lang::HeapAllocator>

alib::system::TShellCommand< TAllocator >::TShellCommand ( AllocatorType & ma )

inline

Constructor taking an allocator.

Parameters

ma	The allocator to use.

Definition at line 60 of file shellcommand.inl.

Method Details:

Run() [1/2]

template<typename TAllocator = lang::HeapAllocator>

int alib::system::TShellCommand< TAllocator >::Run ( const NCString & cmd, lang::CurrentData keepData = lang::CurrentData::Clear )

inline

Executes the given command-line by invoking the static variant of this method passing member ReadBuffer and the inherited string vector (*this).

Parameters

cmd	The command to execute.
keepData	Denotes whether any prior results are kept or not.

Returns

The exit-code of the command. If -1 errno is set.

Definition at line 70 of file shellcommand.inl.

Run() [2/2]

template<typename TAllocator = lang::HeapAllocator>

int alib::system::TShellCommand< TAllocator >::Run ( const NCString & cmd, strings::TAString< nchar, AllocatorType > & readBuffer, StringVector * lines = nullptr )

inlinestatic

Executes the given command-line.
The given readBuffer and vector lines are not reset. Instead the command result is appended to both. If this is not wanted, methods Reset and clear have to be invoked prior to calling this method.

Parameters

cmd	The command to execute.
readBuffer	A string buffer to receive the command's output.
lines	An optional pointer to a vector of strings, which receives the lines of the output text.

Returns

The exit-code of the command. If -1 errno is set.

Definition at line 87 of file shellcommand.inl.

---

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

• shellcommand.inl