io/sequence_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 <ranges>
#include <string>
#include <variant>
#include <vector>
 
#include <seqan3/io/detail/misc.hpp>
#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/sam_file/format_sam.hpp>
#include <seqan3/io/sequence_file/format_embl.hpp>
#include <seqan3/io/sequence_file/format_fasta.hpp>
#include <seqan3/io/sequence_file/format_fastq.hpp>
#include <seqan3/io/sequence_file/format_genbank.hpp>
#include <seqan3/io/sequence_file/output_format_concept.hpp>
#include <seqan3/io/sequence_file/output_options.hpp>
#include <seqan3/io/stream/concept.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
{
 
// ----------------------------------------------------------------------------
// sequence_file_output
// ----------------------------------------------------------------------------
 
template <detail::fields_specialisation selected_field_ids_ = fields<field::seq, field::id, field::qual>,
          detail::type_list_of_sequence_file_output_formats valid_formats_ =
              type_list<format_embl, format_fasta, format_fastq, format_genbank, format_sam>>
class sequence_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::qual>;
 
    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 sequence files, please refer to the documentation "
        "of sequence_file_output::field_ids for the accepted values.");
 
    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<sequence_file_output>;
    using const_iterator = void;
    using sentinel = std::default_sentinel_t;
 
    sequence_file_output() = delete;
    sequence_file_output(sequence_file_output const &) = delete;
    sequence_file_output & operator=(sequence_file_output const &) = delete;
    sequence_file_output(sequence_file_output &&) = default;
    sequence_file_output & operator=(sequence_file_output &&) = default;
    ~sequence_file_output() = default;
 
    sequence_file_output(std::filesystem::path filename,
                         selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{},
                         std::ios_base::openmode openmode = std::ios_base::out | std::ios::binary) :
        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, openmode | 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);
    }
 
    template <output_stream stream_t, sequence_file_output_format file_format>
        requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, stream_char_type>
    sequence_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::sequence_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.");
    }
 
    template <output_stream stream_t, sequence_file_output_format file_format>
        requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, stream_char_type>
    sequence_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::sequence_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.");
    }
 
    iterator begin() noexcept
    {
        return {*this};
    }
 
    sentinel end() noexcept
    {
        return {};
    }
 
    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::qual>(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::qual)>(t));
    }
 
    template <typename arg_t, typename... arg_types>
    void emplace_back(arg_t && arg, arg_types &&... args)
    {
        push_back(std::tie(arg, args...));
    }
 
    template <std::ranges::input_range rng_t>
    sequence_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;
    }
 
    template <std::ranges::input_range rng_t>
    friend sequence_file_output & operator|(rng_t && range, sequence_file_output & f)
        requires tuple_like<std::ranges::range_reference_t<rng_t>>
    {
        f = range;
        return f;
    }
 
    template <std::ranges::input_range rng_t>
    friend sequence_file_output operator|(rng_t && range, sequence_file_output && f)
        requires tuple_like<std::ranges::range_reference_t<rng_t>>
    {
        f = range;
        return std::move(f);
    }
 
    sequence_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::sequence_file_output_format_exposer>::type;
    format_type format;
 
    template <typename seq_t, typename id_t, typename qual_t>
    void write_record(seq_t && seq, id_t && id, qual_t && qual)
    {
        assert(!format.valueless_by_exception());
        std::visit(
            [&](auto & f)
            {
                {
                    f.write_sequence_record(*secondary_stream, options, seq, id, qual);
                }
            },
            format);
    }
 
    friend iterator;
};
 
template <output_stream stream_t, sequence_file_output_format file_format>
sequence_file_output(stream_t &,
                     file_format const &)
    -> sequence_file_output<typename sequence_file_output<>::selected_field_ids, // default field ids
                            type_list<file_format>>;
 
template <output_stream stream_t, sequence_file_output_format file_format>
sequence_file_output(stream_t &&,
                     file_format const &)
    -> sequence_file_output<typename sequence_file_output<>::selected_field_ids, // default field ids.
                            type_list<file_format>>;
 
template <output_stream stream_t,
          sequence_file_output_format file_format,
          detail::fields_specialisation selected_field_ids>
sequence_file_output(stream_t &&,
                     file_format const &,
                     selected_field_ids const &) -> sequence_file_output<selected_field_ids, type_list<file_format>>;
 
template <output_stream stream_t,
          sequence_file_output_format file_format,
          detail::fields_specialisation selected_field_ids>
sequence_file_output(stream_t &,
                     file_format const &,
                     selected_field_ids const &) -> sequence_file_output<selected_field_ids, type_list<file_format>>;
} // namespace seqan3