Sawyer::CommandLine::Cursor Class Reference

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 257 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/2]

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

explicit

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.

Cursor() [2/2]

Sawyer::CommandLine::Cursor::Cursor

(

const std::string &

string

)

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.

Member Function Documentation

location() [1/2]

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

(

)

const

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).

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

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.

atArgEnd()

bool Sawyer::CommandLine::Cursor::atArgEnd

(

)

const

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.

atEnd() [1/2]

bool Sawyer::CommandLine::Cursor::atEnd

(

)

const

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.

atEnd() [2/2]

bool Sawyer::CommandLine::Cursor::atEnd

(

const Location &

location

)

const

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.

arg() [1/2]

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

(

)

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.

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

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.

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

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

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

)

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.

consumeArg()

void Sawyer::CommandLine::Cursor::consumeArg

(

)

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.

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()

but faster.

---

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

• Sawyer/CommandLine.h