Description

Input stream for command line arguments.

A cursor is an ordered set of strings and a current position in that set.

Definition at line 255 of file Sawyer/CommandLine.h.

#include <Sawyer/CommandLine.h>

Public Member Functions
	Cursor (const std::vector< std::string > &strings)
	Construct a cursor from an ordered set of strings.

	Cursor (const std::string &string)
	Constructs a cursor for a single string.

	Cursor ()
	Constructs a not-very-useful cursor to nothing.

const std::vector< std::string > &	strings () const
	All strings for the cursor.

bool	atArgBegin () const
	True when the cursor is at the beginning of an argument.

bool	atArgEnd () const
	True when the cursor is at the end of an argument.

void	replace (const std::vector< std::string > &)
	Replace the current string with new strings.

void	consumeChars (size_t nchars)
	Advance over characters.

size_t	linearDistance () const
	Number of characters from the beginning of the cursor to its current location.


const Location &	location () const
	Property: current position of the cursor.

Cursor &	location (const Location &loc)
	Property: current position of the cursor.


bool	atEnd () const
	Returns true when the cursor is after all arguments.

bool	atEnd (const Location &location) const
	Returns true when the cursor is after all arguments.


const std::string &	arg () const
	Return the entire current program argument regardless of where the cursor is in that argument.

const std::string &	arg (const Location &location) const
	Return the entire current program argument regardless of where the cursor is in that argument.


std::string	rest () const
	Return the part of an argument at and beyond the cursor location.

std::string	rest (const Location &location) const
	Return the part of an argument at and beyond the cursor location.


std::string	substr (const Location &limit, const std::string &separator=" ") const
	Returns all characters within limits.

std::string	substr (const Location &limit1, const Location &limit2, const std::string &separator=" ") const
	Returns all characters within limits.


void	consumeArgs (size_t nargs)
	Advance the cursor to the beginning of the next string.

void	consumeArg ()
	Advance the cursor to the beginning of the next string.

Constructor & Destructor Documentation

◆ Cursor() [1/3]

Sawyer::CommandLine::Cursor::Cursor ( const std::vector< std::string > & strings )

inline

Construct a cursor from an ordered set of strings.

The cursor's initial position is the first character of the first string, or the end if the set contains no strings or contains only empty strings.

Definition at line 263 of file Sawyer/CommandLine.h.

◆ Cursor() [2/3]

Sawyer::CommandLine::Cursor::Cursor ( const std::string & string )

inline

Constructs a cursor for a single string.

The cursor's initial position is the first character of the string, or the end if the string is empty.

Definition at line 267 of file Sawyer/CommandLine.h.

◆ Cursor() [3/3]

Sawyer::CommandLine::Cursor::Cursor ( )

inline

Constructs a not-very-useful cursor to nothing.

Definition at line 270 of file Sawyer/CommandLine.h.

Member Function Documentation

◆ strings()

const std::vector< std::string > & Sawyer::CommandLine::Cursor::strings ( ) const

inline

All strings for the cursor.

Definition at line 273 of file Sawyer/CommandLine.h.

Referenced by Sawyer::CommandLine::ParserResult::allArgs().

◆ location() [1/2]

const Location & Sawyer::CommandLine::Cursor::location ( ) const

inline

Property: current position of the cursor.

The following semantics apply to the location:

The location's idx member will either point to a valid string in the cursor's strings vector, or it will be equal to the size of that vector.
When the idx member is equal to the size of the cursor's strings vector, the cursor is said to be at the end of its input and atEnd returns true.
The location's offset member is zero whenever atEnd returns true.
When atEnd returns false, the offset is less than or equal to the length of the string indexed by idx.
When atEnd returns false and offset is equal to the string length, then the cursor is said to be positioned at the end of an argument and atArgEnd returns true.

When a new location is provided it will be immediately adjusted so that the idx member is not greater than the number of strings in the cursor, and its offset member is less than or equal to the length of that string (or zero when idx is equal to the number of strings).

Definition at line 292 of file Sawyer/CommandLine.h.

◆ location() [2/2]

Cursor & Sawyer::CommandLine::Cursor::location ( const Location & loc )

Property: current position of the cursor.

The following semantics apply to the location:

The location's idx member will either point to a valid string in the cursor's strings vector, or it will be equal to the size of that vector.
When the idx member is equal to the size of the cursor's strings vector, the cursor is said to be at the end of its input and atEnd returns true.
The location's offset member is zero whenever atEnd returns true.
When atEnd returns false, the offset is less than or equal to the length of the string indexed by idx.
When atEnd returns false and offset is equal to the string length, then the cursor is said to be positioned at the end of an argument and atArgEnd returns true.

When a new location is provided it will be immediately adjusted so that the idx member is not greater than the number of strings in the cursor, and its offset member is less than or equal to the length of that string (or zero when idx is equal to the number of strings).

◆ atArgBegin()

bool Sawyer::CommandLine::Cursor::atArgBegin ( ) const

inline

True when the cursor is at the beginning of an argument.

Returns true if the cursor points to an argument and is at the beginning of that argument. Returns false otherwise, including when atEnd returns true.

Definition at line 298 of file Sawyer/CommandLine.h.

References Sawyer::CommandLine::Location::idx, and Sawyer::CommandLine::Location::offset.

◆ atArgEnd()

bool Sawyer::CommandLine::Cursor::atArgEnd ( ) const

inline

True when the cursor is at the end of an argument.

Returns true if the cursor points to an argument and is positioned past the end of that string. Returns false otherwise, including when atEnd returns true.

Definition at line 302 of file Sawyer/CommandLine.h.

References Sawyer::CommandLine::Location::idx, and Sawyer::CommandLine::Location::offset.

◆ atEnd() [1/2]

bool Sawyer::CommandLine::Cursor::atEnd ( ) const

inline

Returns true when the cursor is after all arguments.

When the cursor is after all arguments, then atArgBegin and atArgEnd both return false. A locaton can be specified to override the location that's inherent to this cursor without changing this cursor.

Definition at line 308 of file Sawyer/CommandLine.h.

References atEnd().

Referenced by atEnd().

◆ atEnd() [2/2]

bool Sawyer::CommandLine::Cursor::atEnd ( const Location & location ) const

inline

Returns true when the cursor is after all arguments.

When the cursor is after all arguments, then atArgBegin and atArgEnd both return false. A locaton can be specified to override the location that's inherent to this cursor without changing this cursor.

Definition at line 309 of file Sawyer/CommandLine.h.

References Sawyer::CommandLine::Location::idx.

◆ arg() [1/2]

const std::string & Sawyer::CommandLine::Cursor::arg ( ) const

inline

Return the entire current program argument regardless of where the cursor is in that argument.

A location can be specified to override the location that's inherent to this cursor without changing this cursor. It is an error to call this when atEnd returns true.

Definition at line 316 of file Sawyer/CommandLine.h.

References arg().

Referenced by arg().

◆ arg() [2/2]

const std::string & Sawyer::CommandLine::Cursor::arg ( const Location & location ) const

Return the entire current program argument regardless of where the cursor is in that argument.

A location can be specified to override the location that's inherent to this cursor without changing this cursor. It is an error to call this when atEnd returns true.

◆ rest() [1/2]

std::string Sawyer::CommandLine::Cursor::rest ( ) const

inline

Return the part of an argument at and beyond the cursor location.

If the cursor is positioned at the end of an argument then an empty string is returned. A location can be specified to override the location that's inherent to this cursor without changing this cursor. Returns an empty string if called when atEnd returns true.

Definition at line 324 of file Sawyer/CommandLine.h.

References rest().

Referenced by rest().

◆ rest() [2/2]

std::string Sawyer::CommandLine::Cursor::rest ( const Location & location ) const

Return the part of an argument at and beyond the cursor location.

If the cursor is positioned at the end of an argument then an empty string is returned. A location can be specified to override the location that's inherent to this cursor without changing this cursor. Returns an empty string if called when atEnd returns true.

◆ substr() [1/2]

std::string Sawyer::CommandLine::Cursor::substr	(	const Location &	limit,
		const std::string &	separator = `" "`
	)		const

inline

Returns all characters within limits.

Returns all the characters between this cursor's current location and the specified location, which may be left or right of the cursor's location. The two argument version uses the two specified locations rather than this cursor's current location. The separator string is inserted between text that comes from two different strings.

See also: linearDistance

Definition at line 333 of file Sawyer/CommandLine.h.

References substr().

Referenced by substr().

◆ substr() [2/2]

std::string Sawyer::CommandLine::Cursor::substr	(	const Location &	limit1,
		const Location &	limit2,
		const std::string &	separator = `" "`
	)		const

Returns all characters within limits.

Returns all the characters between this cursor's current location and the specified location, which may be left or right of the cursor's location. The two argument version uses the two specified locations rather than this cursor's current location. The separator string is inserted between text that comes from two different strings.

See also: linearDistance

◆ replace()

void Sawyer::CommandLine::Cursor::replace ( const std::vector< std::string > & )

Replace the current string with new strings.

Repositions the cursor to the beginning of the first inserted string. Must not be called when atEnd returns true.

◆ consumeChars()

void Sawyer::CommandLine::Cursor::consumeChars ( size_t nchars )

Advance over characters.

Advances the cursor's current location by nchars characters. The cursor must be positioned so that at least nchars characters can be skipped in the current string. This call does not advance the cursor to the next string.

◆ consumeArgs()

void Sawyer::CommandLine::Cursor::consumeArgs ( size_t nargs )

inline

Advance the cursor to the beginning of the next string.

If the cursor is already positioned at the last string then it will be positioned to the end and atEnd will return true. It is permissible to call this method when atEnd already returns true, in which case nothing happens.

Definition at line 350 of file Sawyer/CommandLine.h.

References Sawyer::CommandLine::Location::idx, and Sawyer::CommandLine::Location::offset.

◆ consumeArg()

void Sawyer::CommandLine::Cursor::consumeArg ( )

inline

Advance the cursor to the beginning of the next string.

If the cursor is already positioned at the last string then it will be positioned to the end and atEnd will return true. It is permissible to call this method when atEnd already returns true, in which case nothing happens.

Definition at line 354 of file Sawyer/CommandLine.h.

◆ linearDistance()

size_t Sawyer::CommandLine::Cursor::linearDistance ( ) const

Number of characters from the beginning of the cursor to its current location.

This is the same as calling

substr(Location(), "").size()

Sawyer::CommandLine::Cursor::substr

std::string substr(const Location &limit, const std::string &separator=" ") const

Returns all characters within limits.

Definition Sawyer/CommandLine.h:333

Sawyer::CommandLine::Location

Position within a command-line.

Definition Sawyer/CommandLine.h:216

but faster.

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

Sawyer/CommandLine.h

Description

Public Member Functions

Constructor & Destructor Documentation

◆ Cursor() [1/3]

◆ Cursor() [2/3]

◆ Cursor() [3/3]

Member Function Documentation

◆ strings()

◆ location() [1/2]

◆ location() [2/2]

◆ atArgBegin()

◆ atArgEnd()

◆ atEnd() [1/2]

◆ atEnd() [2/2]

◆ arg() [1/2]

◆ arg() [2/2]

◆ rest() [1/2]

◆ rest() [2/2]

◆ substr() [1/2]

◆ substr() [2/2]

◆ replace()

◆ consumeChars()

◆ consumeArgs()

◆ consumeArg()

◆ linearDistance()