Class TrackedDeck

• Defined in File TrackedDeck.hpp

Nested Relationships

Nested Types

• Struct TrackedDeck::Leaf

Class Documentation

class TrackedDeck

A read-only view of a toml input deck that records which keys are used.

SLUG silently ignores any input-deck key it never reads, so a misspelled or misplaced key (e.g. n_trial given under [output] rather than at the top level) has no effect and no warning. TrackedDeck wraps the parsed deck so that every read is recorded, and can then report the keys that were never read.

Only leaves are tracked: values, and arrays (which are read as a unit). A table is not itself a key, and looking one up – for example to test whether [yields.channel2] exists – does not count as using anything beneath it, so the keys inside it are still reported if nothing reads them. Code that consumes a whole table some other way must say so with markUsedAll().

Some keys are valid but legitimately go unread, e.g. nebular.log_U when nebular.compute_neb is false. Code that skips a section for such a reason calls markIgnored() with the reason, so those keys can be reported separately from genuinely unknown ones.

Every read must go through this class for the report to be complete, which is why it does not expose the underlying toml::table: pass it (as a const reference) to everything that reads the deck, in place of the table itself. It only holds a reference to the table, which must outlive it. The recorded state is mutable so that reading is const, and is not thread safe.

Public Functions

inline explicit TrackedDeck(const toml::table &deck)

Wrap an input deck, recording every leaf key it contains.

Parameters:

deck – The parsed deck; must outlive this object

inline auto atPath(const std::string_view path) const -> toml::node_view<const toml::node>

Look up a key, recording the access.

A leaf that exists is marked used. A key that does not exist is remembered as one the code looked for, which is what lets an unused key be matched to the key it was probably meant to be (see unused()). A table is neither: looking one up marks nothing.

Parameters:

path – Dotted path of the key, e.g. “stars.FeH”

Returns:

The same node_view toml::table::at_path() would; empty if the key does not exist

template<class T>
inline auto value(const std::string &path, const bool required = false) const -> std::optional<T>

Read a typed value, recording the access.

Template Parameters:

T – Type to read; any type utils::getTOMLKeyWithError() is instantiated for

Parameters:

• path – Dotted path of the key

• required – Whether a missing key is an error

Throws:

std::runtime_error – under exactly the conditions utils::getTOMLKeyWithError() does: a required key is missing, or the key cannot be read as a T

Returns:

The value, or an empty optional if the key is absent and not required

inline auto initPDF(const std::string &path, const std::string &prefix = "") const -> pdfs::PDF

Read a probability distribution, recording the access.

Parameters:

• path – Dotted path of the key

• prefix – Directory prefix used to locate a PDF file, as for utils::initPDFFromKey()

Throws:

std::runtime_error – under exactly the conditions utils::initPDFFromKey() does

Returns:

The distribution

inline void markUsedAll(const std::string_view prefix) const

Record that every key at or beneath a path has been consumed.

Parameters:

prefix – Dotted path of a table (or a single key)

inline void markIgnored(const std::string_view prefix, const std::string_view reason) const

Record that every not-yet-used key at or beneath a path is being deliberately ignored.

The keys are not marked used, so a later read still counts as a use, and they are reported by ignored() instead of unused().

Parameters:

• prefix – Dotted path of a table (or a single key)

• reason – Why the keys are not read, e.g. “nebular.compute_neb is false”

inline auto unused() const -> std::vector<DeckKeyReport>

Keys that were never read and were not marked ignored.

Returns:

One report per key, in path order, each with a hint if one could be found: the key the code looked for that this one most plausibly was meant to be

inline auto ignored() const -> std::vector<DeckKeyReport>

Keys that were never read because the code deliberately skipped them.

Returns:

One report per key, in path order, each with the reason given to markIgnored()