userver: utils::encoding::TskvParser Class Reference
Loading...
Searching...
No Matches
Public Types | Public Member Functions | List of all members
utils::encoding::TskvParser Class Referencefinal

#include <userver/utils/encoding/tskv_parser.hpp>

Detailed Description

A streaming parser for the TSKV variant that userver emits.

Supported syntax

  1. Records are separated by a single non-escaped \n character
  2. A record consists of entries separated by a single \t character
  3. The first entry SHOULD be verbatim tskv
  4. Entries MAY have values, separated by the first non-escaped =
  5. An entry MAY have no key-value split, in which case it all counts as key

Escaping

  1. \n, \t, \\ in keys or values SHOULD be escaped as "\\\n", "\\\t", "\\\\"</tt> sequences 2. <tt>=</tt> SHOULD be escaped as <tt>"\="</tt> in keys, MAY be escaped in values 3. <tt>\\r</tt> and <tt>\\0</tt> MAY be escaped as <tt>"\\r"</tt> and <tt>"\\0" sequences

Parsing process Initialize TskvParser with a caller-owned string that may contain a single or multiple TSKV records. For each record, first call SkipToRecordBegin. Then call ReadKey and ReadValue a bunch of times.

For a simpler way to read TSKV records, see utils::encoding::TskvReadRecord.

Definition at line 35 of file tskv_parser.hpp.

Public Types

enum class  RecordStatus {
  kReachedEnd ,
  kIncomplete
}
 

Public Member Functions

 TskvParser (std::string_view in) noexcept
 
const char * SkipToRecordBegin () noexcept
 Skips the current record or optional invalid junk until it finds the start of the a valid record.
 
RecordStatus SkipToRecordEnd () noexcept
 Skips to the end of the current record, which might not be the same as the start of the next valid record.
 
std::optional< RecordStatus > ReadKey (std::string &result)
 Parses the key, replacing result with it.
 
std::optional< RecordStatus > ReadValue (std::string &result)
 Parses the value, replacing result with it.
 
const char * GetStreamPosition () const noexcept
 

Member Enumeration Documentation

◆ RecordStatus

enum class utils::encoding::TskvParser::RecordStatus
strong

The status is returned once the record is complete. We ignore invalid escaping, not reporting it as an error, trying to push through. nullopt status means we should keep reading the current TSKV record.

Enumerator
kReachedEnd 

successfully read the whole record

kIncomplete 

the record ends abruptly, the service is probably still writing the record

Definition at line 40 of file tskv_parser.hpp.

Member Function Documentation

◆ GetStreamPosition()

const char * utils::encoding::TskvParser::GetStreamPosition ( ) const
noexcept
Returns
pointer to the data that will be read by the next operation

◆ ReadKey()

std::optional< RecordStatus > utils::encoding::TskvParser::ReadKey ( std::string & result)

Parses the key, replacing result with it.

Exceptions
std::bad_alloconly if std::string allocation throws
Note
RecordStatus::kReachedEnd is returned specifically on a trailing \t\n sequence

◆ ReadValue()

std::optional< RecordStatus > utils::encoding::TskvParser::ReadValue ( std::string & result)

Parses the value, replacing result with it.

Exceptions
std::bad_alloconly if std::string allocation throws

◆ SkipToRecordBegin()

const char * utils::encoding::TskvParser::SkipToRecordBegin ( )
noexcept

Skips the current record or optional invalid junk until it finds the start of the a valid record.

Returns
pointer to the start of the next record if there is one, nullptr otherwise
Note
tskv\n records are currently not supported

◆ SkipToRecordEnd()

RecordStatus utils::encoding::TskvParser::SkipToRecordEnd ( )
noexcept

Skips to the end of the current record, which might not be the same as the start of the next valid record.

Note
RecordStatus::kReachedEnd SHOULD not have been returned for the current record, otherwise the behavior is unspecified.
tskv\n records are currently not supported
The documentation for this class was generated from the following file: