A template class that parses text and throws meaningful error messages. More...

#include <jade.scanner.hpp>

Collaboration diagram for jade::basic_scanner< TChar >:

Public Types
typedef TChar	char_type
	The character type. More...

typedef std::char_traits< char_type >	char_traits_type
	The character traits type. More...

typedef std::basic_istream< char_type >	istream_type
	The input stream type. More...

typedef std::basic_ostream< char_type >	ostream_type
	The output stream type. More...

typedef std::basic_string< char_type >	string_type
	The string type. More...

typedef std::basic_istringstream< char_type >	istringstream_type
	The input stream type. More...

typedef std::basic_ostringstream< char_type >	ostringstream_type
	The output stream type. More...

Public Member Functions
	basic_scanner (istream_type &in)
	Initializes a new instance of the class to scan the specified stream. More...

	basic_scanner (const string_type &in)
	Initializes a new instance of the class to scan the specified string. More...

void	expect (const char_type ch)
	Skips whitespace and validates the next symbol in the stream matches the specified character. If the validation fails, this method throws an exception with a meaningful error message. More...

bool	is_end_of_data () const

void	read_digits (ostream_type &out)
	Reads a series of digits from the stream and copies them to the specified output stream. This method does not skip whitespace before or after reading the digits. More...

double	read_double ()
	Skips whitespace and then parses and returns a floating-point value from the specified stream. If there is an error parsing the value, the method throws an exception with a meaningful error message. More...

float	read_float ()
	Skips whitespace and then parses and returns a floating-point value from the specified stream. If there is an error parsing the value, the method throws an exception with a meaningful error message. More...

template<typename TValue >
TValue	read_real ()
	Skips whitespace and then parses and returns a floating-point value from the specified stream. If there is an error parsing the value, the method throws an exception with a meaningful error message. More...

string_type	read_token (char_type const *const delimeters=nullptr)
	Reads and returns a series of characters terminated by the end of the input stream or a specified delimeter. If no delimeters are unspecified, then the method uses whitespace as the delimeters. More...

void	skip_whitespace ()
	Skips whitespace from the input stream. If the input stream indicates the end of the stream, the method returns without an error. More...

bool	try_char (const char_type ch)
	Skips whitespace and then checks if the next character from the stream matches the specified character. If it does, the method advances the stream past the character and returns true; otherwise, the method returns false. More...

Detailed Description

template<typename TChar>
class jade::basic_scanner< TChar >

A template class that parses text and throws meaningful error messages.

Definition at line 18 of file jade.scanner.hpp.

Member Typedef Documentation

◆ char_traits_type

template<typename TChar >

typedef std::char_traits<char_type> jade::basic_scanner< TChar >::char_traits_type

The character traits type.

Definition at line 25 of file jade.scanner.hpp.

◆ char_type

template<typename TChar >

typedef TChar jade::basic_scanner< TChar >::char_type

The character type.

Definition at line 22 of file jade.scanner.hpp.

◆ istream_type

template<typename TChar >

typedef std::basic_istream<char_type> jade::basic_scanner< TChar >::istream_type

The input stream type.

Definition at line 28 of file jade.scanner.hpp.

◆ istringstream_type

template<typename TChar >

typedef std::basic_istringstream<char_type> jade::basic_scanner< TChar >::istringstream_type

The input stream type.

Definition at line 37 of file jade.scanner.hpp.

◆ ostream_type

template<typename TChar >

typedef std::basic_ostream<char_type> jade::basic_scanner< TChar >::ostream_type

The output stream type.

Definition at line 31 of file jade.scanner.hpp.

◆ ostringstream_type

template<typename TChar >

typedef std::basic_ostringstream<char_type> jade::basic_scanner< TChar >::ostringstream_type

The output stream type.

Definition at line 40 of file jade.scanner.hpp.

◆ string_type

template<typename TChar >

typedef std::basic_string<char_type> jade::basic_scanner< TChar >::string_type

The string type.

Definition at line 34 of file jade.scanner.hpp.

Constructor & Destructor Documentation

◆ basic_scanner() [1/2]

template<typename TChar >

jade::basic_scanner< TChar >::basic_scanner ( istream_type & in )

inlineexplicit

Initializes a new instance of the class to scan the specified stream.

Parameters

in	The input stream.

Definition at line 46 of file jade.scanner.hpp.

             : _ptr ()
             , _in  (in)
         {
         }

◆ basic_scanner() [2/2]

template<typename TChar >

jade::basic_scanner< TChar >::basic_scanner ( const string_type & in )

inlineexplicit

Initializes a new instance of the class to scan the specified string.

Parameters

in	The input string.

Definition at line 57 of file jade.scanner.hpp.

             : _ptr (new istringstream_type(in))
             , _in  (*_ptr)
         {
         }

Member Function Documentation

◆ expect()

template<typename TChar >

void jade::basic_scanner< TChar >::expect ( const char_type ch )

inline

Skips whitespace and validates the next symbol in the stream matches the specified character. If the validation fails, this method throws an exception with a meaningful error message.

Exceptions

jade::error Thrown if the stream provides an unexpected symbol.

Parameters

ch	The expected character.

Definition at line 72 of file jade.scanner.hpp.

         {
             //
             // Skip whitespace before validating the character.
             //
             skip_whitespace();
  
             //
             // Throw an excepiton if encountering the end of the stream.
             //
             const auto actual = _in.peek();
             if (actual < 0)
                 throw error()
                     << "expected symbol '" << char_type(ch) << "' "
                     << "but encountered end of stream";
  
             //
             // Validate the symbol matches the expected value.
             //
             if (actual == ch)
             {
                 _in.get();
                 return;
             }
  
             if (::isprint(ch))
                 throw error()
                     << "expected symbol '" << char_type(ch) << "' "
                     << "but encountered symbol '"
                     << char_type(actual) << "'";
  
             throw error()
                 << "expected symbol '" << char_type(ch) << "' "
                 << "but encountered ASCII code " << actual;
         }

Here is the call graph for this function:

◆ is_end_of_data()

template<typename TChar >

bool jade::basic_scanner< TChar >::is_end_of_data ( ) const

inline

Returns: True if all data has been read from the scanner.

Definition at line 112 of file jade.scanner.hpp.

         {
             return _in.peek() < 0;
         }

◆ read_digits()

template<typename TChar >

void jade::basic_scanner< TChar >::read_digits ( ostream_type & out )

inline

Reads a series of digits from the stream and copies them to the specified output stream. This method does not skip whitespace before or after reading the digits.

Parameters

out	The output stream.

Definition at line 122 of file jade.scanner.hpp.

         {
             while (::isdigit(_in.peek()))
                 out << char_type(_in.get());
         }

Here is the caller graph for this function:

◆ read_double()

template<typename TChar >

double jade::basic_scanner< TChar >::read_double ( )

inline

Skips whitespace and then parses and returns a floating-point value from the specified stream. If there is an error parsing the value, the method throws an exception with a meaningful error message.

Returns: A floating-point value.

Exceptions

jade::error Thrown if there is an error parsing the length.

Definition at line 139 of file jade.scanner.hpp.

         {
             return read_real<double>();
         }

◆ read_float()

template<typename TChar >

float jade::basic_scanner< TChar >::read_float ( )

inline

Skips whitespace and then parses and returns a floating-point value from the specified stream. If there is an error parsing the value, the method throws an exception with a meaningful error message.

Returns: A floating-point value.

Exceptions

jade::error Thrown if there is an error parsing the length.

Definition at line 154 of file jade.scanner.hpp.

         {
             return read_real<float>();
         }

◆ read_real()

template<typename TChar >

template<typename TValue >

TValue jade::basic_scanner< TChar >::read_real ( )

inline

Skips whitespace and then parses and returns a floating-point value from the specified stream. If there is an error parsing the value, the method throws an exception with a meaningful error message.

Returns: A floating-point value.

Exceptions

jade::error Thrown if there is an error parsing the length.

Definition at line 170 of file jade.scanner.hpp.

         {
             static const auto hyphen = char_type('-');
             static const auto period = char_type('.');
  
             //
             // Initially skip whitespace.
             //
             skip_whitespace();
  
             ostringstream_type out;
  
             //
             // Check for negative values.
             //
             if (try_char(hyphen))
                 out << hyphen;
  
             //
             // Read values before the decimal place.
             //
             read_digits(out);
  
             //
             // Check for a decimal, possibly reading additional digits.
             //
             if (try_char(period))
             {
                 out << period;
                 read_digits(out);
             }
  
             //
             // If no symbols exist in the output buffer, this is invalid.
             //
             const auto length_str = out.str();
             if (length_str.empty())
                 throw error(
                     "expected a floating-point value but "
                     "did not encounter any digits");
  
             //
             // Parse and return the digits as a floating-point value, throwing
             // an exception in the case of an error.
             //
             istringstream_type length_in (length_str);
             TValue length;
             if (length_in >> length)
                 return length;
             throw error()
                 << "expected a length but encountered '"
                 << length_str << "'";
         }

Here is the call graph for this function:

◆ read_token()

template<typename TChar >

string_type jade::basic_scanner< TChar >::read_token ( char_type const *const delimeters = nullptr )

inline

Reads and returns a series of characters terminated by the end of the input stream or a specified delimeter. If no delimeters are unspecified, then the method uses whitespace as the delimeters.

Parameters

delimeters The delimeters, or nullptr.

Returns: The token.

Definition at line 232 of file jade.scanner.hpp.

         {
             static const char_type fallback[] =
             {
                 char_type(' '),
                 char_type('\n'),
                 char_type('\t'),
                 char_type('\0')
             };
  
             //
             // Use whitespace as the delimeters unless specified otherwise.
             //
             const auto delims = delimeters == nullptr ? fallback : delimeters;
             const auto length = char_traits_type::length(delims);
  
             ostringstream_type out;
  
             for (;;)
             {
                 auto ch = _in.peek();
  
                 if (ch < 0 || nullptr != char_traits_type::find(
                     delims, length, char_type(ch)))
                     return out.str();
  
                 out << char_type(_in.get());
             }
         }

◆ skip_whitespace()

template<typename TChar >

void jade::basic_scanner< TChar >::skip_whitespace ( )

inline

Skips whitespace from the input stream. If the input stream indicates the end of the stream, the method returns without an error.

Definition at line 267 of file jade.scanner.hpp.

         {
             while (::isspace(_in.peek()))
                 _in.get();
         }

Here is the caller graph for this function:

◆ try_char()

template<typename TChar >

bool jade::basic_scanner< TChar >::try_char ( const char_type ch )

inline

Skips whitespace and then checks if the next character from the stream matches the specified character. If it does, the method advances the stream past the character and returns true; otherwise, the method returns false.

Returns: True if encountering the character; otherwise, false.

Parameters

ch	The character to test.

Definition at line 281 of file jade.scanner.hpp.

         {
             //
             // Skip whitespace before testing the next symbol.
             //
             skip_whitespace();
  
             //
             // Return false if the symbol does not match or if there are no more
             // symbols available in the input stream.
             //
             if (ch != _in.peek())
                 return false;
  
             //
             // Advance past the character and return true to indicate a match.
             //
             _in.get();
             return true;
         }

Here is the call graph for this function:

Here is the caller graph for this function:

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

jade.scanner.hpp

Public Types

Public Member Functions

Detailed Description

template<typename TChar> class jade::basic_scanner< TChar >

Member Typedef Documentation

◆ char_traits_type

◆ char_type

◆ istream_type

◆ istringstream_type

◆ ostream_type

◆ ostringstream_type

◆ string_type

Constructor & Destructor Documentation

◆ basic_scanner() [1/2]

◆ basic_scanner() [2/2]

Member Function Documentation

◆ expect()

◆ is_end_of_data()

◆ read_digits()

◆ read_double()

◆ read_float()

◆ read_real()

◆ read_token()

◆ skip_whitespace()

◆ try_char()

template<typename TChar>
class jade::basic_scanner< TChar >