Source

Usage

1try {
2    auto source = Source::fromFile(u8"configuration.elcl");
3    el::conf::Parser parser;
4    auto document = parser.parseOrThrow(source)
5    // ...
6} catch (const el::conf::Error &error) {
7    std::cerr << error.toText().toCharString() << "\n";
8    exit(1);
9}

 1try {
 2    auto source = Source::fromText(
 3        u8"[main]\n"
 4        u8"value = 12\n");
 5    el::conf::Parser parser;
 6    auto document = parser.parseOrThrow(source)
 7    // ...
 8} catch (const el::conf::Error &error) {
 9    std::cerr << error.toText().toCharString() << "\n";
10    exit(1);
11}

Interface

class Source

Interface for the data source to read the configuration.

Implementation notes:

  • Constructing instances of source subclasses should be a lightweight operation, as sources may be created in batches, e.g. when an \@include directive with a recursive pattern is encountered.

  • The constructor of a source shouldn’t throw exceptions, unless a program termination due to internal errors is favourable.

  • Heavy allocations and API calls shall be made in the open() method.

  • Any IO exceptions shall be raised in the open() and/or readLine() methods.

Tested:

SourceCreateTest

Public Functions

virtual ~Source() = default

Default destructor.

inline const String &name() const noexcept

Get the name of the source.

The name of the source also specifies its type or protocol. In a source identifier, the source name is separated from the source path by a colon.

Returns:

The name of the source.

inline const String &path() const noexcept

Get the path of the source.

The path of the source specifies the location of the source. In a source identifier, the source path is separated from the source name by a colon.

Returns:

The path of the source.

virtual SourceIdentifierPtr identifier() const noexcept = 0

Get the source identifier.

Returns:

The source identifier.

virtual void open() = 0

Open the source.

The open method is only called once in the lifetime of a source. After a successful call of open(), the method isOpen() must return true.

Throws:

Error – (IO) If an error occurs while opening the source.

virtual bool isOpen() const noexcept = 0

Test if the source is open.

Returns:

true if the source is open, false otherwise.

virtual bool atEnd() const noexcept = 0

Test if the source reached its end.

Returns:

true if the source reached its end, false otherwise.

virtual std::size_t readLine(std::span<std::byte> lineBuffer) = 0

Reads a line from the source.

The read line must contain the ending newline sequence if there is any.

Parameters:

lineBuffer – The buffer to store the read line.

Throws:

Error – (IO) If an error occurs while reading the line.

Returns:

The number of bytes read, or zero if no more data was available (e.g. when the file situation changed since the last end-of-file check.)

virtual void close() noexcept = 0

Closes the source.

Closes the source and releases any system resources associated with the source. After a call of close(), the method isOpen() must return false.

Public Static Functions

static SourcePtr fromFile(const String &path) noexcept

Create a source for a file path.

The returned source does not open the file immediately. The file is opened on the first call to open().

Parameters:

path – The path to the file.

static SourcePtr fromFile(const std::filesystem::path &path) noexcept

Create a source for a file path.

The returned source does not open the file immediately. The file is opened on the first call to open().

Parameters:

path – The path to the file.

static SourcePtr fromString(const String &text) noexcept

Create a source from the given UTF-8 encoded string.

Parameters:

text – The string with the text. A copy of the string is stored in the source.

static SourcePtr fromString(std::string &&text) noexcept

Create a source from the given UTF-8 encoded string.

Parameters:

text – The string with the text. A copy of the string is stored in the source.

static SourcePtr fromString(const std::string &text) noexcept

Create a source from the given UTF-8 encoded string.

Parameters:

text – The string with the text. A copy of the string is stored in the source.

class SourceIdentifier

Lightweight identifier for a configuration source.

Instances of this class are usually shared between locations so that the parser and higher layers can refer to the same source without copying the underlying name and path strings.

Tested:

SourceIdentifierTest

Public Functions

inline SourceIdentifier(String name, String path, impl::PrivateTag) noexcept

Create a new source identifier with explicit name and path.

Parameters:

  • name – The name of the source.

  • path – The path of the source.

~SourceIdentifier() = default

Default destructor.

inline bool operator==(const SourceIdentifier &other) const noexcept

Compare this source identifier to another for equality.

Parameters:

other – The other identifier to compare.

Returns:

true if both identifiers have the same name and path.

inline bool operator!=(const SourceIdentifier &other) const noexcept

Compare this source identifier to another for inequality.

Parameters:

other – The other identifier to compare.

Returns:

true if the identifiers differ.

inline const String &name() const noexcept

Get the name of the source.

inline const String &path() const noexcept

Get the path of the source.

inline String toText() const noexcept

Get a text representation of this source identifier.

Returns:

A text representation of the identifier.

Public Static Functions

static inline SourceIdentifierPtr create(String name, String path) noexcept

Factory function to create a shared source identifier.

Parameters:

  • name – The source name.

  • path – The source path.

Returns:

Shared-pointer to the new instance.

static inline SourceIdentifierPtr createForFile(String path) noexcept

Create a new source identifier for a file.

Parameters:

path – The source path.

Returns:

Shared-pointer to the new instance.

static inline SourceIdentifierPtr createForText() noexcept

Create a new source identifier for text.

Returns:

Shared-pointer to the new instance.

static inline bool areEqual(const SourceIdentifierPtr &a, const SourceIdentifierPtr &b) noexcept

A helper function to easily compare two source identifier pointers.

Parameters:

  • a – The first identifier.

  • b – The second identifier.

Returns:

true if both identifier pointers are either nullptr, or compare to the same values.

using erbsland::conf::SourcePtr = std::shared_ptr<Source>
using erbsland::conf::SourcePtrConst = std::shared_ptr<const Source>
using erbsland::conf::SourceList = std::vector<SourcePtr>
using erbsland::conf::SourceListPtr = std::shared_ptr<SourceList>
using erbsland::conf::SourceIdentifierPtr = std::shared_ptr<SourceIdentifier>