parser.hpp #

Defines functions for parsing files or strings and the exceptions they use.

While parse throws an exception on failure, try_parse returns error information.

parse #

Parses the content of a given file and returns a toml::basic_value.

In case of failure, toml::syntax_error is thrown.

The type information of basic_value is provided by a template, and the TOML language version is specified by toml::spec.

parse(std::string filename, toml::spec) #

namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(std::string fname,
      spec s = spec::default_version());
}

Parses the content of the given filename.

If reading the file fails, toml::file_io_error is thrown.

If parsing fails, toml::syntax_error is thrown.

parse(const char (&)[N] filename, toml::spec) #

namespace toml
{
template<typename TC = type_config, std::size_t N>
basic_value<TC>
parse(const char (&fname)[N],
      spec s = spec::default_version());
}

Parses the content of the given filename from a string literal.

If reading the file fails, toml::file_io_error is thrown.

If parsing fails, toml::syntax_error is thrown.

parse(std::filesystem::path, toml::spec) #

namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(const std::filesystem::path& fpath,
      spec s = spec::default_version());
}

This is defined only if <filesystem> is available.

Parses the content of the file at the given file path.

If reading the file fails, toml::file_io_error is thrown.

If parsing fails, toml::syntax_error is thrown.

parse(std::istream&, std::string filename, toml::spec) #

namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(std::istream& is,
      std::string fname = "unknown file",
      spec s = spec::default_version());
}

Parses the content of the given std::istream&.

Open a stream in binary mode by passing std::ios::binary to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.

The filename information is taken as the third argument. If the filename is not provided, it defaults to "unknown file".

parse(FILE*, std::string filename, toml::spec) #

namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
parse(FILE* fp,
      std::string filename,
      spec s = spec::default_version());
}

Parses the content of the file pointed to by FILE*.

Open a stream in binary mode by passing "rb" to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.

If reading the file fails, file_io_error containing errno is thrown.

If parsing fails, syntax_error is thrown.

parse(std::vector<unsigned char>, std::string filename, toml::spec) #

namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(std::vector<unsigned char> content,
      std::string filename,
      spec s = spec::default_version());
}

Parses the byte sequence as a TOML file.

If parsing fails, toml::syntax_error is thrown.

parse_str #

parse_str(std::string, toml::spec) #

namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse_str(std::string content,
          spec s = spec::default_version(),
          cxx::source_location loc = cxx::source_location::current());
}

Parses a string as a TOML file.

In case of failure, toml::syntax_error is thrown.

The type information of basic_value is provided by a template, and the TOML language version is specified by toml::spec.

You generally don’t need to manually set the third argument, cxx::source_location. If std::source_location, std::experimental::source_location, or __builtin_FILE is available, the location information where parse_str was called will be stored.

try_parse #

Parses the contents of the given file and returns a toml::basic_value if successful, or a std::vector<toml::error_info> if it fails.

The type information of basic_value is specified by template, and the version of the TOML language is specified by toml::spec.

Unlike parse, try_parse does not throw exceptions defined in toml11 such as syntax_error. However, please note that exceptions thrown by the standard library will still propagate.

For instance, errors occurring internally within std::ifstream or memory exhaustion in std::vector will throw exceptions.

try_parse(std::string filename, toml::spec) #

namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(std::string fname,
          spec s = spec::default_version());
}

Takes a file name and parses its content.

If parsing fails, a result holding the error type std::vector<error_info> is returned.

If successful, a result holding a basic_value is returned.

try_parse(const char (&)[N] filename, toml::spec) #

namespace toml
{
template<typename TC = type_config, std::size_t N>
result<basic_value<TC>, std::vector<error_info>>
try_parse(const char (&fname)[N],
          spec s = spec::default_version());
}

Takes a string literal as a file name and parses its content.

If parsing fails, a result holding the error type std::vector<error_info> is returned.

If successful, a result holding a basic_value is returned.

try_parse(std::filesystem::path, toml::spec) #

namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(const std::filesystem::path& fpath,
          spec s = spec::default_version());
}

Takes a file path and parses its content.

If parsing fails, a result holding the error type std::vector<error_info> is returned.

If successful, a result holding a basic_value is returned.

try_parse(std::istream&, std::string filename, toml::spec) #

namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(std::istream& is,
          std::string fname = "unknown file",
          spec s = spec::default_version());
}

Takes a std::istream& and parses its content.

Open a stream in binary mode by passing std::ios::binary to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.

The file name information is taken as the second argument. If a file name is not provided, it defaults to "unknown file".

If parsing fails, a result holding the error type std::vector<error_info> is returned.

If successful, a result holding a basic_value is returned.

try_parse(FILE*, std::string filename, toml::spec) #

namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(FILE* fp,
          std::string filename,
          spec s = spec::default_version());
}

Takes a FILE* and parses its content.

Open a stream in binary mode by passing "rb" to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.

If parsing fails, a result holding the error type std::vector<error_info> is returned.

If successful, a result holding a basic_value is returned.

try_parse(std::vector<unsigned char>, std::string filename, toml::spec) #

namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(std::vector<unsigned char> content,
          std::string filename,
          spec s = spec::default_version());
}

Takes a byte array and parses its content as a TOML file.

If parsing fails, a result holding the error type std::vector<error_info> is returned.

If successful, a result holding a basic_value is returned.

try_parse_str #

try_parse_str(std::string, toml::spec) #

namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse_str(std::string content,
              spec s = spec::default_version(),
              cxx::source_location loc = cxx::source_location::current());
}

Parses a string as a TOML file, returning a toml::basic_value if successful, or a std::vector<toml::error_info> if it fails.

Unlike parse_str, it does not throw syntax_error, but instead returns error information as the failure type of the result.

If std::source_location, std::experimental::source_location, or __builtin_FILE is available, it will record the location information.

Typically, you do not need to manually set the third argument cxx::source_location. If any of std::source_location, std::experimental::source_location, or __builtin_FILE are available, the information of the location where parse_str was called will be saved as the location information.

Unlike parse, try_parse does not throw exceptions defined in toml11 such as syntax_error. However, please note that exceptions thrown by the standard library will still propagate.

For instance, errors occurring internally within std::ifstream or memory exhaustion in std::vector will throw exceptions.

syntax_error #

namespace toml
{
struct syntax_error final : public ::toml::exception
{
  public:
    syntax_error(std::string what_arg, std::vector<error_info> err);
    ~syntax_error() noexcept override = default;

    const char* what() const noexcept override;
    std::vector<error_info> const& errors() const noexcept
};
}

An exception thrown when a syntax error is detected in TOML.

It is thrown by parse but not by try_parse.

file_io_error #

namespace toml
{
struct file_io_error final : public ::toml::exception
{
  public:
    file_io_error(const std::string& msg, const std::string& fname);
    file_io_error(int errnum, const std::string& msg, const std::string& fname);
    ~file_io_error() noexcept override = default;

    const char* what() const noexcept override;

    bool has_errno() const noexcept;
    int  get_errno() const noexcept;
};
}

An exception thrown when reading the contents of a file fails.

When using FILE* to read a file, errno is set.

has_errno #

If std::ifstream fails, errno is not set.

In this case, has_errno returns false.

get_errno #

Particularly when passing a FILE*, retrieves the value of errno.

If has_errno is false, it returns 0.

Related #

• error_info.hpp
• result.hpp
• spec.hpp
• value.hpp