keyword.cpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup daq_ocm_libfits
 * @copyright 2022 ESO - European Southern Observatory
 *
 * @brief Definition of contents from fits/keyword.hpp
 */
#include <daq/fits/keyword.hpp>
 
#include <algorithm>
#include <cassert>
#include <iostream>
#include <ostream>
 
#include <fmt/format.h>
 
namespace {
template <class>
inline constexpr bool always_false_v = false;  // NOLINT
template <class T>
char const* TypeStr() noexcept;
template <>
char const* TypeStr<uint64_t>() noexcept {
    return "uint64_t";
}
template <>
char const* TypeStr<int64_t>() noexcept {
    return "int64_t";
}
template <>
char const* TypeStr<double>() noexcept {
    return "double";
}
 
std::string FormatFitsValue(daq::fits::KeywordNameView name,
                            daq::fits::BasicKeywordBase::ValueType const& value) {
    using namespace std::string_view_literals;
    return std::visit(
        [&](auto& value) -> std::string {
            using T = std::decay_t<decltype(value)>;
            if constexpr (std::is_same_v<T, std::string>) {
                if (name.type == daq::fits::KeywordType::Value && name.name == "XTENSION"sv) {
                    // FITS requires XTENSION be padded to at least 8 chars (sec 4.2.1)
                    return fmt::format("'{: <8s}'", value);
                } else {
                    return fmt::format("'{}'", value);
                }
            } else if constexpr (std::is_same_v<T, bool>) {
                return value ? "T" : "F";
            } else if constexpr (std::is_same_v<T, double>) {
                if (value > 10000) {
                    return fmt::format("{:g}", value);
                } else {
                    return fmt::format("{:.1f}", value);
                }
            } else if constexpr (std::is_same_v<T, int64_t>) {
                return fmt::format("{:d}", value);
            } else if constexpr (std::is_same_v<T, uint64_t>) {
                return fmt::format("{:d}", value);
            } else {
                static_assert(always_false_v<T>, "non-exhaustive visitor!");
            }
        },
        value);
}
 
constexpr char const* FMT_VALUEKW_SCALAR = "{:<8}= {:>20}";
constexpr char const* FMT_VALUEKW_STR = "{:<8}= {:<20}";
constexpr char const* FMT_ESOKW = "HIERARCH ESO {} = {}";
constexpr char const* FMT_ALL_COMMENT = "{} / {}";
constexpr char const* FMT_COMMENTARYKW = "{:<8} {}";
 
}  // namespace
 
namespace daq::fits {
namespace {
LiteralKeyword InternalValueKeywordFormat(std::string_view name,
                                          std::string_view value,
                                          std::string_view comment,
                                          bool is_string) {
    // Fixed value format
    auto formatted_name_value =
        fmt::format(is_string ? FMT_VALUEKW_STR : FMT_VALUEKW_SCALAR, name, value);
    if (formatted_name_value.size() > constants::RECORD_LENGTH) {
        throw std::invalid_argument(fmt::format(
            "Formatted name and value does not fit in keyword record. Length: {}, keyword: '{}'",
            formatted_name_value.size(),
            formatted_name_value));
    }
    auto formatted = fmt::format(FMT_ALL_COMMENT, formatted_name_value, comment);
    auto view = std::string_view(formatted).substr(0u, fits::constants::RECORD_LENGTH);
    return LiteralKeyword(view);
}
 
LiteralKeyword
InternalEsoKeywordFormat(std::string_view name, std::string_view value, std::string_view comment) {
    auto formatted_name_value = fmt::format(FMT_ESOKW, name, value);
    if (formatted_name_value.size() > constants::RECORD_LENGTH) {
        throw std::invalid_argument(fmt::format(
            "Formatted name and value does not fit in keyword record. Length: {}, keyword: '{}'",
            formatted_name_value.size(),
            formatted_name_value));
    }
    auto formatted = fmt::format(FMT_ALL_COMMENT, formatted_name_value, comment);
    auto view = std::string_view(formatted).substr(0u, fits::constants::RECORD_LENGTH);
    return LiteralKeyword(view);
}
 
LiteralKeyword InternalCommentaryKeywordFormat(std::string_view name, std::string_view value) {
    auto formatted_name_value = fmt::format(FMT_COMMENTARYKW, name, value);
    if (formatted_name_value.size() > constants::RECORD_LENGTH) {
        throw std::invalid_argument(fmt::format(
            "Formatted name and value does not fit in keyword record. Length: {}, keyword: '{}'",
            formatted_name_value.size(),
            formatted_name_value));
    }
    return LiteralKeyword(formatted_name_value);
}
 
/**
 * Validates logical keyword name according to FITS rules.
 * The rules depend on the type of keyword.
 *
 * Common rules:
 *
 * - Trailing whitespace are insignifant.
 * - Valid character set: [A-Z0-9_-]
 *
 * KeywordType::Value and KeywordType::Commentary:
 * - Size: 1-8 (for an all-spaces keyword there must be one ' ')
 *
 * KeywordType::Eso:
 *
 * - Size: 1 - ESO_HIERARCH_MAX_NAME_LENGTH
 *
 * @throws std::invalid_argument on errors
 */
void ValidateKeywordName(KeywordNameView keyword) {
    if (keyword.name.empty()) {
        throw std::invalid_argument("Keyword name cannot be empty");
    }
    auto max_length = keyword.type == KeywordType::Eso ? constants::ESO_HIERARCH_MAX_NAME_LENGTH
                                                       : constants::KEYWORD_NAME_LENGTH;
    if (keyword.name.size() > max_length) {
        auto msg = fmt::format("Keyword name too long. Maximum is {} and provided name '{}' is {}",
                               max_length,
                               keyword.name,
                               keyword.name.size());
        throw std::invalid_argument(msg);
    }
    auto is_valid_char = [](char c) -> bool {
        return (c >= '0' && c <= '9') || (c >= 'A' && c <= 'Z') || c == ' ' || c == '_' || c == '-';
    };
 
    if (!std::all_of(std::begin(keyword.name), std::end(keyword.name), is_valid_char)) {
        throw std::invalid_argument(fmt::format(
            "Keyword name '{}' contains illegal character. Valid charset is [A-Z0-9_-].",
            keyword.name));
    }
}
 
constexpr KeywordType ParseKeywordType(std::string_view record) noexcept {
    if (record.size() >= constants::KEYWORD_NAME_LENGTH + constants::VALUE_INDICATOR.size()) {
        // If bytes 9 and 10 contain the value indicator it must be a value keyword
        if (record.substr(constants::KEYWORD_NAME_LENGTH, constants::VALUE_INDICATOR.size()) ==
            constants::VALUE_INDICATOR) {
            return KeywordType::Value;
        }
        if (record.size() > constants::ESO_HIERARCH_PREFIX.size()) {
            // HIERARCH ESO keyword must start with 'HIERARCH ESO ' and contain '='.
            auto kw = record.substr(0u, constants::ESO_HIERARCH_PREFIX.size());
            auto remainder = record.substr(constants::ESO_HIERARCH_PREFIX.size(), record.npos);
            if (kw == constants::ESO_HIERARCH_PREFIX && remainder.find('=') != kw.npos) {
                return KeywordType::Eso;
            }
        }
    }
    // Everything else are Commentary keywords.
    return KeywordType::Commentary;
}
 
/**
 * Parse the logical category of an ESO hierarchical keyword.
 *
 * Logical category ignores trailing numbers, so logical category of
 * - `DET1` is `DET`
 * - `DET01` is `DET`
 *
 * However, the logical category for
 * - `DET1A` is `DET1A`
 * - `DET1A1` is `DET1A`.
 *
 * @param name Logical keyword name with the first token being the category.
 * @return logical category (first token stripped of trailing numbers)
 */
constexpr std::string_view ParseLogicalCategory(std::string_view name) noexcept {
    using namespace std::literals::string_view_literals;
    // End of category token
    auto end = name.find_first_of(" ="sv);
    // Trim away any trailing numbers
    auto full_category = name.substr(0, end);
    auto logical_end = full_category.find_last_not_of("0123456789"sv);
    if (logical_end != std::string_view::npos) {
        auto view = name.substr(0, logical_end + 1);
        return view;
    }
    return full_category;
}
 
enum class TrimType { Name, Full };
 
/**
 * Trim string view.
 * If @a trim is @a Name it will try to keep a single space char because that is significant in
 * FITS.
 */
constexpr std::string_view TrimBlanks(std::string_view str, TrimType trim) noexcept {
    if (str.empty()) {
        return str;
    }
    {  // Trim left
        auto trim_pos = str.find_first_not_of(constants::BLANK_CHARS);
        if (trim_pos == std::string_view::npos) {
            // All blanks
            return trim == TrimType::Name ? str.substr(0u, 1u) : std::string_view();
        }
        str.remove_prefix(trim_pos);
    }
    {  // Trim right
        auto trim_pos = str.find_last_not_of(constants::BLANK_CHARS);
        if (trim_pos != std::string_view::npos) {
            str.remove_suffix(str.size() - trim_pos - 1);
        }
    }
    return str;
}
 
/**
 * Read next token in str up to @a delimiter.
 *
 * @returns Trimmed token and position after delimiter in the input str. If delimiter was not found
 *          the returned string_view iterator will be nullopt.
 */
constexpr std::pair<std::string_view, std::optional<std::string_view::size_type>>
NextToken(std::string_view str, char delimiter, TrimType trim) noexcept {
    auto delimiter_pos = str.find(delimiter);
    std::optional<std::string_view::size_type> ret_pos;
    if (delimiter_pos != std::string_view::npos) {
        // Delimiter found
        ret_pos = delimiter_pos + 1;
        str.remove_suffix(str.size() - delimiter_pos);
    }
    auto trimmed = TrimBlanks(str, trim);
    return {trimmed, ret_pos};
}
 
constexpr LiteralKeyword::Components
ParseValueKeywordComponents(std::array<char, 80> const& record_array) {
    auto record = std::string_view(&record_array[0], record_array.size());
    LiteralKeyword::Components components{};
    components.type = KeywordType::Value;
 
    // Name
    components.name = TrimBlanks(record.substr(0u, constants::KEYWORD_NAME_LENGTH), TrimType::Name);
    record.remove_prefix(constants::KEYWORD_NAME_LENGTH + constants::VALUE_INDICATOR.size());
    // Value
    auto [value, comment_start] = NextToken(record, '/', TrimType::Full);
    components.value = value;
    // Optional comment
    if (comment_start.has_value()) {
        record.remove_prefix(*comment_start);
        components.comment = TrimBlanks(record, TrimType::Full);
    } else {
        components.comment = std::string_view();
    }
 
    return components;
}
 
constexpr LiteralKeyword::Components
ParseEsoKeywordComponents(std::array<char, 80> const& record_array) {
    auto record = std::string_view(&record_array[0], record_array.size());
    LiteralKeyword::Components components{};
    components.type = KeywordType::Eso;
    // Name
    record.remove_prefix(constants::ESO_HIERARCH_PREFIX.size());
 
    auto [name, value_start] = NextToken(record, '=', TrimType::Name);
    components.name = name;
    // Value
    if (!value_start.has_value()) {
        throw std::invalid_argument(
            fmt::format("Invalid ESO HIERARCH keyword. No '=' value indicator found: {}", record));
    }
    record.remove_prefix(*value_start);
    auto [value, comment_start] = NextToken(record, '/', TrimType::Full);
    if (value.empty()) {
        throw std::invalid_argument(
            fmt::format("Invalid ESO HIERARCH keyword. No value found: {}", record));
    }
    components.value = value;
    // Optional comment
    if (comment_start.has_value()) {
        record.remove_prefix(*comment_start);
        components.comment = TrimBlanks(record, TrimType::Full);
    } else {
        components.comment = std::string_view();
    }
 
    return components;
}
 
constexpr LiteralKeyword::Components
ParseCommentaryKeywordComponents(std::array<char, 80> const& record_array) {
    auto record = std::string_view(&record_array[0], record_array.size());
    LiteralKeyword::Components components{};
    components.type = KeywordType::Commentary;
 
    // Name
    components.name = TrimBlanks(record.substr(0u, constants::KEYWORD_NAME_LENGTH), TrimType::Name);
    record.remove_prefix(constants::KEYWORD_NAME_LENGTH);
    // Value
    components.value = TrimBlanks(record, TrimType::Full);
 
    // Commentary keywords does not have a comment
    components.comment = std::string_view();
 
    return components;
}
 
[[nodiscard]] LiteralKeyword::Components
ParseKeywordComponents(std::array<char, 80> const& record) {
    auto sv_record = std::string_view(&record[0], record.size());
    auto type = ParseKeywordType(sv_record);
 
    // Parse name component
    switch (type) {
    case KeywordType::Value:
        return ParseValueKeywordComponents(record);
    case KeywordType::Eso:
        return ParseEsoKeywordComponents(record);
    case KeywordType::Commentary:
        return ParseCommentaryKeywordComponents(record);
    };
    std::cerr << __PRETTY_FUNCTION__ << ": Invalid type: " << type << std::endl;
    assert(false);
}
 
}  // namespace
 
bool operator<(KeywordNameView lhs, KeywordNameView rhs) noexcept {
    return lhs.name < rhs.name;
}
 
bool operator==(KeywordNameView lhs, KeywordNameView rhs) noexcept {
    return lhs.type == rhs.type && lhs.name == rhs.name;
}
 
bool operator!=(KeywordNameView lhs, KeywordNameView rhs) noexcept {
    return !(lhs == rhs);
}
 
LiteralKeyword::LiteralKeyword() noexcept {
    std::fill(std::begin(m_record), std::end(m_record), ' ');
    m_components = ParseKeywordComponents(m_record);
    ValidateKeywordName(GetName());
}
 
LiteralKeyword::LiteralKeyword(std::array<char, constants::RECORD_LENGTH> record)
    : m_record(record), m_components(ParseKeywordComponents(m_record)) {
    try {
        ValidateKeywordName(GetName());
    } catch (...) {
        std::throw_with_nested(std::invalid_argument("Failed to construct LiteralKeyword"));
    }
}
 
LiteralKeyword::LiteralKeyword(std::string_view record) : m_record() {
    try {
        if (record.size() > constants::RECORD_LENGTH) {
            throw std::invalid_argument(
                "LiteralKeyword: Keyword with record > 80 chars is invalid");
        }
        std::fill(std::begin(m_record), std::end(m_record), ' ');
        std::copy(std::begin(record), std::end(record), std::begin(m_record));
        m_components = ParseKeywordComponents(m_record);
        ValidateKeywordName(GetName());
    } catch (...) {
        std::throw_with_nested(std::invalid_argument("Failed to construct LiteralKeyword"));
    }
}
 
LiteralKeyword::LiteralKeyword(LiteralKeyword const& other) noexcept {
    *this = other;
}
 
LiteralKeyword& LiteralKeyword::operator=(LiteralKeyword const& other) noexcept {
    m_record = other.m_record;
    // Reconstruct string_views using same offset, but with base of this->m_record.data()
    auto make_offset = [&](std::string_view sv) -> std::string_view {
        if (sv.empty()) {
            return std::string_view();
        }
        auto start_offset = sv.data() - other.m_record.data();
        return std::string_view(m_record.data() + start_offset, sv.size());
    };
    m_components.name = make_offset(other.m_components.name);
    m_components.value = make_offset(other.m_components.value);
    m_components.comment = make_offset(other.m_components.comment);
    m_components.type = other.m_components.type;
    return *this;
}
 
std::string_view LiteralKeyword::GetRecord() const& noexcept {
    auto full = std::string_view(&m_record[0], m_record.size());
    return TrimBlanks(full, TrimType::Name);
}
 
bool operator<(LiteralKeyword const& lhs, LiteralKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
 
bool operator==(LiteralKeyword const& lhs, LiteralKeyword const& rhs) noexcept {
    return lhs.GetRecord() == rhs.GetRecord();
}
 
bool operator!=(LiteralKeyword const& lhs, LiteralKeyword const& rhs) noexcept {
    return lhs.GetRecord() != rhs.GetRecord();
}
 
std::ostream& operator<<(std::ostream& os, LiteralKeyword const& kw) {
    os << kw.GetRecord();
    return os;
}
 
// Instantiate the different variants
template struct BasicKeyword<ValueKeywordTraits>;
template struct BasicKeyword<EsoKeywordTraits>;
 
template std::ostream&
operator<<<EsoKeywordTraits>(std::ostream& os, BasicKeyword<EsoKeywordTraits> const& kw);
 
template std::ostream&
operator<<<ValueKeywordTraits>(std::ostream& os, BasicKeyword<ValueKeywordTraits> const& kw);
 
template <class Trait>
BasicKeyword<Trait>::BasicKeyword(std::string name_arg,
                                  char const* string_value,
                                  std::optional<std::string> comment_arg)
    : name(std::move(name_arg)), value(std::string(string_value)), comment(std::move(comment_arg)) {
    ValidateKeywordName(GetName());
}
 
template <class Trait>
BasicKeyword<Trait>::BasicKeyword(std::string name_arg,
                                  ValueType value_arg,
                                  std::optional<std::string> comment_arg)
    : name(std::move(name_arg)), value(std::move(value_arg)), comment(std::move(comment_arg)) {
    ValidateKeywordName(GetName());
}
 
template <class Trait>
bool BasicKeyword<Trait>::operator==(BasicKeyword<Trait> const& rhs) const noexcept {
    return name == rhs.name && value == rhs.value && comment == rhs.comment;
}
 
template <class Trait>
bool BasicKeyword<Trait>::operator!=(BasicKeyword<Trait> const& rhs) const noexcept {
    return !(*this == rhs);
}
 
template <class Trait>
bool BasicKeyword<Trait>::operator<(BasicKeyword<Trait> const& rhs) const noexcept {
    return name < rhs.name;
}
 
bool NameEquals(KeywordVariant const& lhs, KeywordVariant const& rhs) noexcept {
    if (lhs.index() != rhs.index()) {
        return false;
    }
    return std::visit(
        [&](auto const& lhs, auto const& rhs) noexcept -> bool {
            return lhs.GetName() == rhs.GetName();
        },
        lhs,
        rhs);
}
 
KeywordClass GetKeywordClass(std::string_view name) {
    if (name.size() > FLEN_KEYWORD) {
        throw std::invalid_argument("Keyword too long");
    }
    char record[FLEN_CARD] = {' '};
    std::copy(name.begin(), name.end(), &record[0]);
 
    return static_cast<KeywordClass>(fits_get_keyclass(record));
}
 
bool operator<(LiteralKeyword const& lhs, EsoKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
 
bool operator<(LiteralKeyword const& lhs, ValueKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
bool operator<(ValueKeyword const& lhs, EsoKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
 
bool operator<(ValueKeyword const& lhs, LiteralKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
 
bool operator<(EsoKeyword const& lhs, ValueKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
bool operator<(EsoKeyword const& lhs, LiteralKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
 
std::ostream& operator<<(std::ostream& os, BasicKeywordBase::ValueType const& kw) {
    std::visit(
        [&](auto const& var) mutable {
            using T = std::decay_t<decltype(var)>;
            if constexpr (std::is_same_v<T, std::string>) {
                os << "(str)'" << var << "'";
            } else if constexpr (std::is_same_v<T, bool>) {
                os << "(bool)" << (var ? "true" : "false");
            } else {
                os << "(" << TypeStr<T>() << ")" << var;
            }
        },
        kw);
    return os;
}
 
template <class Trait>
std::ostream& operator<<(std::ostream& os, BasicKeyword<Trait> const& kw) {
    os << "name='" << kw.name << "', value=" << kw.value << ", comment=";
    if (kw.comment) {
        os << "'" << *kw.comment << "'";
    } else {
        os << "n/a";
    }
    return os;
}
 
std::ostream& operator<<(std::ostream& os, KeywordVariant const& kw) {
    std::visit([&](auto const& var) mutable { os << var; }, kw);
    return os;
}
 
void UpdateKeywords(KeywordVector& to, KeywordVector const& from, ConflictPolicy policy) {
    for (auto const& kw : from) {
        if (auto it = std::find_if(
                to.begin(), to.end(), [&](auto const& val) { return NameEquals(val, kw); });
            it != to.end()) {
            if (policy == ConflictPolicy::Replace) {
                // Replace existing keyword with same name (and type)
                *it = kw;
            }
        } else {
            // Otherwise append
            to.emplace_back(kw);
        }
    }
}
 
void InsertKeywords(KeywordVector& keywords,
                    KeywordVector::iterator position,
                    KeywordVector::const_iterator from_first,
                    KeywordVector::const_iterator from_last) {
    // Insert in specified position and then delete duplicates from the two ranges before and after
    // inserted elements.
    auto num_elements = std::distance(from_first, from_last);
    auto pred = [&](KeywordVector::value_type const& kw) -> bool {
        return std::find_if(from_first, from_last, [&](auto const& val) {
                   return NameEquals(val, kw);
               }) != from_last;
    };
    auto inserted_first = keywords.insert(position, from_first, from_last);
    auto after_inserted_first = inserted_first;
    std::advance(after_inserted_first, num_elements);
    keywords.erase(std::remove_if(after_inserted_first, keywords.end(), pred), keywords.end());
    keywords.erase(std::remove_if(keywords.begin(), inserted_first, pred), inserted_first);
}
 
LiteralKeyword Format(EsoKeyword const& keyword) {
    // Fixed value format
    auto name = keyword.GetName();
    auto value = FormatFitsValue(name, keyword.value);
    auto comment = keyword.comment.value_or("");
    return InternalEsoKeywordFormat(name.name, value, comment);
}
 
LiteralKeyword Format(ValueKeyword const& keyword) {
    // Fixed value format
    auto name = keyword.GetName();
    auto value = FormatFitsValue(name, keyword.value);
    auto comment = keyword.comment.value_or("");
    return InternalValueKeywordFormat(
        name.name, value, comment, std::holds_alternative<std::string>(keyword.value));
}
 
LiteralKeyword Format(LiteralKeyword::Components const& keyword) {
    switch (keyword.type) {
    case KeywordType::Value: {
        bool is_str = keyword.value.find('\'') != std::string_view::npos;
        return InternalValueKeywordFormat(keyword.name, keyword.value, keyword.comment, is_str);
    }
    case KeywordType::Eso: {
        return InternalEsoKeywordFormat(keyword.name, keyword.value, keyword.comment);
    }
    case KeywordType::Commentary: {
        return InternalCommentaryKeywordFormat(keyword.name, keyword.value);
    }
    };
    std::cerr << __PRETTY_FUNCTION__ << ": Invalid type: " << keyword.type << std::endl;
    assert(false);
}
 
LiteralKeyword Format(KeywordVariant const& keyword) {
    return std::visit(
        [&](auto& kw) -> LiteralKeyword {
            using T = std::decay_t<decltype(kw)>;
            if constexpr (std::is_same_v<T, LiteralKeyword>) {
                return Format(kw.GetComponents());
            } else {
                return Format(kw);
            }
        },
        keyword);
}
 
namespace v1 {
namespace {
constexpr bool SortEsoKeywordName(std::string_view lhs, std::string_view rhs) noexcept {
    using namespace std::literals::string_view_literals;
 
    auto lhs_cat = ParseLogicalCategory(lhs);
    auto rhs_cat = ParseLogicalCategory(rhs);
    if (lhs_cat == rhs_cat) {
        /* within same category keyword is sorted by name */
        return lhs < rhs;
    }
    // This determines the custom category sorting order:
    std::array<std::string_view, 8> categories = {
        "DPR"sv, "OBS"sv, "TPL"sv, "GEN"sv, "TEL"sv, "ADA"sv, "INS"sv, "DET"sv};
    auto lhs_idx = std::find(std::begin(categories), std::end(categories), lhs_cat);
    auto rhs_idx = std::find(std::begin(categories), std::end(categories), rhs_cat);
 
    if (lhs_idx != std::end(categories)) {
        if (rhs_idx != std::end(categories)) {
            // Both lhs and rhs are have special case categories. Sort by
            // their relative position (note: same category was handled before).
            return std::distance(lhs_idx, rhs_idx) > 0;
        } else {
            /* rhs is an unknown category, sort last */
            return true;
        }
    } else {
        if (rhs_idx != std::end(categories)) {
            /* Sort rhs before lhs as it has special category*/
            return false;
        } else {
            /* both lhs and rhs are unknown categories -> sort by name */
            return lhs < rhs;
        }
    }
}
}  // namespace
 
bool StandardLess::operator()(LiteralKeyword const& lhs_kw, LiteralKeyword const& rhs_kw) noexcept {
    auto lhs = lhs_kw.GetName();
    auto rhs = rhs_kw.GetName();
 
    switch (lhs.type) {
    case Value:
        switch (rhs.type) {
        case Value:
            /* Value never sorted before other Value (stable sorted) */
            return false;
        case Eso:
            [[fallthrough]];
        case Commentary:
            /* lhs Value type sorted before ESO and Commentary types */
            return true;
        }
    case Eso:
        switch (rhs.type) {
        case Value:
            /* lhs is Eso and is sorted after Value */
            return false;
        case Eso:
            /* Both are ESO keywords so sorted by name */
            return SortEsoKeywordName(lhs.name, rhs.name);
        case Commentary:
            /* Eso before commentary */
            return true;
        };
    case Commentary:
        switch (rhs.type) {
        case Value:
            [[fallthrough]];
        case Eso:
            /* lhs is Commentary so sorted after both Value and Eso */
            return false;
        case Commentary:
            /* Commentary keywords are stable sorted last */
            return lhs.name < rhs.name;
        }
    };
    return false;
}
 
void StandardSort(std::vector<LiteralKeyword>& keywords) {
    std::stable_sort(std::begin(keywords), std::end(keywords), StandardLess{});
}
 
}  // namespace v1
 
#if defined(UNIT_TEST)
// Some compile time checks to also verify parsing function are actually constexp.
static_assert(ParseKeywordType("DATE-OBS= 'date'") == KeywordType::Value);
static_assert(ParseKeywordType("DATE-OBS='date'") == KeywordType::Commentary);
static_assert(NextToken("        ='date'", '=', TrimType::Name) ==
              std::pair<std::string_view, std::optional<std::string_view::size_type>>(" ", 9));
#endif
}  // namespace daq::fits