[FEATURE] Use enum output_file_open_mode to handle overwriting perm…

…ission

Signed-off-by: Lydia Buntrock <[email protected]>

doc/tutorial/read_mapper/read_mapper_indexer_step1.cpp

@@ -24,7 +24,7 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
                       seqan3::input_file_validator{{"fa","fasta"}});
     parser.add_option(args.index_path, 'o', "output", "The output index file path.",
                       seqan3::option_spec::DEFAULT,
-                      seqan3::output_file_validator{{"index"}});
+                      seqan3::output_file_validator{seqan3::output_file_open_mode::exclusive, {"index"}});
 }
 
 //![main]

doc/tutorial/read_mapper/read_mapper_indexer_step2.cpp

@@ -51,7 +51,7 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
                       seqan3::input_file_validator{{"fa","fasta"}});
     parser.add_option(args.index_path, 'o', "output", "The output index file path.",
                       seqan3::option_spec::DEFAULT,
-                      seqan3::output_file_validator{{"index"}});
+                      seqan3::output_file_validator{seqan3::output_file_open_mode::exclusive, {"index"}});
 }
 
 int main(int argc, char const ** argv)

doc/tutorial/read_mapper/read_mapper_indexer_step3.cpp

@@ -66,7 +66,7 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
                       seqan3::input_file_validator{{"fa","fasta"}});
     parser.add_option(args.index_path, 'o', "output", "The output index file path.",
                       seqan3::option_spec::DEFAULT,
-                      seqan3::output_file_validator{{"index"}});
+                      seqan3::output_file_validator{seqan3::output_file_open_mode::exclusive, {"index"}});
 }
 
 int main(int argc, char const ** argv)

doc/tutorial/read_mapper/read_mapper_step1.cpp

@@ -39,7 +39,7 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
                       seqan3::input_file_validator{{"index"}});
     parser.add_option(args.sam_path, 'o', "output", "The output SAM file path.",
                       seqan3::option_spec::DEFAULT,
-                      seqan3::output_file_validator{{"sam"}});
+                      seqan3::output_file_validator{seqan3::output_file_open_mode::exclusive, {"sam"}});
     parser.add_option(args.errors, 'e', "error", "Maximum allowed errors.",
                       seqan3::option_spec::DEFAULT,
                       seqan3::arithmetic_range_validator{0, 4});

doc/tutorial/read_mapper/read_mapper_step2.cpp

@@ -103,7 +103,7 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
                       seqan3::input_file_validator{{"index"}});
     parser.add_option(args.sam_path, 'o', "output", "The output SAM file path.",
                       seqan3::option_spec::DEFAULT,
-                      seqan3::output_file_validator{{"sam"}});
+                      seqan3::output_file_validator{seqan3::output_file_open_mode::exclusive, {"sam"}});
     parser.add_option(args.errors, 'e', "error", "Maximum allowed errors.",
                       seqan3::option_spec::DEFAULT,
                       seqan3::arithmetic_range_validator{0, 4});

doc/tutorial/read_mapper/read_mapper_step3.cpp

@@ -122,7 +122,7 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
                       seqan3::input_file_validator{{"index"}});
     parser.add_option(args.sam_path, 'o', "output", "The output SAM file path.",
                       seqan3::option_spec::DEFAULT,
-                      seqan3::output_file_validator{{"sam"}});
+                      seqan3::output_file_validator{seqan3::output_file_open_mode::exclusive, {"sam"}});
     parser.add_option(args.errors, 'e', "error", "Maximum allowed errors.",
                       seqan3::option_spec::DEFAULT,
                       seqan3::arithmetic_range_validator{0, 4});

doc/tutorial/read_mapper/read_mapper_step4.cpp

@@ -130,7 +130,7 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
                       seqan3::input_file_validator{{"index"}});
     parser.add_option(args.sam_path, 'o', "output", "The output SAM file path.",
                       seqan3::option_spec::DEFAULT,
-                      seqan3::output_file_validator{{"sam"}});
+                      seqan3::output_file_validator{seqan3::output_file_open_mode::exclusive, {"sam"}});
     parser.add_option(args.errors, 'e', "error", "Maximum allowed errors.",
                       seqan3::option_spec::DEFAULT,
                       seqan3::arithmetic_range_validator{0, 4});

include/seqan3/argument_parser/validators.hpp

@@ -574,6 +574,15 @@ class input_file_validator : public file_validator_base
     }
 };
 
+//!\brief Stores, if it is valid to overwrite the output file.
+enum output_file_open_mode
+{
+    //!\brief Allow to overwrite the output file
+    overwritable,
+    //!\brief Forbid overwriting the output file
+    exclusive
+};
+
 /*!\brief A validator that checks if a given path is a valid output file.
  * \ingroup argument_parser
  * \implements seqan3::validator
@@ -600,76 +609,60 @@ class input_file_validator : public file_validator_base
 template <typename file_t = void>
 class output_file_validator : public file_validator_base
 {
-public:
-    //!\brief Stores, if it is valid to overwrite the output file.
-    bool allow_overwrite = false; // ToDo: bool oder enum? Für jedes File einzeln entscheiden, also zum Pfad dazugeben? Oder als Vektor angeben?
+private:
+    //!\brief Stores the current mode, if it is valid to overwrite the output file.
+    output_file_open_mode mode;
 
+public:
     static_assert(std::same_as<file_t, void> || detail::has_type_valid_formats<file_t>,
                 "Expected either a template type with a static member called valid_formats (a file type) or void.");
 
-    // Wenn enum, dann: ?
-    // static_assert(std::same_as<allow_overwrite, void> || detail::has_type_valid_formats<file_t>,
-    //             "Wenn gesetzt, prüfe ob file existiert.");
-
     // Import from base class.
     using typename file_validator_base::option_value_type;
 
     /*!\name Constructors, destructor and assignment
      * \{
      */
 
-    //!\copydoc seqan3::input_file_validator::input_file_validator()
-    output_file_validator()
+    output_file_validator() = delete; //!< Deleted.
+    output_file_validator(output_file_validator const &) = default; //!< Defaulted.
+    output_file_validator(output_file_validator &&) = default; //!< Defaulted.
+    output_file_validator & operator=(output_file_validator const &) = default; //!< Defaulted.
+    output_file_validator & operator=(output_file_validator &&) = default; //!< Defaulted.
+    virtual ~output_file_validator() = default; //!< Virtual Destructor.
+
+    /*!\brief Constructs from a given collection of valid extensions.
+     * \param[in] mode Sets a flag, if it is valid to overwrite the output file.
+     *
+     * \details
+     *
+     * This constructor is only available if `file_t` does not name a valid seqan3 file type that contains a
+     * static member `valid_formats`.
+     */
+    explicit output_file_validator(output_file_open_mode const mode) : file_validator_base{}, mode{mode}
     {
         if constexpr (!std::same_as<file_t, void>)
             file_validator_base::extensions = detail::valid_file_extensions<typename file_t::valid_formats>();
     }
 
-    output_file_validator(output_file_validator const &) = default;               //!< Defaulted.
-    output_file_validator(output_file_validator &&) = default;                    //!< Defaulted.
-    output_file_validator & operator=(output_file_validator const &) = default;   //!< Defaulted.
-    output_file_validator & operator=(output_file_validator &&) = default;        //!< Defaulted.
-    virtual ~output_file_validator() = default;                                   //!< Virtual Destructor.
-
-    //!\copydoc seqan3::input_file_validator::input_file_validator(std::vector<std::string>)
-    explicit output_file_validator(std::vector<std::string> extensions)
-    //!\cond
-        requires std::same_as<file_t, void>
-    //!\endcond
-        : file_validator_base{}
-    {
-        file_validator_base::extensions = std::move(extensions);
-    }
-
     /*!\brief Constructs from a given collection of valid extensions.
      * \param[in] extensions The valid extensions to validate for.
-     * \param[in] allow_overwrite Sets a flag, if it is valid to overwrite the output file.
+     * \param[in] mode Sets a flag, if it is valid to overwrite the output file.
      *
      * \details
      *
      * This constructor is only available if `file_t` does not name a valid seqan3 file type that contains a
      * static member `valid_formats`.
      */
-    explicit output_file_validator(std::vector<std::string> extensions, bool allow_overwrite)
+    explicit output_file_validator(output_file_open_mode const mode, std::vector<std::string> extensions)
     //!\cond
         requires std::same_as<file_t, void>
     //!\endcond
-        : file_validator_base{}, allow_overwrite{allow_overwrite}
+        : file_validator_base{}, mode{mode}
     {
         file_validator_base::extensions = std::move(extensions);
     }
 
-    /*!\brief Constructs from a given collection of valid extensions.
-     * \param[in] allow_overwrite Sets a flag, if it is valid to overwrite the output file.
-     *
-     * \details
-     *
-     * This constructor is only available if `file_t` does not name a valid seqan3 file type that contains a
-     * static member `valid_formats`.
-     */    explicit output_file_validator(bool allow_overwrite) : file_validator_base{}, allow_overwrite{allow_overwrite}
-    {}
-
-
     // Import base constructor.
     using file_validator_base::file_validator_base;
     //!\}
@@ -686,7 +679,7 @@ class output_file_validator : public file_validator_base
     {
         try
         {
-            if (!allow_overwrite && std::filesystem::exists(file))
+            if ((mode == exclusive) && std::filesystem::exists(file))
                 throw validation_error{detail::to_string("The file ", file, " already exists!")};
 
             // Check if file has any write permissions.
@@ -707,9 +700,9 @@ class output_file_validator : public file_validator_base
     //!\brief Returns a message that can be appended to the (positional) options help page info.
     std::string get_help_page_message() const
     {
-        if (allow_overwrite)
+        if (mode == overwritable)
             return "Write permissions must be granted." + valid_extensions_help_page_message();
-        else
+        else // mode == exclusive
             return "The output file must not exist already and write permissions must be granted." +
                    valid_extensions_help_page_message();
     }

test/snippet/argument_parser/validators_output_directory.cpp

@@ -10,7 +10,8 @@ int main(int argc, const char ** argv)
     std::filesystem::path mydir{};
 
     myparser.add_option(mydir, 'd', "dir", "The output directory for storing the files.",
-                        seqan3::option_spec::DEFAULT, seqan3::output_directory_validator{});
+                        seqan3::option_spec::DEFAULT,
+                        seqan3::output_file_validator{seqan3::output_file_open_mode::exclusive});
     //! [validator_call]
 
     // an exception will be thrown if the user specifies a directory that cannot be created by the filesystem either

test/snippet/argument_parser/validators_output_file.cpp

@@ -9,10 +9,12 @@ int main(int argc, const char ** argv)
     //! [validator_call]
     std::filesystem::path myfile{};
 
+                        // Add the output_file_open_mode, to allow overwriting existing files, or to avoid this.
     myparser.add_option(myfile,'f',"file","Output file containing the processed sequences.",
-                        seqan3::option_spec::DEFAULT, seqan3::output_file_validator{{"fa","fasta"}});
-                        // Add an additional `true`, to allow overwriting existing files.
-                        // seqan3::option_spec::DEFAULT, seqan3::output_file_validator{{"fa","fasta"}, true});
+                        seqan3::option_spec::DEFAULT,
+                        seqan3::output_file_validator{seqan3::output_file_open_mode::overwritable, {"fa","fasta"}});
+                        // or
+                        // seqan3::output_file_validator{seqan3::output_file_open_mode::exclusive, {"fa","fasta"}});
     //! [validator_call]
 
     // an exception will be thrown if the user specifies a filename

test/snippet/argument_parser/validators_output_file_ext_from_file.cpp

@@ -5,15 +5,16 @@
 int main(int argc, const char ** argv)
 {
     // Default constructed validator has an empty extension list.
-    seqan3::output_file_validator validator1{};
+    seqan3::output_file_validator validator1{seqan3::output_file_open_mode::exclusive};
     seqan3::debug_stream << validator1.get_help_page_message() << "\n";
 
     // Specify your own extensions for the output file.
-    seqan3::output_file_validator validator2{std::vector{std::string{"exe"}, std::string{"fasta"}}};
+    seqan3::output_file_validator validator2{seqan3::output_file_open_mode::exclusive,
+                                             std::vector{std::string{"exe"}, std::string{"fasta"}}};
     seqan3::debug_stream << validator2.get_help_page_message() << "\n";
 
     // Give the seqan3 file type as a template argument to get all valid extensions for this file.
-    seqan3::output_file_validator<seqan3::sequence_file_output<>> validator3{};
+    seqan3::output_file_validator<seqan3::sequence_file_output<>> validator3{seqan3::output_file_open_mode::exclusive};
     seqan3::debug_stream << validator3.get_help_page_message() << "\n";
 
     return 0;