iris::Spec Class Reference

Doxygen 1.15.0 generates this reference during each site build from the public headers. The C++ guide shows the API in use.

A parsed and checked reader spec. More...

#include <iris/spec.hpp>

Public Member Functions
std::string_view	name () const
	Return the format name from the format metadata, or an empty name.
Data	read (const std::filesystem::path &path, const Params &params={}) const
	Read the input file at path with the parameters params.
Data	read_text (std::string_view text, std::string_view origin="<input>", const Params &params={}) const
	Read the input text from origin, which names it in errors, with the parameters params.
std::expected< Data, Error >	try_read (const std::filesystem::path &path, const Params &params={}) const
	Read like read(), but return a language error instead of throwing it.
std::expected< Data, Error >	try_read_text (std::string_view text, std::string_view origin="<input>", const Params &params={}) const
	Read like read_text(), but return the Error instead of throwing it.
Data	catalog (const std::filesystem::path &path, const Params &params={}) const
	Catalog the instances of the input file at path with the parameters params: read every instance and return the entries instances, name if every instance has a name, and failed if an instance is rejected (Specification §9.6).
Data	catalog_text (std::string_view text, std::string_view origin="<input>", const Params &params={}) const
	Catalog the input text from origin like catalog().
std::expected< Data, Error >	try_catalog (const std::filesystem::path &path, const Params &params={}) const
	Catalog like catalog(), but return a language error instead of throwing it.
std::expected< Data, Error >	try_catalog_text (std::string_view text, std::string_view origin="<input>", const Params &params={}) const
	Catalog like catalog_text(), but return the Error instead of throwing it.

Static Public Member Functions
static Spec	parse (std::string_view text, std::string_view origin="<spec>", std::pmr::memory_resource &memory= *std::pmr::get_default_resource())
	Parse the reader spec text from origin, which names it in errors, and allocate from memory.
static std::expected< Spec, Error >	try_parse (std::string_view text, std::string_view origin="<spec>", std::pmr::memory_resource &memory= *std::pmr::get_default_resource())
	Parse like parse(), but return the Error instead of throwing it.
static Spec	load (const std::filesystem::path &path, std::pmr::memory_resource &memory= *std::pmr::get_default_resource())
	Parse the reader spec in the file at path, which names it in errors, and allocate from memory.
static std::expected< Spec, Error >	try_load (const std::filesystem::path &path, std::pmr::memory_resource &memory= *std::pmr::get_default_resource())
	Load like load(), but return the Error instead of throwing it.

Detailed Description

A parsed and checked reader spec.

Copies share the parsed spec, which never changes, so they are cheap. Reading does not change it either, so threads can read with one spec at the same time.

Every allocation the library makes for the spec, and for the data it reads, comes from the memory resource given when the spec is parsed: the default resource unless another is given. The resource must outlive the spec and the data, and be thread-safe if threads read with the spec at the same time. Errors, which leave the library, are the exception: they use the global heap.

Each operation that throws an Error has a try_ variant that returns it instead. Both still throw std::system_error for a file that cannot be read, AccessError for misuse, and std::bad_alloc.

Member Function Documentation

catalog()

Data iris::Spec::catalog ( const std::filesystem::path & path, const Params & params = {} ) const

nodiscard

Catalog the instances of the input file at path with the parameters params: read every instance and return the entries instances, name if every instance has a name, and failed if an instance is rejected (Specification §9.6).

Throws like read().

catalog_text()

Data iris::Spec::catalog_text ( std::string_view text, std::string_view origin = "<input>", const Params & params = {} ) const

nodiscard

Catalog the input text from origin like catalog().

Throws Error for every language error.

load()

Spec iris::Spec::load ( const std::filesystem::path & path, std::pmr::memory_resource & memory = *std::pmr::get_default_resource() )

static

Parse the reader spec in the file at path, which names it in errors, and allocate from memory.

Throws like parse(), and std::system_error if the file cannot be read.

name()

std::string_view iris::Spec::name ( ) const

nodiscard

Return the format name from the format metadata, or an empty name.

parse()

Spec iris::Spec::parse ( std::string_view text, std::string_view origin = "<spec>", std::pmr::memory_resource & memory = *std::pmr::get_default_resource() )

static

Parse the reader spec text from origin, which names it in errors, and allocate from memory.

Throws Error for every parse-time error.

read()

Data iris::Spec::read ( const std::filesystem::path & path, const Params & params = {} ) const

nodiscard

Read the input file at path with the parameters params.

Throws Error for every language error, and std::system_error if the file cannot be read.

read_text()

Data iris::Spec::read_text ( std::string_view text, std::string_view origin = "<input>", const Params & params = {} ) const

nodiscard

Read the input text from origin, which names it in errors, with the parameters params.

Throws Error for every language error.

try_catalog()

std::expected< Data, Error > iris::Spec::try_catalog ( const std::filesystem::path & path, const Params & params = {} ) const

nodiscard

Catalog like catalog(), but return a language error instead of throwing it.

try_catalog_text()

std::expected< Data, Error > iris::Spec::try_catalog_text ( std::string_view text, std::string_view origin = "<input>", const Params & params = {} ) const

nodiscard

Catalog like catalog_text(), but return the Error instead of throwing it.

try_load()

std::expected< Spec, Error > iris::Spec::try_load ( const std::filesystem::path & path, std::pmr::memory_resource & memory = *std::pmr::get_default_resource() )

static

Load like load(), but return the Error instead of throwing it.

try_parse()

std::expected< Spec, Error > iris::Spec::try_parse ( std::string_view text, std::string_view origin = "<spec>", std::pmr::memory_resource & memory = *std::pmr::get_default_resource() )

static

Parse like parse(), but return the Error instead of throwing it.

try_read()

std::expected< Data, Error > iris::Spec::try_read ( const std::filesystem::path & path, const Params & params = {} ) const

nodiscard

Read like read(), but return a language error instead of throwing it.

try_read_text()

std::expected< Data, Error > iris::Spec::try_read_text ( std::string_view text, std::string_view origin = "<input>", const Params & params = {} ) const

nodiscard

Read like read_text(), but return the Error instead of throwing it.