io/structure_file/output.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: BSD-3-Clause
 
#pragma once
 
#include <cassert>
#include <filesystem>
#include <fstream>
#include <optional>
#include <ranges>
#include <string>
#include <type_traits>
#include <variant>
#include <vector>
 
#include <seqan3/io/detail/misc_output.hpp>
#include <seqan3/io/detail/out_file_iterator.hpp>
#include <seqan3/io/detail/record.hpp>
#include <seqan3/io/detail/record_like.hpp>
#include <seqan3/io/exception.hpp>
#include <seqan3/io/record.hpp>
#include <seqan3/io/stream/concept.hpp>
#include <seqan3/io/structure_file/format_vienna.hpp>
#include <seqan3/io/structure_file/output_format_concept.hpp>
#include <seqan3/io/structure_file/output_options.hpp>
#include <seqan3/utility/tuple/concept.hpp>
#include <seqan3/utility/type_list/traits.hpp>
#include <seqan3/utility/views/convert.hpp>
#include <seqan3/utility/views/elements.hpp>
#include <seqan3/utility/views/zip.hpp>
 
namespace seqan3
{
 
// ----------------------------------------------------------------------------
// structure_file_output
// ----------------------------------------------------------------------------
 
template <detail::fields_specialisation selected_field_ids_ = fields<field::seq, field::id, field::structure>,
          detail::type_list_of_structure_file_output_formats valid_formats_ = type_list<format_vienna>>
class structure_file_output
{
public:
    using selected_field_ids = selected_field_ids_;
    using valid_formats = valid_formats_;
    using stream_char_type = char;
 
    using field_ids = fields<field::seq,
                             field::id,
                             field::bpp,
                             field::structure,
                             field::structured_seq,
                             field::energy,
                             field::react,
                             field::react_err,
                             field::comment,
                             field::offset>;
 
    static_assert(
        []() constexpr
        {
            for (field f : selected_field_ids::as_array)
                if (!field_ids::contains(f))
                    return false;
            return true;
        }(),
        "You selected a field that is not valid for structure files, please refer to the documentation "
        "of structure_file_output::field_ids for the accepted values.");
 
    static_assert(
        []() constexpr
        {
            return !(selected_field_ids::contains(field::structured_seq)
                     && (selected_field_ids::contains(field::seq) || (selected_field_ids::contains(field::structure))));
        }(),
        "You may not select field::structured_seq and either of field::seq and field::structure "
        "at the same time.");
 
    using value_type = void;
    using reference = void;
    using const_reference = void;
    using size_type = void;
    using difference_type = std::ptrdiff_t;
    using iterator = detail::out_file_iterator<structure_file_output>;
    using const_iterator = void;
    using sentinel = std::default_sentinel_t;
 
    structure_file_output() = delete;
    structure_file_output(structure_file_output const &) = delete;
    structure_file_output & operator=(structure_file_output const &) = delete;
    structure_file_output(structure_file_output &&) = default;
    structure_file_output & operator=(structure_file_output &&) = default;
    ~structure_file_output() = default;
 
    structure_file_output(std::filesystem::path filename,
                          selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{}) :
        primary_stream{new std::ofstream{}, stream_deleter_default}
    {
        primary_stream->rdbuf()->pubsetbuf(stream_buffer.data(), stream_buffer.size());
        static_cast<std::basic_ofstream<char> *>(primary_stream.get())
            ->open(filename, std::ios_base::out | std::ios::binary);
 
        if (!primary_stream->good())
            throw file_open_error{"Could not open file " + filename.string() + " for writing."};
 
        // possibly add intermediate compression stream
        secondary_stream = detail::make_secondary_ostream(*primary_stream, filename);
 
        // initialise format handler or throw if format is not found
        detail::set_format(format, filename);
    }
    structure_file_output(std::filesystem::path filename, {…}
 
    template <output_stream stream_t, structure_file_output_format file_format>
        requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, char>
    structure_file_output(stream_t & stream,
                          file_format const & SEQAN3_DOXYGEN_ONLY(format_tag),
                          selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{}) :
        primary_stream{&stream, stream_deleter_noop},
        secondary_stream{&stream, stream_deleter_noop},
        format{detail::structure_file_output_format_exposer<file_format>{}}
    {
        static_assert(list_traits::contains<file_format, valid_formats>,
                      "You selected a format that is not in the valid_formats of this file.");
    }
    structure_file_output(stream_t & stream, {…}
 
    template <output_stream stream_t, structure_file_output_format file_format>
        requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, char>
    structure_file_output(stream_t && stream,
                          file_format const & SEQAN3_DOXYGEN_ONLY(format_tag),
                          selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{}) :
        primary_stream{new stream_t{std::move(stream)}, stream_deleter_default},
        secondary_stream{&*primary_stream, stream_deleter_noop},
        format{detail::structure_file_output_format_exposer<file_format>{}}
    {
        static_assert(list_traits::contains<file_format, valid_formats>,
                      "You selected a format that is not in the valid_formats of this file.");
    }
    structure_file_output(stream_t && stream, {…}
 
    iterator begin() noexcept
    {
        return {*this};
    }
    iterator begin() noexcept {…}
 
    sentinel end() noexcept
    {
        return {};
    }
    sentinel end() noexcept {…}
 
    template <typename record_t>
    void push_back(record_t && r)
        requires detail::record_like<record_t>
    {
        write_record(detail::get_or_ignore<field::seq>(r),
                     detail::get_or_ignore<field::id>(r),
                     detail::get_or_ignore<field::bpp>(r),
                     detail::get_or_ignore<field::structure>(r),
                     detail::get_or_ignore<field::structured_seq>(r),
                     detail::get_or_ignore<field::energy>(r),
                     detail::get_or_ignore<field::react>(r),
                     detail::get_or_ignore<field::react_err>(r),
                     detail::get_or_ignore<field::comment>(r),
                     detail::get_or_ignore<field::offset>(r));
    }
    void push_back(record_t && r) {…}
 
    template <typename tuple_t>
    void push_back(tuple_t && t)
        requires tuple_like<tuple_t> && (!detail::record_like<tuple_t>)
    {
        // index_of might return npos, but this will be handled well by get_or_ignore (and just return ignore)
        write_record(detail::get_or_ignore<selected_field_ids::index_of(field::seq)>(t),
                     detail::get_or_ignore<selected_field_ids::index_of(field::id)>(t),
                     detail::get_or_ignore<selected_field_ids::index_of(field::bpp)>(t),
                     detail::get_or_ignore<selected_field_ids::index_of(field::structure)>(t),
                     detail::get_or_ignore<selected_field_ids::index_of(field::structured_seq)>(t),
                     detail::get_or_ignore<selected_field_ids::index_of(field::energy)>(t),
                     detail::get_or_ignore<selected_field_ids::index_of(field::react)>(t),
                     detail::get_or_ignore<selected_field_ids::index_of(field::react_err)>(t),
                     detail::get_or_ignore<selected_field_ids::index_of(field::comment)>(t),
                     detail::get_or_ignore<selected_field_ids::index_of(field::offset)>(t));
    }
    void push_back(tuple_t && t) {…}
 
    template <typename arg_t, typename... arg_types>
    void emplace_back(arg_t && arg, arg_types &&... args)
    {
        push_back(std::tie(arg, args...));
    }
    void emplace_back(arg_t && arg, arg_types &&... args) {…}
 
    template <std::ranges::input_range rng_t>
    structure_file_output & operator=(rng_t && range)
        requires tuple_like<std::ranges::range_reference_t<rng_t>>
    {
        for (auto && record : range)
            push_back(std::forward<decltype(record)>(record));
        return *this;
    }
    structure_file_output & operator=(rng_t && range) {…}
 
    template <std::ranges::input_range rng_t>
    friend structure_file_output & operator|(rng_t && range, structure_file_output & f)
        requires tuple_like<std::ranges::range_reference_t<rng_t>>
    {
        f = range;
        return f;
    }
    friend structure_file_output & operator|(rng_t && range, structure_file_output & f) {…};
 
    template <std::ranges::input_range rng_t>
    friend structure_file_output operator|(rng_t && range, structure_file_output && f)
        requires tuple_like<std::ranges::range_reference_t<rng_t>>
    {
        f = range;
        return std::move(f);
    }
    friend structure_file_output operator|(rng_t && range, structure_file_output && f) {…};
 
    structure_file_output_options options;
 
    std::basic_ostream<stream_char_type> & get_stream()
    {
        return *secondary_stream;
    }
 
protected:
    std::vector<char> stream_buffer{std::vector<char>(1'000'000)};
 
    using stream_ptr_t = std::unique_ptr<std::basic_ostream<stream_char_type>,
                                         std::function<void(std::basic_ostream<stream_char_type> *)>>;
    static void stream_deleter_noop(std::basic_ostream<stream_char_type> *)
    {}
    static void stream_deleter_default(std::basic_ostream<stream_char_type> * ptr)
    {
        delete ptr;
    }
 
    stream_ptr_t primary_stream{nullptr, stream_deleter_noop};
    stream_ptr_t secondary_stream{nullptr, stream_deleter_noop};
 
    using format_type =
        typename detail::variant_from_tags<valid_formats, detail::structure_file_output_format_exposer>::type;
    format_type format;
 
    template <typename seq_type,
              typename id_type,
              typename bpp_type,
              typename structure_type,
              typename structured_seq_type,
              typename energy_type,
              typename react_type,
              typename comment_type,
              typename offset_type>
    void write_record(seq_type && seq,
                      id_type && id,
                      bpp_type && bpp,
                      structure_type && structure,
                      structured_seq_type && structured_seq,
                      energy_type && energy,
                      react_type && react,
                      react_type && react_error,
                      comment_type && comment,
                      offset_type && offset)
    {
        static_assert(detail::decays_to_ignore_v<structured_seq_type>
                          || (detail::decays_to_ignore_v<seq_type> && detail::decays_to_ignore_v<structure_type>),
                      "You may not select field::structured_seq and either of field::seq and field::structure "
                      "at the same time.");
 
        assert(!format.valueless_by_exception());
        std::visit(
            [&](auto & f)
            {
                if constexpr (!detail::decays_to_ignore_v<structured_seq_type>)
                {
                    f.write_structure_record(*secondary_stream,
                                             options,
                                             structured_seq | views::elements<0>,
                                             id,
                                             bpp,
                                             structured_seq | views::elements<1>,
                                             energy,
                                             react,
                                             react_error,
                                             comment,
                                             offset);
                }
                else
                {
                    f.write_structure_record(*secondary_stream,
                                             options,
                                             seq,
                                             id,
                                             bpp,
                                             structure,
                                             energy,
                                             react,
                                             react_error,
                                             comment,
                                             offset);
                }
            },
            format);
    }
 
    friend iterator;
};
class structure_file_output {…};
 
template <output_stream stream_t,
          structure_file_output_format file_format,
          detail::fields_specialisation selected_field_ids>
structure_file_output(stream_t &&,
                      file_format const &,
                      selected_field_ids const &) -> structure_file_output<selected_field_ids, type_list<file_format>>;
 
template <output_stream stream_t,
          structure_file_output_format file_format,
          detail::fields_specialisation selected_field_ids>
structure_file_output(stream_t &,
                      file_format const &,
                      selected_field_ids const &) -> structure_file_output<selected_field_ids, type_list<file_format>>;
 
} // namespace seqan3