1// Copyright (C) 2020 The Qt Company Ltd.
2// Copyright (C) 2013 Laszlo Papp <lpapp@kde.org>
3// Copyright (C) 2013 David Faure <faure@kde.org>
4// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
5
6#include "qcommandlineoption.h"
7
8#include "qset.h"
9
10QT_BEGIN_NAMESPACE
11
12class QCommandLineOptionPrivate : public QSharedData
13{
14public:
15 Q_NEVER_INLINE
16 explicit QCommandLineOptionPrivate(const QString &name)
17 : names(removeInvalidNames(nameList: QStringList(name)))
18 { }
19
20 Q_NEVER_INLINE
21 explicit QCommandLineOptionPrivate(const QStringList &names)
22 : names(removeInvalidNames(nameList: names))
23 { }
24
25 static QStringList removeInvalidNames(QStringList nameList);
26
27 //! The list of names used for this option.
28 QStringList names;
29
30 //! The documentation name for the value, if one is expected
31 //! Example: "-o <file>" means valueName == "file"
32 QString valueName;
33
34 //! The description used for this option.
35 QString description;
36
37 //! The list of default values used for this option.
38 QStringList defaultValues;
39
40 QCommandLineOption::Flags flags;
41};
42
43/*!
44 \since 5.2
45 \class QCommandLineOption
46 \brief The QCommandLineOption class defines a possible command-line option.
47 \inmodule QtCore
48 \ingroup shared
49 \ingroup tools
50
51 This class is used to describe an option on the command line. It allows
52 different ways of defining the same option with multiple aliases possible.
53 It is also used to describe how the option is used - it may be a flag (e.g. \c{-v})
54 or take a value (e.g. \c{-o file}).
55
56 Examples:
57 \snippet code/src_corelib_tools_qcommandlineoption.cpp 0
58
59 \sa QCommandLineParser
60*/
61
62/*!
63 \fn QCommandLineOption &QCommandLineOption::operator=(QCommandLineOption &&other)
64
65 Move-assigns \a other to this QCommandLineOption instance.
66
67 \since 5.2
68*/
69
70/*!
71 Constructs a command line option object with the name \a name.
72
73 The name can be either short or long. If the name is one character in
74 length, it is considered a short name. Option names must not be empty,
75 must not start with a dash or a slash character, must not contain a \c{=}
76 and cannot be repeated.
77
78 \sa setDescription(), setValueName(), setDefaultValues()
79*/
80QCommandLineOption::QCommandLineOption(const QString &name)
81 : d(new QCommandLineOptionPrivate(name))
82{
83}
84
85/*!
86 Constructs a command line option object with the names \a names.
87
88 This overload allows to set multiple names for the option, for instance
89 \c{o} and \c{output}.
90
91 The names can be either short or long. Any name in the list that is one
92 character in length is a short name. Option names must not be empty,
93 must not start with a dash or a slash character, must not contain a \c{=}
94 and cannot be repeated.
95
96 \sa setDescription(), setValueName(), setDefaultValues()
97*/
98QCommandLineOption::QCommandLineOption(const QStringList &names)
99 : d(new QCommandLineOptionPrivate(names))
100{
101}
102
103/*!
104 Constructs a command line option object with the given arguments.
105
106 The name of the option is set to \a name.
107 The name can be either short or long. If the name is one character in
108 length, it is considered a short name. Option names must not be empty,
109 must not start with a dash or a slash character, must not contain a \c{=}
110 and cannot be repeated.
111
112 The description is set to \a description. It is customary to add a "."
113 at the end of the description.
114
115 In addition, the \a valueName needs to be set if the option expects a value.
116 The default value for the option is set to \a defaultValue.
117
118 In Qt versions before 5.4, this constructor was \c explicit. In Qt 5.4
119 and later, it no longer is and can be used for uniform initialization:
120
121 \snippet code/src_corelib_tools_qcommandlineoption.cpp cxx11-init
122
123 \sa setDescription(), setValueName(), setDefaultValues()
124*/
125QCommandLineOption::QCommandLineOption(const QString &name, const QString &description,
126 const QString &valueName,
127 const QString &defaultValue)
128 : d(new QCommandLineOptionPrivate(name))
129{
130 setValueName(valueName);
131 setDescription(description);
132 setDefaultValue(defaultValue);
133}
134
135/*!
136 Constructs a command line option object with the given arguments.
137
138 This overload allows to set multiple names for the option, for instance
139 \c{o} and \c{output}.
140
141 The names of the option are set to \a names.
142 The names can be either short or long. Any name in the list that is one
143 character in length is a short name. Option names must not be empty,
144 must not start with a dash or a slash character, must not contain a \c{=}
145 and cannot be repeated.
146
147 The description is set to \a description. It is customary to add a "."
148 at the end of the description.
149
150 In addition, the \a valueName needs to be set if the option expects a value.
151 The default value for the option is set to \a defaultValue.
152
153 In Qt versions before 5.4, this constructor was \c explicit. In Qt 5.4
154 and later, it no longer is and can be used for uniform initialization:
155
156 \snippet code/src_corelib_tools_qcommandlineoption.cpp cxx11-init-list
157
158 \sa setDescription(), setValueName(), setDefaultValues()
159*/
160QCommandLineOption::QCommandLineOption(const QStringList &names, const QString &description,
161 const QString &valueName,
162 const QString &defaultValue)
163 : d(new QCommandLineOptionPrivate(names))
164{
165 setValueName(valueName);
166 setDescription(description);
167 setDefaultValue(defaultValue);
168}
169
170/*!
171 Constructs a QCommandLineOption object that is a copy of the QCommandLineOption
172 object \a other.
173
174 \sa operator=()
175*/
176QCommandLineOption::QCommandLineOption(const QCommandLineOption &other)
177 : d(other.d)
178{
179}
180
181/*!
182 Destroys the command line option object.
183*/
184QCommandLineOption::~QCommandLineOption()
185{
186}
187
188/*!
189 Makes a copy of the \a other object and assigns it to this QCommandLineOption
190 object.
191*/
192QCommandLineOption &QCommandLineOption::operator=(const QCommandLineOption &other)
193{
194 d = other.d;
195 return *this;
196}
197
198/*!
199 \fn void QCommandLineOption::swap(QCommandLineOption &other)
200 \memberswap{option}
201*/
202
203/*!
204 Returns the names set for this option.
205 */
206QStringList QCommandLineOption::names() const
207{
208 return d->names;
209}
210
211namespace {
212 struct IsInvalidName
213 {
214 typedef bool result_type;
215 typedef QString argument_type;
216
217 Q_NEVER_INLINE
218 result_type operator()(const QString &name) const noexcept
219 {
220 if (Q_UNLIKELY(name.isEmpty()))
221 return warn(what: "be empty");
222
223 const QChar c = name.at(i: 0);
224 if (Q_UNLIKELY(c == u'-'))
225 return warn(what: "start with a '-'");
226 if (Q_UNLIKELY(c == u'/'))
227 return warn(what: "start with a '/'");
228 if (Q_UNLIKELY(name.contains(u'=')))
229 return warn(what: "contain a '='");
230
231 return false;
232 }
233
234 Q_NEVER_INLINE
235 static bool warn(const char *what) noexcept
236 {
237 qWarning(msg: "QCommandLineOption: Option names cannot %s", what);
238 return true;
239 }
240 };
241} // unnamed namespace
242
243// static
244QStringList QCommandLineOptionPrivate::removeInvalidNames(QStringList nameList)
245{
246 if (Q_UNLIKELY(nameList.isEmpty()))
247 qWarning(msg: "QCommandLineOption: Options must have at least one name");
248 else
249 nameList.removeIf(pred: IsInvalidName());
250 return nameList;
251}
252
253/*!
254 Sets the name of the expected value, for the documentation, to \a valueName.
255
256 Options without a value assigned have a boolean-like behavior:
257 either the user specifies --option or they don't.
258
259 Options with a value assigned need to set a name for the expected value,
260 for the documentation of the option in the help output. An option with names \c{o} and \c{output},
261 and a value name of \c{file} will appear as \c{-o, --output <file>}.
262
263 Call QCommandLineParser::value() if you expect the option to be present
264 only once, and QCommandLineParser::values() if you expect that option
265 to be present multiple times.
266
267 \sa valueName()
268 */
269void QCommandLineOption::setValueName(const QString &valueName)
270{
271 d->valueName = valueName;
272}
273
274/*!
275 Returns the name of the expected value.
276
277 If empty, the option doesn't take a value.
278
279 \sa setValueName()
280 */
281QString QCommandLineOption::valueName() const
282{
283 return d->valueName;
284}
285
286/*!
287 Sets the description used for this option to \a description.
288
289 It is customary to add a "." at the end of the description.
290
291 The description is used by QCommandLineParser::showHelp().
292
293 \sa description()
294 */
295void QCommandLineOption::setDescription(const QString &description)
296{
297 d->description = description;
298}
299
300/*!
301 Returns the description set for this option.
302
303 \sa setDescription()
304 */
305QString QCommandLineOption::description() const
306{
307 return d->description;
308}
309
310/*!
311 Sets the default value used for this option to \a defaultValue.
312
313 The default value is used if the user of the application does not specify
314 the option on the command line.
315
316 If \a defaultValue is empty, the option has no default values.
317
318 \sa defaultValues() setDefaultValues()
319 */
320void QCommandLineOption::setDefaultValue(const QString &defaultValue)
321{
322 QStringList newDefaultValues;
323 if (!defaultValue.isEmpty()) {
324 newDefaultValues.reserve(asize: 1);
325 newDefaultValues << defaultValue;
326 }
327 // commit:
328 d->defaultValues.swap(other&: newDefaultValues);
329}
330
331/*!
332 Sets the list of default values used for this option to \a defaultValues.
333
334 The default values are used if the user of the application does not specify
335 the option on the command line.
336
337 \sa defaultValues() setDefaultValue()
338 */
339void QCommandLineOption::setDefaultValues(const QStringList &defaultValues)
340{
341 d->defaultValues = defaultValues;
342}
343
344/*!
345 Returns the default values set for this option.
346
347 \sa setDefaultValues()
348 */
349QStringList QCommandLineOption::defaultValues() const
350{
351 return d->defaultValues;
352}
353
354/*!
355 Returns a set of flags that affect this command-line option.
356
357 \since 5.8
358 \sa setFlags(), QCommandLineOption::Flags
359 */
360QCommandLineOption::Flags QCommandLineOption::flags() const
361{
362 return d->flags;
363}
364
365/*!
366 Set the set of flags that affect this command-line option to \a flags.
367
368 \since 5.8
369 \sa flags(), QCommandLineOption::Flags
370 */
371void QCommandLineOption::setFlags(Flags flags)
372{
373 d->flags = flags;
374}
375
376/*!
377 \enum QCommandLineOption::Flag
378
379 \value HiddenFromHelp Hide this option in the user-visible help output. All
380 options are visible by default. Setting this flag for a particular
381 option makes it internal, i.e. not listed in the help output.
382
383 \value ShortOptionStyle The option will always be understood as a short
384 option, regardless of what was set by
385 QCommandLineParser::setSingleDashWordOptionMode.
386 This allows flags such as \c{-DDEFINE=VALUE} or \c{-I/include/path} to be
387 interpreted as short flags even when the parser is in
388 QCommandLineParser::ParseAsLongOptions mode.
389
390 \value IgnoreOptionsAfter [since 6.9] No options beyond this one will be parsed. Useful
391 for cases where you need to send extra command line arguments to a secondary
392 application. If a value is provided for this option, it will be ignored.
393
394 \sa QCommandLineOption::setFlags(), QCommandLineOption::flags()
395*/
396
397QT_END_NAMESPACE
398

source code of qtbase/src/corelib/tools/qcommandlineoption.cpp