/src/tomlplusplus/include/toml++/impl/parser.hpp

Source
//# This file is a part of toml++ and is subject to the the terms of the MIT license.
//# Copyright (c) Mark Gillard <mark.gillard@outlook.com.au>
//# See https://github.com/marzer/tomlplusplus/blob/master/LICENSE for the full license text.
// SPDX-License-Identifier: MIT
#pragma once

#include "preprocessor.hpp"
#if TOML_ENABLE_PARSER

#include "table.hpp"
#include "parse_result.hpp"
#include "header_start.hpp"

TOML_NAMESPACE_START
{
  TOML_ABI_NAMESPACE_BOOL(TOML_EXCEPTIONS, ex, noex);

  /// \brief  Parses a TOML document from a string view.
  ///
  /// \detail \cpp
  /// auto tbl = toml::parse("a = 3"sv);
  /// std::cout << tbl["a"] << "\n";
  /// \ecpp
  ///
  /// \out
  /// 3
  /// \eout
  ///
  /// \param  doc       The TOML document to parse. Must be valid UTF-8.
  /// \param  source_path   The path used to initialize each node's `source().path`.
  ///             If you don't have a path (or you have no intention of using paths in diagnostics)
  ///             then this parameter can safely be left blank.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse(std::string_view doc, std::string_view source_path = {});

  /// \brief  Parses a TOML document from a string view.
  ///
  /// \detail \cpp
  /// auto tbl = toml::parse("a = 3"sv, "foo.toml");
  /// std::cout << tbl["a"] << "\n";
  /// \ecpp
  ///
  /// \out
  /// 3
  /// \eout
  ///
  /// \param  doc       The TOML document to parse. Must be valid UTF-8.
  /// \param  source_path   The path used to initialize each node's `source().path`.
  ///             If you don't have a path (or you have no intention of using paths in diagnostics)
  ///             then this parameter can safely be left blank.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse(std::string_view doc, std::string && source_path);

  /// \brief  Parses a TOML document from a file.
  ///
  /// \detail \cpp
  /// toml::parse_result get_foo_toml()
  /// {
  ///   return toml::parse_file("foo.toml");
  /// }
  /// \ecpp
  ///
  /// \param  file_path   The TOML document to parse. Must be valid UTF-8.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse_file(std::string_view file_path);

#if TOML_HAS_CHAR8

  /// \brief  Parses a TOML document from a char8_t string view.
  ///
  /// \detail \cpp
  /// auto tbl = toml::parse(u8"a = 3"sv);
  /// std::cout << tbl["a"] << "\n";
  /// \ecpp
  ///
  /// \out
  /// 3
  /// \eout
  ///
  /// \param  doc       The TOML document to parse. Must be valid UTF-8.
  /// \param  source_path   The path used to initialize each node's `source().path`.
  ///             If you don't have a path (or you have no intention of using paths in diagnostics)
  ///             then this parameter can safely be left blank.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse(std::u8string_view doc, std::string_view source_path = {});

  /// \brief  Parses a TOML document from a char8_t string view.
  ///
  /// \detail \cpp
  /// auto tbl = toml::parse(u8"a = 3"sv, "foo.toml");
  /// std::cout << tbl["a"] << "\n";
  /// \ecpp
  ///
  /// \out
  /// 3
  /// \eout
  ///
  /// \param  doc       The TOML document to parse. Must be valid UTF-8.
  /// \param  source_path   The path used to initialize each node's `source().path`.
  ///             If you don't have a path (or you have no intention of using paths in diagnostics)
  ///             then this parameter can safely be left blank.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse(std::u8string_view doc, std::string && source_path);

  /// \brief  Parses a TOML document from a file.
  ///
  /// \detail \cpp
  /// toml::parse_result get_foo_toml()
  /// {
  ///   return toml::parse_file(u8"foo.toml");
  /// }
  /// \ecpp
  ///
  /// \param  file_path   The TOML document to parse. Must be valid UTF-8.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse_file(std::u8string_view file_path);

#endif // TOML_HAS_CHAR8

#if TOML_ENABLE_WINDOWS_COMPAT

  /// \brief  Parses a TOML document from a string view.
  ///
  /// \availability This overload is only available when #TOML_ENABLE_WINDOWS_COMPAT is enabled.
  ///
  /// \detail \cpp
  /// auto tbl = toml::parse("a = 3"sv, L"foo.toml");
  /// std::cout << tbl["a"] << "\n";
  /// \ecpp
  ///
  /// \out
  /// 3
  /// \eout
  ///
  /// \param  doc       The TOML document to parse. Must be valid UTF-8.
  /// \param  source_path   The path used to initialize each node's `source().path`.
  ///             If you don't have a path (or you have no intention of using paths in diagnostics)
  ///             then this parameter can safely be left blank.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse(std::string_view doc, std::wstring_view source_path);

  /// \brief  Parses a TOML document from a stream.
  ///
  /// \availability This overload is only available when #TOML_ENABLE_WINDOWS_COMPAT is enabled.
  ///
  /// \detail \cpp
  /// std::stringstream ss;
  /// ss << "a = 3"sv;
  ///
  /// auto tbl = toml::parse(ss);
  /// std::cout << tbl["a"] << "\n";
  /// \ecpp
  ///
  /// \out
  /// 3
  /// \eout
  ///
  /// \param  doc       The TOML document to parse. Must be valid UTF-8.
  /// \param  source_path   The path used to initialize each node's `source().path`.
  ///             If you don't have a path (or you have no intention of using paths in diagnostics)
  ///             then this parameter can safely be left blank.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse(std::istream & doc, std::wstring_view source_path);

  /// \brief  Parses a TOML document from a file.
  ///
  /// \availability This overload is only available when #TOML_ENABLE_WINDOWS_COMPAT is enabled.
  ///
  /// \detail \cpp
  /// toml::parse_result get_foo_toml()
  /// {
  ///   return toml::parse_file(L"foo.toml");
  /// }
  /// \ecpp
  ///
  /// \param  file_path   The TOML document to parse. Must be valid UTF-8.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse_file(std::wstring_view file_path);

#endif // TOML_ENABLE_WINDOWS_COMPAT

#if TOML_HAS_CHAR8 && TOML_ENABLE_WINDOWS_COMPAT

  /// \brief  Parses a TOML document from a char8_t string view.
  ///
  /// \availability This overload is only available when #TOML_ENABLE_WINDOWS_COMPAT is enabled.
  ///
  /// \detail \cpp
  /// auto tbl = toml::parse(u8"a = 3"sv, L"foo.toml");
  /// std::cout << tbl["a"] << "\n";
  /// \ecpp
  ///
  /// \out
  /// 3
  /// \eout
  ///
  /// \param  doc       The TOML document to parse. Must be valid UTF-8.
  /// \param  source_path   The path used to initialize each node's `source().path`.
  ///             If you don't have a path (or you have no intention of using paths in diagnostics)
  ///             then this parameter can safely be left blank.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse(std::u8string_view doc, std::wstring_view source_path);

#endif // TOML_HAS_CHAR8 && TOML_ENABLE_WINDOWS_COMPAT

  /// \brief  Parses a TOML document from a stream.
  ///
  /// \detail \cpp
  /// std::stringstream ss;
  /// ss << "a = 3"sv;
  ///
  /// auto tbl = toml::parse(ss);
  /// std::cout << tbl["a"] << "\n";
  /// \ecpp
  ///
  /// \out
  /// 3
  /// \eout
  ///
  /// \param  doc       The TOML document to parse. Must be valid UTF-8.
  /// \param  source_path   The path used to initialize each node's `source().path`.
  ///             If you don't have a path (or you have no intention of using paths in diagnostics)
  ///             then this parameter can safely be left blank.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse(std::istream & doc, std::string_view source_path = {});

  /// \brief  Parses a TOML document from a stream.
  ///
  /// \detail \cpp
  /// std::stringstream ss;
  /// ss << "a = 3"sv;
  ///
  /// auto tbl = toml::parse(ss, "foo.toml");
  /// std::cout << tbl["a"] << "\n";
  /// \ecpp
  ///
  /// \out
  /// 3
  /// \eout
  ///
  /// \param  doc       The TOML document to parse. Must be valid UTF-8.
  /// \param  source_path   The path used to initialize each node's `source().path`.
  ///             If you don't have a path (or you have no intention of using paths in diagnostics)
  ///             then this parameter can safely be left blank.
  ///
  /// \returns  \conditional_return{With exceptions}
  ///       A toml::table.
  ///       \conditional_return{Without exceptions}
  ///       A toml::parse_result.
  TOML_NODISCARD
  TOML_EXPORTED_FREE_FUNCTION
  parse_result TOML_CALLCONV parse(std::istream & doc, std::string && source_path);

  TOML_ABI_NAMESPACE_END; // TOML_EXCEPTIONS

  inline namespace literals
  {
    TOML_ABI_NAMESPACE_BOOL(TOML_EXCEPTIONS, lit_ex, lit_noex);

    /// \brief  Parses TOML data from a string literal.
    ///
    /// \detail \cpp
    /// using namespace toml::literals;
    ///
    /// auto tbl = "a = 3"_toml;
    /// std::cout << tbl["a"] << "\n";
    /// \ecpp
    ///
    /// \out
    /// 3
    /// \eout
    ///
    /// \param  str The string data. Must be valid UTF-8.
    /// \param  len The string length.
    ///
    /// \returns  \conditional_return{With exceptions}
    ///       A toml::table.
    ///       \conditional_return{Without exceptions}
    ///       A toml::parse_result.
    TOML_NODISCARD
    TOML_ALWAYS_INLINE
    parse_result operator""_toml(const char* str, size_t len)
    {
      return parse(std::string_view{ str, len });
    }

#if TOML_HAS_CHAR8

    /// \brief  Parses TOML data from a UTF-8 string literal.
    ///
    /// \detail \cpp
    /// using namespace toml::literals;
    ///
    /// auto tbl = u8"a = 3"_toml;
    /// std::cout << tbl["a"] << "\n";
    /// \ecpp
    ///
    /// \out
    /// 3
    /// \eout
    ///
    /// \param  str The string data. Must be valid UTF-8.
    /// \param  len The string length.
    ///
    /// \returns  \conditional_return{With exceptions}
    ///       A toml::table.
    ///       \conditional_return{Without exceptions}
    ///       A toml::parse_result.
    TOML_NODISCARD
    TOML_ALWAYS_INLINE
    parse_result operator""_toml(const char8_t* str, size_t len)
    {
      return parse(std::u8string_view{ str, len });
    }

#endif // TOML_HAS_CHAR8

    TOML_ABI_NAMESPACE_END; // TOML_EXCEPTIONS
  }
}
TOML_NAMESPACE_END;

#include "header_end.hpp"
#endif // TOML_ENABLE_PARSER

Coverage Report

Created: 2025-11-11 07:00

Line	Count	Source
1		//# This file is a part of toml++ and is subject to the the terms of the MIT license.
2		//# Copyright (c) Mark Gillard <mark.gillard@outlook.com.au>
3		//# See https://github.com/marzer/tomlplusplus/blob/master/LICENSE for the full license text.
4		// SPDX-License-Identifier: MIT
5		#pragma once
6
7		#include "preprocessor.hpp"
8		#if TOML_ENABLE_PARSER
9
10		#include "table.hpp"
11		#include "parse_result.hpp"
12		#include "header_start.hpp"
13
14		TOML_NAMESPACE_START
15		{
16		TOML_ABI_NAMESPACE_BOOL(TOML_EXCEPTIONS, ex, noex);
17
18		/// \brief Parses a TOML document from a string view.
19		///
20		/// \detail \cpp
21		/// auto tbl = toml::parse("a = 3"sv);
22		/// std::cout << tbl["a"] << "\n";
23		/// \ecpp
24		///
25		/// \out
26		/// 3
27		/// \eout
28		///
29		/// \param doc The TOML document to parse. Must be valid UTF-8.
30		/// \param source_path The path used to initialize each node's `source().path`.
31		/// If you don't have a path (or you have no intention of using paths in diagnostics)
32		/// then this parameter can safely be left blank.
33		///
34		/// \returns \conditional_return{With exceptions}
35		/// A toml::table.
36		/// \conditional_return{Without exceptions}
37		/// A toml::parse_result.
38		TOML_NODISCARD
39		TOML_EXPORTED_FREE_FUNCTION
40		parse_result TOML_CALLCONV parse(std::string_view doc, std::string_view source_path = {});
41
42		/// \brief Parses a TOML document from a string view.
43		///
44		/// \detail \cpp
45		/// auto tbl = toml::parse("a = 3"sv, "foo.toml");
46		/// std::cout << tbl["a"] << "\n";
47		/// \ecpp
48		///
49		/// \out
50		/// 3
51		/// \eout
52		///
53		/// \param doc The TOML document to parse. Must be valid UTF-8.
54		/// \param source_path The path used to initialize each node's `source().path`.
55		/// If you don't have a path (or you have no intention of using paths in diagnostics)
56		/// then this parameter can safely be left blank.
57		///
58		/// \returns \conditional_return{With exceptions}
59		/// A toml::table.
60		/// \conditional_return{Without exceptions}
61		/// A toml::parse_result.
62		TOML_NODISCARD
63		TOML_EXPORTED_FREE_FUNCTION
64		parse_result TOML_CALLCONV parse(std::string_view doc, std::string && source_path);
65
66		/// \brief Parses a TOML document from a file.
67		///
68		/// \detail \cpp
69		/// toml::parse_result get_foo_toml()
70		/// {
71		/// return toml::parse_file("foo.toml");
72		/// }
73		/// \ecpp
74		///
75		/// \param file_path The TOML document to parse. Must be valid UTF-8.
76		///
77		/// \returns \conditional_return{With exceptions}
78		/// A toml::table.
79		/// \conditional_return{Without exceptions}
80		/// A toml::parse_result.
81		TOML_NODISCARD
82		TOML_EXPORTED_FREE_FUNCTION
83		parse_result TOML_CALLCONV parse_file(std::string_view file_path);
84
85		#if TOML_HAS_CHAR8
86
87		/// \brief Parses a TOML document from a char8_t string view.
88		///
89		/// \detail \cpp
90		/// auto tbl = toml::parse(u8"a = 3"sv);
91		/// std::cout << tbl["a"] << "\n";
92		/// \ecpp
93		///
94		/// \out
95		/// 3
96		/// \eout
97		///
98		/// \param doc The TOML document to parse. Must be valid UTF-8.
99		/// \param source_path The path used to initialize each node's `source().path`.
100		/// If you don't have a path (or you have no intention of using paths in diagnostics)
101		/// then this parameter can safely be left blank.
102		///
103		/// \returns \conditional_return{With exceptions}
104		/// A toml::table.
105		/// \conditional_return{Without exceptions}
106		/// A toml::parse_result.
107		TOML_NODISCARD
108		TOML_EXPORTED_FREE_FUNCTION
109		parse_result TOML_CALLCONV parse(std::u8string_view doc, std::string_view source_path = {});
110
111		/// \brief Parses a TOML document from a char8_t string view.
112		///
113		/// \detail \cpp
114		/// auto tbl = toml::parse(u8"a = 3"sv, "foo.toml");
115		/// std::cout << tbl["a"] << "\n";
116		/// \ecpp
117		///
118		/// \out
119		/// 3
120		/// \eout
121		///
122		/// \param doc The TOML document to parse. Must be valid UTF-8.
123		/// \param source_path The path used to initialize each node's `source().path`.
124		/// If you don't have a path (or you have no intention of using paths in diagnostics)
125		/// then this parameter can safely be left blank.
126		///
127		/// \returns \conditional_return{With exceptions}
128		/// A toml::table.
129		/// \conditional_return{Without exceptions}
130		/// A toml::parse_result.
131		TOML_NODISCARD
132		TOML_EXPORTED_FREE_FUNCTION
133		parse_result TOML_CALLCONV parse(std::u8string_view doc, std::string && source_path);
134
135		/// \brief Parses a TOML document from a file.
136		///
137		/// \detail \cpp
138		/// toml::parse_result get_foo_toml()
139		/// {
140		/// return toml::parse_file(u8"foo.toml");
141		/// }
142		/// \ecpp
143		///
144		/// \param file_path The TOML document to parse. Must be valid UTF-8.
145		///
146		/// \returns \conditional_return{With exceptions}
147		/// A toml::table.
148		/// \conditional_return{Without exceptions}
149		/// A toml::parse_result.
150		TOML_NODISCARD
151		TOML_EXPORTED_FREE_FUNCTION
152		parse_result TOML_CALLCONV parse_file(std::u8string_view file_path);
153
154		#endif // TOML_HAS_CHAR8
155
156		#if TOML_ENABLE_WINDOWS_COMPAT
157
158		/// \brief Parses a TOML document from a string view.
159		///
160		/// \availability This overload is only available when #TOML_ENABLE_WINDOWS_COMPAT is enabled.
161		///
162		/// \detail \cpp
163		/// auto tbl = toml::parse("a = 3"sv, L"foo.toml");
164		/// std::cout << tbl["a"] << "\n";
165		/// \ecpp
166		///
167		/// \out
168		/// 3
169		/// \eout
170		///
171		/// \param doc The TOML document to parse. Must be valid UTF-8.
172		/// \param source_path The path used to initialize each node's `source().path`.
173		/// If you don't have a path (or you have no intention of using paths in diagnostics)
174		/// then this parameter can safely be left blank.
175		///
176		/// \returns \conditional_return{With exceptions}
177		/// A toml::table.
178		/// \conditional_return{Without exceptions}
179		/// A toml::parse_result.
180		TOML_NODISCARD
181		TOML_EXPORTED_FREE_FUNCTION
182		parse_result TOML_CALLCONV parse(std::string_view doc, std::wstring_view source_path);
183
184		/// \brief Parses a TOML document from a stream.
185		///
186		/// \availability This overload is only available when #TOML_ENABLE_WINDOWS_COMPAT is enabled.
187		///
188		/// \detail \cpp
189		/// std::stringstream ss;
190		/// ss << "a = 3"sv;
191		///
192		/// auto tbl = toml::parse(ss);
193		/// std::cout << tbl["a"] << "\n";
194		/// \ecpp
195		///
196		/// \out
197		/// 3
198		/// \eout
199		///
200		/// \param doc The TOML document to parse. Must be valid UTF-8.
201		/// \param source_path The path used to initialize each node's `source().path`.
202		/// If you don't have a path (or you have no intention of using paths in diagnostics)
203		/// then this parameter can safely be left blank.
204		///
205		/// \returns \conditional_return{With exceptions}
206		/// A toml::table.
207		/// \conditional_return{Without exceptions}
208		/// A toml::parse_result.
209		TOML_NODISCARD
210		TOML_EXPORTED_FREE_FUNCTION
211		parse_result TOML_CALLCONV parse(std::istream & doc, std::wstring_view source_path);
212
213		/// \brief Parses a TOML document from a file.
214		///
215		/// \availability This overload is only available when #TOML_ENABLE_WINDOWS_COMPAT is enabled.
216		///
217		/// \detail \cpp
218		/// toml::parse_result get_foo_toml()
219		/// {
220		/// return toml::parse_file(L"foo.toml");
221		/// }
222		/// \ecpp
223		///
224		/// \param file_path The TOML document to parse. Must be valid UTF-8.
225		///
226		/// \returns \conditional_return{With exceptions}
227		/// A toml::table.
228		/// \conditional_return{Without exceptions}
229		/// A toml::parse_result.
230		TOML_NODISCARD
231		TOML_EXPORTED_FREE_FUNCTION
232		parse_result TOML_CALLCONV parse_file(std::wstring_view file_path);
233
234		#endif // TOML_ENABLE_WINDOWS_COMPAT
235
236		#if TOML_HAS_CHAR8 && TOML_ENABLE_WINDOWS_COMPAT
237
238		/// \brief Parses a TOML document from a char8_t string view.
239		///
240		/// \availability This overload is only available when #TOML_ENABLE_WINDOWS_COMPAT is enabled.
241		///
242		/// \detail \cpp
243		/// auto tbl = toml::parse(u8"a = 3"sv, L"foo.toml");
244		/// std::cout << tbl["a"] << "\n";
245		/// \ecpp
246		///
247		/// \out
248		/// 3
249		/// \eout
250		///
251		/// \param doc The TOML document to parse. Must be valid UTF-8.
252		/// \param source_path The path used to initialize each node's `source().path`.
253		/// If you don't have a path (or you have no intention of using paths in diagnostics)
254		/// then this parameter can safely be left blank.
255		///
256		/// \returns \conditional_return{With exceptions}
257		/// A toml::table.
258		/// \conditional_return{Without exceptions}
259		/// A toml::parse_result.
260		TOML_NODISCARD
261		TOML_EXPORTED_FREE_FUNCTION
262		parse_result TOML_CALLCONV parse(std::u8string_view doc, std::wstring_view source_path);
263
264		#endif // TOML_HAS_CHAR8 && TOML_ENABLE_WINDOWS_COMPAT
265
266		/// \brief Parses a TOML document from a stream.
267		///
268		/// \detail \cpp
269		/// std::stringstream ss;
270		/// ss << "a = 3"sv;
271		///
272		/// auto tbl = toml::parse(ss);
273		/// std::cout << tbl["a"] << "\n";
274		/// \ecpp
275		///
276		/// \out
277		/// 3
278		/// \eout
279		///
280		/// \param doc The TOML document to parse. Must be valid UTF-8.
281		/// \param source_path The path used to initialize each node's `source().path`.
282		/// If you don't have a path (or you have no intention of using paths in diagnostics)
283		/// then this parameter can safely be left blank.
284		///
285		/// \returns \conditional_return{With exceptions}
286		/// A toml::table.
287		/// \conditional_return{Without exceptions}
288		/// A toml::parse_result.
289		TOML_NODISCARD
290		TOML_EXPORTED_FREE_FUNCTION
291		parse_result TOML_CALLCONV parse(std::istream & doc, std::string_view source_path = {});
292
293		/// \brief Parses a TOML document from a stream.
294		///
295		/// \detail \cpp
296		/// std::stringstream ss;
297		/// ss << "a = 3"sv;
298		///
299		/// auto tbl = toml::parse(ss, "foo.toml");
300		/// std::cout << tbl["a"] << "\n";
301		/// \ecpp
302		///
303		/// \out
304		/// 3
305		/// \eout
306		///
307		/// \param doc The TOML document to parse. Must be valid UTF-8.
308		/// \param source_path The path used to initialize each node's `source().path`.
309		/// If you don't have a path (or you have no intention of using paths in diagnostics)
310		/// then this parameter can safely be left blank.
311		///
312		/// \returns \conditional_return{With exceptions}
313		/// A toml::table.
314		/// \conditional_return{Without exceptions}
315		/// A toml::parse_result.
316		TOML_NODISCARD
317		TOML_EXPORTED_FREE_FUNCTION
318		parse_result TOML_CALLCONV parse(std::istream & doc, std::string && source_path);
319
320		TOML_ABI_NAMESPACE_END; // TOML_EXCEPTIONS
321
322		inline namespace literals
323		{
324		TOML_ABI_NAMESPACE_BOOL(TOML_EXCEPTIONS, lit_ex, lit_noex);
325
326		/// \brief Parses TOML data from a string literal.
327		///
328		/// \detail \cpp
329		/// using namespace toml::literals;
330		///
331		/// auto tbl = "a = 3"_toml;
332		/// std::cout << tbl["a"] << "\n";
333		/// \ecpp
334		///
335		/// \out
336		/// 3
337		/// \eout
338		///
339		/// \param str The string data. Must be valid UTF-8.
340		/// \param len The string length.
341		///
342		/// \returns \conditional_return{With exceptions}
343		/// A toml::table.
344		/// \conditional_return{Without exceptions}
345		/// A toml::parse_result.
346		TOML_NODISCARD
347		TOML_ALWAYS_INLINE
348		parse_result operator""_toml(const char* str, size_t len)
349	0	{
350	0	return parse(std::string_view{ str, len });
351	0	}
352
353		#if TOML_HAS_CHAR8
354
355		/// \brief Parses TOML data from a UTF-8 string literal.
356		///
357		/// \detail \cpp
358		/// using namespace toml::literals;
359		///
360		/// auto tbl = u8"a = 3"_toml;
361		/// std::cout << tbl["a"] << "\n";
362		/// \ecpp
363		///
364		/// \out
365		/// 3
366		/// \eout
367		///
368		/// \param str The string data. Must be valid UTF-8.
369		/// \param len The string length.
370		///
371		/// \returns \conditional_return{With exceptions}
372		/// A toml::table.
373		/// \conditional_return{Without exceptions}
374		/// A toml::parse_result.
375		TOML_NODISCARD
376		TOML_ALWAYS_INLINE
377		parse_result operator""_toml(const char8_t* str, size_t len)
378		{
379		return parse(std::u8string_view{ str, len });
380		}
381
382		#endif // TOML_HAS_CHAR8
383
384		TOML_ABI_NAMESPACE_END; // TOML_EXCEPTIONS
385		}
386		}
387		TOML_NAMESPACE_END;
388
389		#include "header_end.hpp"
390		#endif // TOML_ENABLE_PARSER