Merge pull request #280 from eseiler/feat/multi_cite

[FEATURE] Handle multiple citations

Author: eseiler

include/sharg/auxiliary.hpp

@@ -28,6 +28,45 @@ enum class update_notifications : uint8_t
     off //!< Automatic update notifications should be disabled.
 };
 
+/*!\brief A `std::vector<std::string>` that can also be constructed from `std::string`.
+ * \ingroup misc
+ * \details
+ * \experimentalapi{Experimental since version 1.2.0.}
+ */
+class vector_of_string : public std::vector<std::string>
+{
+private:
+    //!\brief The base type.
+    using base_t = std::vector<std::string>;
+
+public:
+    using base_t::base_t;
+
+    vector_of_string() = default;                                     //!< Defaulted.
+    vector_of_string(vector_of_string const &) = default;             //!< Defaulted.
+    vector_of_string & operator=(vector_of_string const &) = default; //!< Defaulted.
+    vector_of_string(vector_of_string &&) = default;                  //!< Defaulted.
+    vector_of_string & operator=(vector_of_string &&) = default;      //!< Defaulted.
+    ~vector_of_string() = default;                                    //!< Defaulted.
+
+    //!\brief Delegate to `std::string` constructor if possible.
+    template <typename... t>
+        requires std::constructible_from<std::string, t...>
+    constexpr vector_of_string(t &&... str) : base_t{std::string(std::forward<t>(str)...)}
+    {}
+
+    //!\brief Construct from iterator pair.
+    template <typename Iter>
+        requires std::constructible_from<std::string, Iter, Iter>
+              && std::same_as<std::decay_t<Iter>, std::string::value_type *>
+    constexpr vector_of_string(Iter begin, Iter end) : base_t{std::string(begin, end)}
+    {}
+
+    //!\brief Construct from an initializer list.
+    constexpr vector_of_string(std::initializer_list<std::string::value_type> il) : base_t{{il}}
+    {}
+};
+
 /*!\brief Stores all parser related meta information of the sharg::parser.
  * \ingroup parser
  * \details
@@ -78,8 +117,8 @@ struct parser_meta_data // holds all meta information
      */
     std::string long_copyright;
 
-    //!\brief How  users shall cite your application.
-    std::string citation;
+    //!\brief How users shall cite your application.
+    vector_of_string citation;
 
     /*!\brief The title of your man page when exported by specifying
      *        "--export-help man" on the common line.

include/sharg/detail/format_base.hpp

@@ -595,8 +595,17 @@ class format_help_base : public format_base
 
             if (!empty(meta.citation))
             {
-                derived_t().print_line(derived_t().in_bold("In your academic works please cite: ") + meta.citation,
-                                       false);
+                derived_t().print_line(derived_t().in_bold("In your academic works please cite: "), false);
+                for (size_t i = 0; i < meta.citation.size(); ++i)
+                {
+                    // Using `\\fB` and `\\fP` instead of `derived_t().in_bold()` here.
+                    // `format_help::print_list_item` uses `format_help::text_width` to determine whether
+                    // there should be a new line after the key ("[i]").
+                    // `format_help::text_width` ignores special sequences such as `\\fB` and `\\fP`,
+                    // but not the actual control sequences produced by `derived_t().in_bold()`.
+                    // All formats support `\\fB` and `\\fP`.
+                    derived_t().print_list_item("\\fB[" + std::to_string(i + 1u) + "]\\fP", meta.citation[i]);
+                }
             }
 
             if (!empty(meta.long_copyright))

include/sharg/detail/format_help.hpp

@@ -196,7 +196,7 @@ class format_help : public format_help_base<format_help>
         // Print term.
         std::fill_n(out, layout.leftPadding, ' ');
         std::cout << to_text(term);
-        unsigned pos = layout.leftPadding + term.size();
+        unsigned pos = layout.leftPadding + text_width(term);
         if (pos + layout.centerPadding > layout.rightColumnTab)
         {
             std::cout << '\n';

test/unit/detail/format_help_test.cpp

@@ -192,7 +192,23 @@ TEST_F(format_help_test, with_citation)
              + "LEGAL\n"
                "    SeqAn Copyright: 2006-2025 Knut Reinert, FU-Berlin; released under the\n"
                "    3-clause BSDL.\n"
-               "    In your academic works please cite: citation\n";
+               "    In your academic works please cite:\n    [1]   citation\n";
+    EXPECT_EQ(get_parse_cout_on_exit(parser), expected);
+}
+
+TEST_F(format_help_test, with_multiple_citation)
+{
+    auto parser = get_parser("-h");
+    parser.info.citation = {"citation1", "citation2"};
+
+    expected = "test_parser\n"
+               "===========\n"
+               "\nOPTIONS\n\n"
+             + basic_options_str + "\n" + version_str() + "\n"
+             + "LEGAL\n"
+               "    SeqAn Copyright: 2006-2025 Knut Reinert, FU-Berlin; released under the\n"
+               "    3-clause BSDL.\n"
+               "    In your academic works please cite:\n    [1]   citation1\n    [2]   citation2\n";
     EXPECT_EQ(get_parse_cout_on_exit(parser), expected);
 }
 

test/unit/detail/format_html_test.cpp

@@ -192,8 +192,9 @@ TEST_F(format_html_test, full_information_information)
           "<br>\n"
           "<strong>SeqAn Copyright: </strong>2006-2025 Knut Reinert, FU-Berlin; released under the 3-clause BSDL.\n"
           "<br>\n"
-          "<strong>In your academic works please cite: </strong>citation\n"
+          "<strong>In your academic works please cite: </strong>\n"
           "<br>\n"
+          "</p>\n<dl>\n<dt><strong>[1]</strong></dt>\n<dd>citation</dd>\n</dl>\n<p>\n"
           "For full copyright and/or warranty information see <strong>--copyright</strong>.\n"
           "<br>\n"
           "</p>\n"

test/unit/detail/format_man_test.cpp

@@ -298,7 +298,10 @@ TEST_F(format_man_test, full_info_short_and_citation)
 .br
 \fBSeqAn Copyright: \fR2006-2025 Knut Reinert, FU-Berlin; released under the 3-clause BSDL.
 .br
-\fBIn your academic works please cite: \fRcitation
+\fBIn your academic works please cite: \fR
+.TP
+\fB[1]\fP
+citation
 )";
     EXPECT_EQ(get_parse_cout_on_exit(parser), expected);
 }
@@ -321,7 +324,10 @@ TEST_F(format_man_test, full_info_short_long_and_citation)
 .br
 \fBSeqAn Copyright: \fR2006-2025 Knut Reinert, FU-Berlin; released under the 3-clause BSDL.
 .br
-\fBIn your academic works please cite: \fRcitation
+\fBIn your academic works please cite: \fR
+.TP
+\fB[1]\fP
+citation
 .br
 For full copyright and/or warranty information see \fB--copyright\fR.
 )";