A read-only position in a character stream, with line and column tracking and a save/restore mechanism. More...

#include <Cursor.hh>

Public Types
using	stream_type = std::istream
	The underlying stream type (`std::istream`).

Public Member Functions
	Cursor (std::string sourceName="")
	Construct over a file, opened internally for reading. More...

	Cursor (std::string sourceName, std::shared_ptr< stream_type > externalStream)
	Construct over a caller-supplied stream. More...

	Cursor (Cursor const &object)
	Copy constructor. Copies the position; shares the stream. More...

	Cursor (Cursor &&object)=delete
	Move construction is deleted.

virtual	~Cursor ()
	Destructor. Does not close a caller-supplied stream; the internally-opened `ifstream` is closed when its last owner drops. More...

Cursor &	operator= (Cursor const &object)
	Copy assignment. Copies the position; shares the stream. More...

Cursor &	operator= (Cursor &&object)=delete
	Move assignment is deleted.

bool	operator== (Cursor const &object) const
	Equality by location: same filename pointer, line and column. The stream contents are not compared. More...

void	rewind ()
	Seek back to the start of the stream and reset the line and column counters to zero. More...

void	store () noexcept
	Record the current stream offset as the saved position. If the stream is at or past end-of-input, a flag is set so a later `restore()` seeks to the end. More...

void	restore ()
	Seek back to the position recorded by the last `store()`. More...

void	safeRestore () noexcept
	Clear stream error flags, restore to the saved position, and put the exception mask back. Never throws. More...

bool	isValid () const noexcept
	Whether the stream exists and is readable (not EOF, not bad). More...

stream_type::char_type	get ()
	Consume and return the next character; advance line/column. More...

stream_type::char_type	safeGet () noexcept
	Non-throwing `get()`: returns ‘’\032'` at end-of-input instead of throwing. Line/column still advance. More...

stream_type::char_type	peek ()
	Return the next character without consuming it. More...

stream_type::char_type	safePeek () noexcept
	Non-throwing `peek()`: returns ‘’\032'` at end-of-input instead of throwing, and leaves the stream usable. More...

std::shared_ptr< std::string >	getLocation () const noexcept
	Shared pointer to the source-name string. More...

std::string const &	getFilename () const noexcept
	The source name. More...

unsigned long int	getLineNumber () const noexcept
	The current line number. More...

unsigned long int	getColumnNumber () const noexcept
	The current column number. More...

Detailed Description

A read-only position in a character stream, with line and column tracking and a save/restore mechanism.

Cursor wraps a std::istream (an internally-opened std::ifstream when constructed from a filename, or a caller-supplied stream) and adds:

Line and column counters advanced by every get() / safeGet(). Position starts at line 0, column 0 ("before any character"); the first read moves it to line 1, column 1.
A single saved position — store() records tellg(), restore() seeks back to it. Used by Parser for backtracking.
Throwing and non-throwing accessors. get() / peek() throw std::ios_base::failure at end-of-input (the exception mask is set in the constructor); safeGet() / safePeek() return the sentinel ‘’\032'` (ASCII SUB) instead.

The stream is shared (std::shared_ptr); copying a Cursor copies the position but shares the underlying stream. Move construction and move assignment are deleted.

See also: https://cparse.fedem.eu/reference/cursor — reference manual page.; Parser

Constructor & Destructor Documentation

◆ Cursor() [1/3]

fedem::parser::Cursor::Cursor ( std::string sourceName = "" )

explicit

Construct over a file, opened internally for reading.

Parameters

sourceName Path to open. An empty string yields a cursor whose stream never becomes valid (isValid() stays false).

Note: skipws is cleared so whitespace is visible to the grammar. The exception mask is set to failbit | eofbit | badbit.

See also: https://cparse.fedem.eu/reference/cursor-ctor

References store().

Here is the call graph for this function:

◆ Cursor() [2/3]

fedem::parser::Cursor::Cursor	(	std::string	sourceName,
		std::shared_ptr< stream_type >	externalStream
	)

Construct over a caller-supplied stream.

Parameters

sourceName	Name used for diagnostics and `getFilename()`; need not be a real path (e.g. `"<memory>"`).
externalStream	Stream to read from. The cursor shares ownership and sets the exception mask and `skipws` on it.

See also: https://cparse.fedem.eu/reference/cursor-ctor

References store().

Here is the call graph for this function:

◆ Cursor() [3/3]

fedem::parser::Cursor::Cursor ( Cursor const & object )

Copy constructor. Copies the position; shares the stream.

Parameters

object Cursor to copy from.

◆ ~Cursor()

fedem::parser::Cursor::~Cursor ( )

virtual

Destructor. Does not close a caller-supplied stream; the internally-opened ifstream is closed when its last owner drops.

See also: https://cparse.fedem.eu/reference/cursor-dtor

Member Function Documentation

◆ operator=()

Cursor & fedem::parser::Cursor::operator= ( Cursor const & object )

Copy assignment. Copies the position; shares the stream.

Parameters

object Cursor to copy from.

Returns: *this.

See also: https://cparse.fedem.eu/reference/cursor-operator-assign

◆ operator==()

bool fedem::parser::Cursor::operator== ( Cursor const & object ) const

Equality by location: same filename pointer, line and column. The stream contents are not compared.

Parameters

object Cursor to compare against.

Returns: true if both cursors are at the same location.

See also: https://cparse.fedem.eu/reference/cursor-operator-eq

References getColumnNumber(), and getLocation().

Here is the call graph for this function:

◆ rewind()

void fedem::parser::Cursor::rewind ( )

Seek back to the start of the stream and reset the line and column counters to zero.

See also: https://cparse.fedem.eu/reference/cursor-rewind

References store().

Here is the call graph for this function:

◆ store()

void fedem::parser::Cursor::store ( )

noexcept

Record the current stream offset as the saved position. If the stream is at or past end-of-input, a flag is set so a later restore() seeks to the end.

See also: https://cparse.fedem.eu/reference/cursor-store

Referenced by Cursor(), rewind(), and fedem::parser::Parser::storeCursor().

Here is the caller graph for this function:

◆ restore()

void fedem::parser::Cursor::restore ( )

Seek back to the position recorded by the last store().

Note: May throw if the stream is in a hard-failed state; use safeRestore() to recover from that.

See also: https://cparse.fedem.eu/reference/cursor-restore

References get().

Referenced by fedem::parser::Parser::restoreCursor(), and safeRestore().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ safeRestore()

void fedem::parser::Cursor::safeRestore ( )

noexcept

Clear stream error flags, restore to the saved position, and put the exception mask back. Never throws.

See also: https://cparse.fedem.eu/reference/cursor-safe-restore

References restore().

Here is the call graph for this function:

◆ isValid()

bool fedem::parser::Cursor::isValid ( ) const

noexcept

Whether the stream exists and is readable (not EOF, not bad).

Returns: true while more input can be read.

See also: https://cparse.fedem.eu/reference/cursor-is-valid

◆ get()

Cursor::stream_type::char_type fedem::parser::Cursor::get ( )

Consume and return the next character; advance line/column.

Returns: The character consumed.

Exceptions

std::runtime_error	if the internal stream pointer is null.
std::ios_base::failure	at end-of-input or on stream error — this is the path `Parser::parse()` uses to detect EOF.

See also: https://cparse.fedem.eu/reference/cursor-get

Referenced by restore().

Here is the caller graph for this function:

◆ safeGet()

Cursor::stream_type::char_type fedem::parser::Cursor::safeGet ( )

noexcept

Non-throwing get(): returns ‘’\032'` at end-of-input instead of throwing. Line/column still advance.

Returns: The character consumed, or ‘’\032'` at end-of-input.

See also: https://cparse.fedem.eu/reference/cursor-safe-get

◆ peek()

Cursor::stream_type::char_type fedem::parser::Cursor::peek ( )

Return the next character without consuming it.

Returns: The next character.

Exceptions

std::runtime_error	if the internal stream pointer is null.
std::ios_base::failure	at end-of-input or on stream error.

See also: https://cparse.fedem.eu/reference/cursor-peek

◆ safePeek()

Cursor::stream_type::char_type fedem::parser::Cursor::safePeek ( )

noexcept

Non-throwing peek(): returns ‘’\032'` at end-of-input instead of throwing, and leaves the stream usable.

Returns: The next character, or ‘’\032'` at end-of-input.

See also: https://cparse.fedem.eu/reference/cursor-safe-peek

◆ getLocation()

std::shared_ptr< std::string > fedem::parser::Cursor::getLocation ( ) const

inlinenoexcept

Shared pointer to the source-name string.

Returns: The shared std::string holding the source name; may be null.

See also: https://cparse.fedem.eu/reference/cursor-get-location

Referenced by operator==().

Here is the caller graph for this function:

◆ getFilename()

std::string const & fedem::parser::Cursor::getFilename ( ) const

inlinenoexcept

The source name.

Returns: The source name, or an empty string if none was set.

See also: https://cparse.fedem.eu/reference/cursor-get-filename

◆ getLineNumber()

unsigned long int fedem::parser::Cursor::getLineNumber ( ) const

inlinenoexcept

The current line number.

Returns: The 1-based line number once reading has started; 0 before.

See also: https://cparse.fedem.eu/reference/cursor-get-line-number

◆ getColumnNumber()

unsigned long int fedem::parser::Cursor::getColumnNumber ( ) const

inlinenoexcept

The current column number.

Returns: The 1-based column number once reading has started; 0 before.

See also: https://cparse.fedem.eu/reference/cursor-get-column-number

Referenced by operator==().

Here is the caller graph for this function:

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

Cursor.hh
Cursor.cpp

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Cursor() [1/3]

◆ Cursor() [2/3]

◆ Cursor() [3/3]

◆ ~Cursor()

Member Function Documentation

◆ operator=()

◆ operator==()

◆ rewind()

◆ store()

◆ restore()

◆ safeRestore()

◆ isValid()

◆ get()

◆ safeGet()

◆ peek()

◆ safePeek()

◆ getLocation()

◆ getFilename()

◆ getLineNumber()

◆ getColumnNumber()