keyword.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup daq_ocm_libfits
 * @copyright 2022 ESO - European Southern Observatory
 *
 * @brief Contains data structure for FITS keywords
 */
#ifndef DAQ_OCM_DAQ_FITS_KEYWORD_HPP_
#define DAQ_OCM_DAQ_FITS_KEYWORD_HPP_
 
#include <array>
#include <cstdint>
#include <iosfwd>
#include <optional>
#include <stdexcept>
#include <string>
#include <variant>
#include <vector>
 
#include <cfitsio/fitsio.h>
 
namespace daq::fits {
// Forward declarations
enum KeywordType : uint8_t;
class KeywordFormatter;
 
namespace constants {
/**
 * FITS keyword record length.
 */
static constexpr std::size_t RECORD_LENGTH = 80u;
/**
 * FITS keyword name length.
 */
static constexpr std::size_t KEYWORD_NAME_LENGTH = 8u;
/**
 * ESO keyword prefix, up to and including trailing whitespace
 */
static constexpr std::string_view ESO_HIERARCH_PREFIX = "HIERARCH ESO ";
/**
 * Absolute maximum length of logical keyword assuming packed value-indicator `= ` and no value
 */
static constexpr std::size_t ESO_HIERARCH_MAX_NAME_LENGTH =
    RECORD_LENGTH - ESO_HIERARCH_PREFIX.size() - 2u;
/**
 * Threshold where if name and formatted value >= this limit the packed formatting is used.
 */
static constexpr std::size_t ESO_HIERARCH_NAME_VALUE_PACKED_LIMIT = ESO_HIERARCH_MAX_NAME_LENGTH;
 
/**
 * FITS value indicator.
 */
static constexpr std::string_view VALUE_INDICATOR = "= ";
/**
 * Blank chars which is used to determine end of keyword record.
 */
static constexpr std::string_view BLANK_CHARS = std::string_view(" \0", 2);
}  // namespace constants
 
/**
 * Type of FITS keyword.
 *
 * FITS standard define two types: Value keywords and Commentary keywords.
 *
 * ESO conventions adds a third "ESO hiearchical keyword" which is strictly speaking a
 * Commentary keyword with keyword name "HIERARCH".
 */
enum KeywordType : std::uint8_t {
    /**
     * A value keyword.
     */
    Value,
    /**
     * An ESO hiearchical keyword.
     */
    Eso,
    /**
     * A commentary keyword, which are keywords that do not fall into the previous categories.
     */
    Commentary,
};
 
struct KeywordNameView {
    std::string_view name;
    KeywordType type;
};
 
/**
 * Fits keyword type
 *
 * See https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/node52.html#ffdtyp
 */
enum class KeywordClass : int {
    Structure = TYP_STRUC_KEY,
    Compression = TYP_CMPRS_KEY,
    Scale = TYP_SCAL_KEY,
    Null = TYP_NULL_KEY,
    Dim = TYP_DIM_KEY,
    Range = TYP_RANG_KEY,
    Unit = TYP_UNIT_KEY,
    Disp = TYP_DISP_KEY,
    HduId = TYP_HDUID_KEY,
    Checksum = TYP_CKSUM_KEY,
    Wcs = TYP_WCS_KEY,
    RefSys = TYP_REFSYS_KEY,
    Comment = TYP_COMM_KEY,
    Continue = TYP_CONT_KEY,
 
    User = TYP_USER_KEY,
};
 
/**
 * @returns true if keyword type and names are equal.
 * @relatesalso KeywordNameView
 */
bool operator==(KeywordNameView lhs, KeywordNameView rhs) noexcept;
 
/**
 * @returns true if keyword type and names are not equal.
 * @relatesalso KeywordNameView
 */
bool operator!=(KeywordNameView lhs, KeywordNameView rhs) noexcept;
 
/**
 * Represents the literal 80-character FITS keyword record.
 *
 * @ingroup daq_ocm_libfits
 */
class LiteralKeyword final {
public:
    /**
     * Decomposed components a literal keyword.
     */
    struct Components {
        KeywordType type;
 
        std::string_view name;
        std::string_view value;
        /**
         * Comment may be empty
         */
        std::string_view comment;
    };
 
    /**
     * Initializes an empty record (filled with ' ' characters)
     */
    LiteralKeyword() noexcept;
 
    /**
     * Construct literal keyword from a fixed size record.
     *
     * @param record FITS keyword record literal.
     */
    explicit LiteralKeyword(std::array<char, constants::RECORD_LENGTH> record);
 
    /**
     * Construct literal keyword from string_view.
     *
     * @note If string_view is empty this will be interpreted as the (valid) keyword "        ".
     *
     * @param record literal keyword record.
     *
     * @throw std::invalid_argument if record is invalid (size() > 80).
     */
    explicit LiteralKeyword(std::string_view record);
 
    LiteralKeyword(LiteralKeyword const& other) noexcept;
    LiteralKeyword& operator=(LiteralKeyword const& other) noexcept;
 
    /**
     * @return Keyword type.
     */
    constexpr KeywordType GetType() const noexcept {
        return m_components.type;
    }
 
    /**
     * Query logical keyword name.
     *
     * The logical keyword name depends on the type of keyword:
     *
     * - Type::Value: Returns same value as GetName() but without trailing whitespaces.
     * - Type::Eso: Returns the logical keyword name following "HIEARCH ESO" up to the first "=",
     *   without leading or trailing whitespaces.
     * - Type::Commentary: Keywords that do not fall into
     *
     * @returns the logical keyword name which depends on the type of keyword and the type.
     */
    constexpr KeywordNameView GetName() const& noexcept {
        return {m_components.name, m_components.type};
    }
    KeywordNameView GetName() && noexcept = delete;
 
    /**
     * @returns the FITS keyword record without trailing blank characters.
     *
     * @todo Rename to GetLogicalRecord?
     */
    std::string_view GetRecord() const& noexcept;
    constexpr std::string_view GetRecord() && noexcept = delete;
 
    /**
     * Get components of the keyword in its literal form with insignifant whitespaces removed.
     */
    constexpr Components GetComponents() const& noexcept {
        return m_components;
    }
 
private:
    std::array<char, constants::RECORD_LENGTH> m_record;
    // Components refer to m_record
    Components m_components;
};
 
auto operator==(LiteralKeyword::Components const& lhs,
                LiteralKeyword::Components const& rhs) noexcept -> bool;
 
auto operator!=(LiteralKeyword::Components const& lhs,
                LiteralKeyword::Components const& rhs) noexcept -> bool;
/**
 * Sort by logical keyword name (not DICD sort)
 *
 * @relatesalso LiteralKeyword
 * @ingroup daq_ocm_libfits
 */
bool operator<(LiteralKeyword const&, LiteralKeyword const&) noexcept;
 
/**
 * Compares equally if keyword record in @a lhs is the same as @a rhs (char for char).
 *
 * @relatesalso LiteralKeyword
 * @ingroup daq_ocm_libfits
 */
bool operator==(LiteralKeyword const& lhs, LiteralKeyword const& rhs) noexcept;
 
/**
 * Compares inequally if keyword record in @a lhs is not the same as @a rhs (char for char).
 *
 * @relatesalso LiteralKeyword
 * @ingroup daq_ocm_libfits
 */
bool operator!=(LiteralKeyword const&, LiteralKeyword const&) noexcept;
 
std::ostream& operator<<(std::ostream& os, LiteralKeyword const& kw);
 
/**
 * Non template base class that is purely used to avoid type-deduction issues of ValueType.
 */
struct BasicKeywordBase {
    // Possible value types that can be carried in a keyword
    using ValueType = std::variant<std::string, std::int64_t, std::uint64_t, double, bool>;
};
 
/**
 * A type safe version of LiteralKeyword that consist of the three basic components of a FITS
 * keyword keyword record: name, value and optional comment.
 *
 * @note name should be used for the logical keyword name, not the keyword name according to FITS
 * standard. E.g. the ESO hiearchical keywords all have the keyword name HIERARCH according to the
 * standard, but this structure should instead use the logical fields where e.g. "HIERARCH ESO DPR
 * CATG" is the logical keyword name.
 *
 * It does not model any specific unit, only the value type. Therefore it is not strictly necessary
 * to have all possible types represented in ValueType (e.g. both singel and double precision
 * floats).
 *
 * The idea is that the unit, formatting and ranges is provided provided by dictionaries.
 *
 * It also typically requires a dictionary to be able to understand how to parse @c value.
 *
 * @ingroup daq_ocm_libfits
 */
template <class Trait>
struct BasicKeyword final : BasicKeywordBase {
    BasicKeyword() = default;
    BasicKeyword(BasicKeyword const&) = default;
    BasicKeyword(BasicKeyword&&) noexcept = default;
    BasicKeyword(std::string name,
                 char const* string_value,
                 std::optional<std::string> comment = std::nullopt);
    BasicKeyword(std::string name,
                 ValueType value,
                 std::optional<std::string> comment = std::nullopt);
 
    BasicKeyword& operator=(BasicKeyword&& rhs) noexcept = default;
    BasicKeyword& operator=(BasicKeyword const& rhs) = default;
 
    /**
     * Query logical keyword name.
     *
     * @returns logical keyword name.
     */
    constexpr KeywordNameView GetName() const& noexcept {
        return KeywordNameView{name, Trait::GetKeywordType()};
    }
    KeywordNameView GetName() && = delete;
 
    /**
     * Compares all members for equality.
     */
    bool operator==(BasicKeyword const& rhs) const noexcept;
    /**
     * Compares all members for inequality.
     */
    bool operator!=(BasicKeyword const& rhs) const noexcept;
    /**
     * Uses @a name property as the sorting index.
     */
    bool operator<(BasicKeyword const& rhs) const noexcept;
 
    /**
     * Trimmed keyword name
     */
    std::string name;
    ValueType value;
    /**
     * Trimmed keyword comment
     */
    std::optional<std::string> comment;
};
 
struct ValueKeywordTraits {
    static constexpr KeywordType GetKeywordType() noexcept {
        return KeywordType::Value;
    }
};
struct EsoKeywordTraits {
    static constexpr KeywordType GetKeywordType() noexcept {
        return KeywordType::Eso;
    }
};
 
/**
 * Standard FITS value keyword.
 *
 * @ingroup daq_ocm_libfits
 */
using ValueKeyword = BasicKeyword<ValueKeywordTraits>;
 
/**
 * ESO hiearchical keyword.
 *
 * @ingroup daq_ocm_libfits
 */
using EsoKeyword = BasicKeyword<EsoKeywordTraits>;
 
/**
 * Keyword sorting function.
 *
 * @relatesalso ValueKeyword
 * @relatesalso EsoKeyword
 * @ingroup daq_ocm_libfits
 */
bool operator<(LiteralKeyword const&, EsoKeyword const&) noexcept;
/**
 * Keyword sorting function.
 *
 * @relatesalso ValueKeyword
 * @relatesalso LiteralKeyword
 * @ingroup daq_ocm_libfits
 */
bool operator<(LiteralKeyword const&, ValueKeyword const&) noexcept;
/**
 * Keyword sorting function.
 *
 * @relatesalso ValueKeyword
 * @relatesalso EsoKeyword
 * @ingroup daq_ocm_libfits
 */
bool operator<(ValueKeyword const&, EsoKeyword const&) noexcept;
/**
 * Keyword sorting function.
 *
 * @relatesalso ValueKeyword
 * @relatesalso LiteralKeyword
 * @ingroup daq_ocm_libfits
 */
bool operator<(ValueKeyword const&, LiteralKeyword const&) noexcept;
 
/**
 * Keyword sorting function.
 *
 * @relatesalso ValueKeyword
 * @relatesalso EsoKeyword
 * @ingroup daq_ocm_libfits
 */
bool operator<(EsoKeyword const&, ValueKeyword const&) noexcept;
/**
 * Keyword sorting function.
 *
 * @relatesalso LiteralKeyword
 * @relatesalso EsoKeyword
 * @ingroup daq_ocm_libfits
 */
bool operator<(EsoKeyword const&, LiteralKeyword const&) noexcept;
 
template <class Trait>
std::ostream& operator<<(std::ostream& os, BasicKeyword<Trait> const& kw);
 
template <class Trait>
std::ostream& operator<<(std::ostream& os, BasicKeywordBase::ValueType const& kw);
 
/**
 * The different variants of keywords that are supported.
 *
 * @ingroup daq_ocm_libfits
 */
using KeywordVariant = std::variant<ValueKeyword, EsoKeyword, LiteralKeyword>;
 
/**
 * Subset of value-typed keywords.
 *
 * @ingroup daq_ocm_libfits
 */
using TypedKeywordVariant = std::variant<ValueKeyword, EsoKeyword>;
 
/**
 * Vector of keywords.
 *
 * @ingroup daq_ocm_libfits
 */
using KeywordVector = std::vector<KeywordVariant>;
 
/**
 * Ostream formatting of keywords.
 *
 * @ingroup daq_ocm_libfits
 */
std::ostream& operator<<(std::ostream& os, KeywordVariant const& kw);
 
/**
 * Get keyword name from @a keyword.
 * @param keyword Keyword to query.
 */
constexpr KeywordNameView GetKeywordName(EsoKeyword const& keyword) noexcept {
    return keyword.GetName();
}
 
constexpr KeywordNameView GetKeywordName(ValueKeyword const& keyword) noexcept {
    return keyword.GetName();
}
 
/**
 * Get keyword name from @a keyword variant.
 * @param keyword Keyword to query.
 */
constexpr KeywordNameView GetKeywordName(KeywordVariant const& keyword) noexcept {
    return std::visit([&](auto const& kw) { return kw.GetName(); }, keyword);
}
 
/**
 * Get keyword class
 * @param name Keyword name.
 * @return keyword class.
 */
KeywordClass GetKeywordClass(std::string_view name);
 
/**
 * Compare logical keyword names of keyword of the same type.
 *
 * Comparing names only is useful to e.g. look up keyword by name, to modify it.
 *
 * @param lhs value to compare
 * @param rhs value to compare
 * @returns true iff lhs and rhs are the same type and their name property compares equal.
 *
 * @ingroup daq_ocm_libfits
 */
bool NameEquals(KeywordVariant const& lhs, KeywordVariant const& rhs) noexcept;
 
enum class ConflictPolicy {
    /**
     * Replace keyword that conflicts.
     */
    Replace,
    /**
     * Skip keyword that conflicts.
     */
    Skip
};
 
/**
 * Updates @a to with keywords from @a from.
 *
 * New keywords are inserted at the end. Existing keywords will be updated with new value if
 * keyword type and name is the same.
 *
 * @param to Keywords to update to.
 * @param from Keywords to update from.
 * @param policy Determines what to do for a keyword conflict.
 *
 * @ingroup daq_ocm_libfits
 */
void UpdateKeywords(KeywordVector& to,
                    KeywordVector const& from,
                    ConflictPolicy policy = ConflictPolicy::Replace);
 
/**
 * Insert keywords
 *
 * Conflicting keywords are deleted from the current position.
 *
 * @param position Insert position that must lie within range (to_first, to_last]
 * @param to_first Start of range to consider when deleting duplicate keywords.
 * @param to_last  End of range to consider when deleting duplicate keywords.
 * @param from_first Range to insert from.
 * @param from_last Range to insert from.
 * @param from Keywords to update from.
 *
 * @ingroup daq_ocm_libfits
 */
void InsertKeywords(KeywordVector& keywords,
                    KeywordVector::iterator position,
                    KeywordVector::const_iterator from_first,
                    KeywordVector::const_iterator from_last);
 
/**
 * @name Format keyword using default formatting rules.
 *
 * @param keyword Keyword to format.
 * @throw std::invalid_argument on failure.
 */
/// @{
LiteralKeyword Format(KeywordVariant const& keyword);
LiteralKeyword Format(ValueKeyword const& keyword);
LiteralKeyword Format(EsoKeyword const& keyword);
LiteralKeyword Format(LiteralKeyword::Components const& keyword);
/// @}
 
/**
 * Indicates keyword is invalid for some reason.
 */
class InvalidKeyword : public std::invalid_argument {
public:
    InvalidKeyword(std::string_view name, char const* reason);
    InvalidKeyword(std::string_view name, std::string const& reason);
};
 
/**
 * Indicates keyword is unknown and cannot be formatted.
 */
class UnknownKeyword : public InvalidKeyword {
public:
    UnknownKeyword(std::string_view kw, std::vector<std::string> const& dictionaries);
};
 
/**
 * Formats keyword against e.g. dictionaries.
 */
class KeywordFormatter {
public:
    virtual ~KeywordFormatter() noexcept;
 
    /**
     * Formats keyword.
     *
     * @throws UnknownKeyword if @a keyword is not known.
     * @throws std::exception on other failures.
     */
    virtual auto Format(KeywordVariant const& keyword) const -> LiteralKeyword = 0;
};
 
/**
 * Formats according to built-in rules without any dictionaries.
 */
class StandardKeywordFormatter : public KeywordFormatter {
public:
    auto Format(KeywordVariant const& keyword) const -> LiteralKeyword override;
};
 
/**
 * Format keyword value using built-in rules such that it can be used as a component when formatting
 * a complete keyword record.
 *
 * @param name Keyword name, used to determine special handling of e.g. the `XTENSION` keyword.
 * @param value Value to format.
 * @return Formatted value. Strings are escaped.
 */
auto FormatFitsValue(KeywordNameView name, BasicKeywordBase::ValueType const& value) -> std::string;
 
/**
 * Untyped formatting where value already has been formatted *correctly*. No validation of value is
 * made.
 *
 * @param name Logical keyword name & type.
 * @param value formatted FITS keyword value.
 * @param comment Comment which may be empty.
 * @return formatted keyword record.
 */
auto UntypedFormat(KeywordNameView name, std::string_view value, std::string_view comment)
    -> LiteralKeyword;
 
/**
 * Versioned namespace of sorting functions in case standard evolves but instruments want to freeze.
 */
namespace v1 {
 
/**
 * Sorting function object
 *
 * @ingroup daq_ocm_libfits
 */
struct StandardLess {
    bool operator()(LiteralKeyword const&, LiteralKeyword const&) noexcept;
};
 
/**
 * Sorts keywords according to ESO DICD standards.
 *
 * Specifically the following sorting order is applied:
 *
 * 1. Value keywords
 *    note: value keywords are not sorted with other value keywords to keep their relative order
 *    from the source they originally come from.
 * 2. ESO keywords are sorted by
 *   1. category (DPR, OBS, TPL, GEN, TEL, ADA, INS, DET)
 *   2. keyword name
 * 3. Commentary keywords (using only the keyword name)
 *
 * @param[in, out] keywords Vector of keywords to sort.
 *
 * @ingroup daq_ocm_libfits
 */
void StandardSort(std::vector<LiteralKeyword>& keywords);
 
}  // namespace v1
}  // namespace daq::fits
 
#endif  // #ifndef DAQ_OCM_DAQ_KEYWORD_HPP_