[DOC] Add documentation

include/seqan3/io/sam_file/detail/format_sam_base.hpp

@@ -260,6 +260,7 @@ inline void format_sam_base::read_arithmetic_field(std::string_view const & str,
  * \tparam stream_view_type     The type of the stream as a view.
  * \param[in, out] stream_view  The stream view to iterate over.
  * \param[in, out] hdr          The header (as a pointer) to store the parsed values.
+ * \param[in] options           The options to alter the parsing process.
  *
  * \throws seqan3::format_error if any unexpected character or format is encountered.
  *

include/seqan3/io/sam_file/format_bam.hpp

@@ -83,7 +83,7 @@ class format_bam : private detail::format_sam_base
               typename e_value_type,
               typename bit_score_type>
     void read_alignment_record(stream_type & stream,
-                               sam_file_input_options<seq_legal_alph_type> const & SEQAN3_DOXYGEN_ONLY(options),
+                               sam_file_input_options<seq_legal_alph_type> const & options,
                                ref_seqs_type & ref_seqs,
                                sam_file_header<ref_ids_type> & header,
                                stream_pos_type & position_buffer,

include/seqan3/io/sam_file/format_sam.hpp

@@ -165,7 +165,7 @@ class format_sam : protected detail::format_sam_base
               typename e_value_type,
               typename bit_score_type>
     void read_alignment_record(stream_type & stream,
-                               sam_file_input_options<seq_legal_alph_type> const & SEQAN3_DOXYGEN_ONLY(options),
+                               sam_file_input_options<seq_legal_alph_type> const & options,
                                ref_seqs_type & ref_seqs,
                                sam_file_header<ref_ids_type> & header,
                                stream_pos_type & position_buffer,

test/snippet/io/sam_file/sam_file_input_options.cpp

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
+// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
+// SPDX-License-Identifier: CC0-1.0
+
+#include <sstream>
+
+#include <seqan3/io/sam_file/input.hpp>
+
+// A helper struct to create a temporary file and remove it when it goes out of scope.
+struct temporary_file
+{
+    std::filesystem::path const path{std::filesystem::temp_directory_path() / "warnings.txt"};
+
+    temporary_file()
+    {
+        std::ofstream file{path}; // Create file
+    }
+    temporary_file(temporary_file const &) = delete;
+    temporary_file & operator=(temporary_file const &) = delete;
+    temporary_file(temporary_file &&) = delete;
+    temporary_file & operator=(temporary_file &&) = delete;
+    ~temporary_file()
+    {
+        std::filesystem::remove(path);
+    }
+
+    std::string read_content() const
+    {
+        std::ifstream file{path};
+        return std::string{std::istreambuf_iterator<char>{file}, std::istreambuf_iterator<char>{}};
+    }
+};
+
+static constexpr auto sam_file_raw = R"(@HD	VN:1.6	pb:5.0.0
+@SQ	SN:ref	LN:34
+)";
+
+static auto get_sam_file_input()
+{
+    return seqan3::sam_file_input{std::istringstream{sam_file_raw}, seqan3::format_sam{}};
+}
+
+void defaults_to_cerr()
+{
+    auto fin = get_sam_file_input();
+    std::cerr << "Written to cerr: ";
+    auto it = fin.begin(); // Prints to cerr: "Unsupported SAM header tag in @HD: pb"
+}
+
+void redirect_to_cout()
+{
+    auto fin = get_sam_file_input();
+    fin.options.stream_warnings_to = std::addressof(std::cout); // Equivalent to `= &std::cout;`
+    std::cout << "Written to cout: ";
+    auto it = fin.begin(); // Prints to cout: "Unsupported SAM header tag in @HD: pb"
+}
+
+void redirect_to_file()
+{
+    temporary_file tmp_file{};
+    auto fin = get_sam_file_input();
+
+    { // Inner scope to close file before reading
+        std::ofstream warning_file{tmp_file.path};
+        fin.options.stream_warnings_to = std::addressof(warning_file); // Equivalent to `= &warning_file;`
+        auto it = fin.begin(); // Prints to file: "Unsupported SAM header tag in @HD: pb"
+    }
+
+    std::cout << "Written to file: " << tmp_file.read_content();
+}
+
+void silence_warnings()
+{
+    auto fin = get_sam_file_input();
+    fin.options.stream_warnings_to = nullptr;
+    auto it = fin.begin(); // No warning emitted
+}
+
+int main()
+{
+    defaults_to_cerr();
+    redirect_to_cout();
+    redirect_to_file();
+    silence_warnings();
+}

test/snippet/io/sam_file/sam_file_input_options.err

@@ -0,0 +1 @@
+Written to cerr: Unsupported SAM header tag in @HD: pb

test/snippet/io/sam_file/sam_file_input_options.err.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
+SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
+SPDX-License-Identifier: CC0-1.0

test/snippet/io/sam_file/sam_file_input_options.out

@@ -0,0 +1,2 @@
+Written to cout: Unsupported SAM header tag in @HD: pb
+Written to file: Unsupported SAM header tag in @HD: pb

test/snippet/io/sam_file/sam_file_input_options.out.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
+SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
+SPDX-License-Identifier: CC0-1.0