Skip to content

Commit 4abed1a

Browse files
eseilereseiler
committed
[FEATURE] Handle multiple citations
1 parent cb13c0c commit 4abed1a

File tree

8 files changed

+83
-14
lines changed

8 files changed

+83
-14
lines changed

‎include/sharg/auxiliary.hpp‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,19 @@ enum class update_notifications : uint8_t
4343
*/
4444
struct parser_meta_data // holds all meta information
4545
{
46+
// These are only needed to silence the deprecation warning for `citation`.
47+
//!\cond
48+
#pragma GCC diagnostic push
49+
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
50+
parser_meta_data() = default;
51+
parser_meta_data(parser_meta_data const &) = default;
52+
parser_meta_data & operator=(parser_meta_data const &) = default;
53+
parser_meta_data(parser_meta_data &&) = default;
54+
parser_meta_data & operator=(parser_meta_data &&) = default;
55+
~parser_meta_data() = default;
56+
#pragma GCC diagnostic pop
57+
//!\endcond
58+
4659
/*!\brief The application name that will be displayed on the help page.
4760
*
4861
* The application name must only contain alpha-numeric characters, '_' or '-',
@@ -78,9 +91,16 @@ struct parser_meta_data // holds all meta information
7891
*/
7992
std::string long_copyright;
8093

81-
//!\brief How users shall cite your application.
94+
/*!\brief How users shall cite your application.
95+
* \deprecated This member is deprecated, please use `sharg::parser_meta_data::citations` instead.
96+
*/
97+
SHARG_DEPRECATED_200("sharg::parser::info::citation (std::string) will be removed in Sharg 2.0.0. ",
98+
"Please use sharg::parser::info::citations (std::vector<std::string>) instead.")
8299
std::string citation;
83100

101+
//!\brief How users shall cite your application.
102+
std::vector<std::string> citations;
103+
84104
/*!\brief The title of your man page when exported by specifying
85105
* "--export-help man" on the common line.
86106
*/

‎include/sharg/detail/format_base.hpp‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -361,6 +361,11 @@ class format_help_base : public format_base
361361
void parse(parser_meta_data & parser_meta)
362362
{
363363
meta = parser_meta;
364+
#pragma GCC diagnostic push
365+
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
366+
if (!meta.citation.empty())
367+
meta.citations.emplace_back(std::move(meta.citation));
368+
#pragma GCC diagnostic pop
364369

365370
derived_t().print_header();
366371

@@ -568,7 +573,7 @@ class format_help_base : public format_base
568573
void print_legal()
569574
{
570575
// Print legal stuff
571-
if ((!empty(meta.short_copyright)) || (!empty(meta.long_copyright)) || (!empty(meta.citation))
576+
if ((!empty(meta.short_copyright)) || (!empty(meta.long_copyright)) || (!empty(meta.citations))
572577
|| (!empty(meta.author)) || (!empty(meta.email)))
573578
{
574579
derived_t().print_section("Legal");
@@ -593,10 +598,19 @@ class format_help_base : public format_base
593598
+ "2006-2025 Knut Reinert, FU-Berlin; released under the 3-clause BSDL.",
594599
false);
595600

596-
if (!empty(meta.citation))
601+
if (!empty(meta.citations))
597602
{
598-
derived_t().print_line(derived_t().in_bold("In your academic works please cite: ") + meta.citation,
599-
false);
603+
derived_t().print_line(derived_t().in_bold("In your academic works please cite: "), false);
604+
for (size_t i = 0; i < meta.citations.size(); ++i)
605+
{
606+
// Using `\\fB` and `\\fP` instead of `derived_t().in_bold()` here.
607+
// `format_help::print_list_item` uses `format_help::text_width` to determine whether
608+
// there should be a new line after the key ("[i]").
609+
// `format_help::text_width` ignores special sequences such as `\\fB` and `\\fP`,
610+
// but not the actual control sequences produced by `derived_t().in_bold()`.
611+
// All formats support `\\fB` and `\\fP`.
612+
derived_t().print_list_item("\\fB[" + std::to_string(i + 1u) + "]\\fP", meta.citations[i]);
613+
}
600614
}
601615

602616
if (!empty(meta.long_copyright))

‎include/sharg/detail/format_help.hpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -196,7 +196,7 @@ class format_help : public format_help_base<format_help>
196196
// Print term.
197197
std::fill_n(out, layout.leftPadding, ' ');
198198
std::cout << to_text(term);
199-
unsigned pos = layout.leftPadding + term.size();
199+
unsigned pos = layout.leftPadding + text_width(term);
200200
if (pos + layout.centerPadding > layout.rightColumnTab)
201201
{
202202
std::cout << '\n';

‎include/sharg/platform.hpp‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,12 @@ static_assert(__cplusplus >= 201709L, "SHARG requires C++20, make sure that you
4242
#ifndef SHARG_DOXYGEN_ONLY
4343
# define SHARG_DOXYGEN_ONLY(x)
4444
#endif
45+
46+
//!\brief Deprecation message for Sharg 2.0.0 release.
47+
#ifndef SHARG_DEPRECATED_200
48+
# ifndef SHARG_DISABLE_DEPRECATED_WARNINGS
49+
# define SHARG_DEPRECATED_200(message, alternative) [[deprecated(message alternative)]]
50+
# else
51+
# define SHARG_DEPRECATED_200(message, alternative) /**/
52+
# endif
53+
#endif

‎test/documentation/sharg_doxygen_cfg.in‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -353,7 +353,7 @@ PREDEFINED = "CEREAL_SERIALIZE_FUNCTION_NAME=serialize" \
353353
"SHARG_DOXYGEN_ONLY(x)= x" \
354354
"${SHARG_DOXYGEN_PREDEFINED_NDEBUG}" \
355355
"SHARG_HAS_TDL=1"
356-
EXPAND_AS_DEFINED =
356+
EXPAND_AS_DEFINED = SHARG_DEPRECATED_200
357357
SKIP_FUNCTION_MACROS = NO
358358
#---------------------------------------------------------------------------
359359
# Configuration options related to external references

‎test/unit/detail/format_help_test.cpp‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,26 @@ TEST_F(format_help_test, with_long_copyright)
183183
TEST_F(format_help_test, with_citation)
184184
{
185185
auto parser = get_parser("-h");
186+
parser.info.citations = {"citation"};
187+
188+
expected = "test_parser\n"
189+
"===========\n"
190+
"\nOPTIONS\n\n"
191+
+ basic_options_str + "\n" + version_str() + "\n"
192+
+ "LEGAL\n"
193+
" SeqAn Copyright: 2006-2025 Knut Reinert, FU-Berlin; released under the\n"
194+
" 3-clause BSDL.\n"
195+
" In your academic works please cite:\n [1] citation\n";
196+
EXPECT_EQ(get_parse_cout_on_exit(parser), expected);
197+
}
198+
199+
TEST_F(format_help_test, with_citation_deprecated)
200+
{
201+
auto parser = get_parser("-h");
202+
#pragma GCC diagnostic push
203+
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
186204
parser.info.citation = "citation";
205+
#pragma GCC diagnostic pop
187206

188207
expected = "test_parser\n"
189208
"===========\n"
@@ -192,7 +211,7 @@ TEST_F(format_help_test, with_citation)
192211
+ "LEGAL\n"
193212
" SeqAn Copyright: 2006-2025 Knut Reinert, FU-Berlin; released under the\n"
194213
" 3-clause BSDL.\n"
195-
" In your academic works please cite: citation\n";
214+
" In your academic works please cite:\n [1] citation\n";
196215
EXPECT_EQ(get_parse_cout_on_exit(parser), expected);
197216
}
198217

‎test/unit/detail/format_html_test.cpp‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ TEST_F(format_html_test, full_information_information)
7979
parser.info.url = "https://seqan.de";
8080
parser.info.short_copyright = "short copyright";
8181
parser.info.long_copyright = "long_copyright";
82-
parser.info.citation = "citation";
82+
parser.info.citations = {"citation"};
8383
parser.info.author = "author";
8484
parser.info.email = "email";
8585
parser.add_option(option_value,
@@ -192,8 +192,9 @@ TEST_F(format_html_test, full_information_information)
192192
"<br>\n"
193193
"<strong>SeqAn Copyright: </strong>2006-2025 Knut Reinert, FU-Berlin; released under the 3-clause BSDL.\n"
194194
"<br>\n"
195-
"<strong>In your academic works please cite: </strong>citation\n"
195+
"<strong>In your academic works please cite: </strong>\n"
196196
"<br>\n"
197+
"</p>\n<dl>\n<dt><strong>[1]</strong></dt>\n<dd>citation</dd>\n</dl>\n<p>\n"
197198
"For full copyright and/or warranty information see <strong>--copyright</strong>.\n"
198199
"<br>\n"
199200
"</p>\n"

‎test/unit/detail/format_man_test.cpp‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -291,14 +291,17 @@ TEST_F(format_man_test, full_info_short_and_citation)
291291

292292
// Add a short copyright & citation and test the dummy parser.
293293
parser.info.short_copyright = "short copyright";
294-
parser.info.citation = "citation";
294+
parser.info.citations = {"citation"};
295295

296296
std::string expected = this->expected + R"(.SH LEGAL
297297
\fBtest_parser Copyright: \fRshort copyright
298298
.br
299299
\fBSeqAn Copyright: \fR2006-2025 Knut Reinert, FU-Berlin; released under the 3-clause BSDL.
300300
.br
301-
\fBIn your academic works please cite: \fRcitation
301+
\fBIn your academic works please cite: \fR
302+
.TP
303+
\fB[1]\fP
304+
citation
302305
)";
303306
EXPECT_EQ(get_parse_cout_on_exit(parser), expected);
304307
}
@@ -313,15 +316,18 @@ TEST_F(format_man_test, full_info_short_long_and_citation)
313316

314317
// Add a short copyright & citation & long copyright and test the dummy parser.
315318
parser.info.short_copyright = "short copyright";
316-
parser.info.citation = "citation";
319+
parser.info.citations = {"citation"};
317320
parser.info.long_copyright = "looong copyright";
318321

319322
std::string expected = this->expected + R"(.SH LEGAL
320323
\fBtest_parser Copyright: \fRshort copyright
321324
.br
322325
\fBSeqAn Copyright: \fR2006-2025 Knut Reinert, FU-Berlin; released under the 3-clause BSDL.
323326
.br
324-
\fBIn your academic works please cite: \fRcitation
327+
\fBIn your academic works please cite: \fR
328+
.TP
329+
\fB[1]\fP
330+
citation
325331
.br
326332
For full copyright and/or warranty information see \fB--copyright\fR.
327333
)";

0 commit comments

Comments
 (0)