Attributable.hpp

/* Copyright 2017-2021 Fabian Koller
 *
 * This file is part of openPMD-api.
 *
 * openPMD-api is free software: you can redistribute it and/or modify
 * it under the terms of of either the GNU General Public License or
 * the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * openPMD-api is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License and the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * and the GNU Lesser General Public License along with openPMD-api.
 * If not, see <http://www.gnu.org/licenses/>.
 */
#pragma once
 
#include "openPMD/IO/AbstractIOHandler.hpp"
#include "openPMD/backend/Attribute.hpp"
#include "openPMD/backend/Writable.hpp"
#include "openPMD/auxiliary/OutOfRangeMsg.hpp"
 
#include <exception>
#include <map>
#include <memory>
#include <vector>
#include <string>
#include <cstddef>
#include <type_traits>
 
// expose private and protected members for invasive testing
#ifndef OPENPMD_protected
#   define OPENPMD_protected protected
#endif
 
 
namespace openPMD
{
namespace traits
{
    template< typename T >
    struct GenerationPolicy;
} // traits
class AbstractFilePosition;
class AttributableInterface;
class Iteration;
namespace internal
{
    class SeriesInternal;
}
 
class no_such_attribute_error : public std::runtime_error
{
public:
    no_such_attribute_error(std::string const& what_arg)
            : std::runtime_error(what_arg)
    { }
    virtual ~no_such_attribute_error() { }
};
 
namespace internal
{
class AttributableData
{
    friend class openPMD::AttributableInterface;
 
public:
    AttributableData();
    AttributableData( AttributableData const & ) = delete;
    AttributableData( AttributableData && ) = delete;
    virtual ~AttributableData() = default;
 
    AttributableData & operator=( AttributableData const & ) = delete;
    AttributableData & operator=( AttributableData && ) = delete;
 
    using A_MAP = std::map< std::string, Attribute >;
    Writable m_writable;
 
private:
    A_MAP m_attributes;
};
 
template< typename T >
inline void
attr_value_check( std::string const /* key */, T /* value */ )
{
}
 
template< >
inline void
attr_value_check( std::string const key, std::string const value )
{
    if( value.empty() )
        throw std::runtime_error(
                "[setAttribute] Value for string attribute '" + key +
                "' must not be empty!" );
}
 
} // namespace internal
 
class AttributableInterface
{
    // @todo remove unnecessary friend (wew that sounds bitter)
    using A_MAP = std::map< std::string, Attribute >;
    friend Writable* getWritable(AttributableInterface*);
    template< typename T_elem >
    friend class BaseRecord;
    template<
        typename T,
        typename T_key,
        typename T_container
    >
    friend class Container;
    template< typename T >
    friend struct traits::GenerationPolicy;
    friend class Iteration;
    friend class Series;
    friend class SeriesInterface;
    friend class Writable;
    friend class WriteIterations;
 
protected:
    internal::AttributableData * m_attri = nullptr;
 
    // Should not be called publicly, only by implementing classes
    AttributableInterface( internal::AttributableData * );
    template< typename T >
    AttributableInterface( T * attri )
        : AttributableInterface{
              static_cast< internal::AttributableData * >( attri ) }
    {
    }
 
public:
    virtual ~AttributableInterface() = default;
 
    template< typename T >
    bool setAttribute(std::string const& key, T value);
    bool setAttribute(std::string const& key, char const value[]);
    Attribute getAttribute(std::string const& key) const;
 
    bool deleteAttribute(std::string const& key);
 
    std::vector< std::string > attributes() const;
    size_t numAttributes() const;
    bool containsAttribute(std::string const& key) const;
 
    std::string comment() const;
    AttributableInterface& setComment(std::string const& comment);
 
    void seriesFlush();
 
    struct MyPath
    {
        std::string directory;       
        std::string seriesName;      
        std::string seriesExtension; 
 
        std::vector< std::string > group;
 
        std::string filePath() const;
    };
 
    MyPath myPath() const;
 
OPENPMD_protected:
 
    internal::SeriesInternal const & retrieveSeries() const;
    internal::SeriesInternal & retrieveSeries();
 
    Iteration const & containingIteration() const;
    Iteration & containingIteration();
    void seriesFlush( FlushLevel );
 
    void flushAttributes();
    enum ReadMode {
        IgnoreExisting,
        OverrideExisting,
        FullyReread
    };
    void readAttributes( ReadMode );
 
    template< typename T >
    T readFloatingpoint(std::string const& key) const;
    template< typename T >
    std::vector< T > readVectorFloatingpoint(std::string const& key) const;
 
    /* views into the resources held by m_writable
     * purely for convenience so code that uses these does not have to go through m_writable-> */
    AbstractIOHandler * IOHandler()
    {
        return m_attri->m_writable.IOHandler.get();
    }
    AbstractIOHandler const * IOHandler() const
    {
        return m_attri->m_writable.IOHandler.get();
    }
    Writable *& parent()
    {
        return m_attri->m_writable.parent;
    }
    Writable const * parent() const
    {
        return m_attri->m_writable.parent;
    }
    Writable & writable()
    {
        return m_attri->m_writable;
    }
    Writable const & writable() const
    {
        return m_attri->m_writable;
    }
 
    inline
    internal::AttributableData & get()
    {
        if( m_attri )
        {
            return *m_attri;
        }
        else
        {
            throw std::runtime_error(
                "[AttributableInterface] "
                "Cannot use default-constructed Attributable." );
        }
    }
    inline
    internal::AttributableData const & get() const
    {
        if( m_attri )
        {
            return *m_attri;
        }
        else
        {
            throw std::runtime_error(
                "[AttributableInterface] "
                "Cannot use default-constructed Attributable." );
        }
    }
 
    bool dirty() const { return writable().dirty; }
    bool& dirty() { return writable().dirty; }
    bool written() const { return writable().written; }
    bool& written() { return writable().written; }
 
private:
    virtual void linkHierarchy(Writable& w);
}; // AttributableInterface
 
// Alias this as Attributable since this is a public abstract parent class
// for most of the classes in our object model of the openPMD hierarchy
using Attributable = AttributableInterface;
 
class LegacyAttributable : public AttributableInterface
{
protected:
    std::shared_ptr< internal::AttributableData > m_attributableData =
        std::make_shared< internal::AttributableData >();
 
public:
    LegacyAttributable() : AttributableInterface{ nullptr }
    {
        AttributableInterface::m_attri = m_attributableData.get();
    }
};
 
//TODO explicitly instantiate Attributable::setAttribute for all T in Datatype
template< typename T >
inline bool
AttributableInterface::setAttribute( std::string const & key, T value )
{
    internal::attr_value_check( key, value );
 
    auto & attri = get();
    if(IOHandler() && Access::READ_ONLY == IOHandler()->m_frontendAccess )
    {
        auxiliary::OutOfRangeMsg const out_of_range_msg(
            "Attribute",
            "can not be set (read-only)."
        );
        throw no_such_attribute_error(out_of_range_msg(key));
    }
 
    dirty() = true;
    auto it = attri.m_attributes.lower_bound(key);
    if( it != attri.m_attributes.end()
        && !attri.m_attributes.key_comp()(key, it->first) )
    {
        // key already exists in map, just replace the value
        it->second = Attribute(value);
        return true;
    } else
    {
        // emplace a new map element for an unknown key
        attri.m_attributes.emplace_hint(
            it, std::make_pair(key, Attribute(std::move(value))));
        return false;
    }
}
 
inline bool
AttributableInterface::setAttribute( std::string const & key, char const value[] )
{
    return this->setAttribute(key, std::string(value));
}
 
template< typename T >
inline T AttributableInterface::readFloatingpoint( std::string const & key ) const
{
    static_assert(std::is_floating_point< T >::value, "Type of attribute must be floating point");
 
    return getAttribute(key).get< T >();
}
 
template< typename T >
inline std::vector< T >
AttributableInterface::readVectorFloatingpoint( std::string const & key ) const
{
    static_assert(std::is_floating_point< T >::value, "Type of attribute must be floating point");
 
    return getAttribute(key).get< std::vector< T > >();
}
} // namespace openPMD