1 ///////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxCmdLineParser and related classes for parsing the command
5 // Author: Vadim Zeitlin
9 // Copyright: (c) 2000 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
10 // Licence: wxWindows licence
11 ///////////////////////////////////////////////////////////////////////////////
13 #ifndef _WX_CMDLINE_H_
14 #define _WX_CMDLINE_H_
18 #include "wx/string.h"
19 #include "wx/arrstr.h"
20 #include "wx/cmdargs.h"
22 #if wxUSE_CMDLINE_PARSER
24 class WXDLLIMPEXP_FWD_BASE wxDateTime
;
26 // ----------------------------------------------------------------------------
28 // ----------------------------------------------------------------------------
30 // by default, options are optional (sic) and each call to AddParam() allows
31 // one more parameter - this may be changed by giving non-default flags to it
34 wxCMD_LINE_OPTION_MANDATORY
= 0x01, // this option must be given
35 wxCMD_LINE_PARAM_OPTIONAL
= 0x02, // the parameter may be omitted
36 wxCMD_LINE_PARAM_MULTIPLE
= 0x04, // the parameter may be repeated
37 wxCMD_LINE_OPTION_HELP
= 0x08, // this option is a help request
38 wxCMD_LINE_NEEDS_SEPARATOR
= 0x10 // must have sep before the value
41 // an option value or parameter may be a string (the most common case), a
43 enum wxCmdLineParamType
45 wxCMD_LINE_VAL_STRING
, // should be 0 (default)
46 wxCMD_LINE_VAL_NUMBER
,
48 wxCMD_LINE_VAL_DOUBLE
,
52 // for constructing the cmd line description using Init()
53 enum wxCmdLineEntryType
58 wxCMD_LINE_NONE
// to terminate the list
61 // ----------------------------------------------------------------------------
62 // wxCmdLineEntryDesc is a description of one command line
63 // switch/option/parameter
64 // ----------------------------------------------------------------------------
66 struct wxCmdLineEntryDesc
68 wxCmdLineEntryType kind
;
69 const char *shortName
;
71 const char *description
;
72 wxCmdLineParamType type
;
76 // the list of wxCmdLineEntryDesc objects should be terminated with this one
77 #define wxCMD_LINE_DESC_END \
78 { wxCMD_LINE_NONE, NULL, NULL, NULL, wxCMD_LINE_VAL_NONE, 0x0 }
80 // ----------------------------------------------------------------------------
81 // wxCmdLineParser is a class for parsing command line.
83 // It has the following features:
85 // 1. distinguishes options, switches and parameters; allows option grouping
86 // 2. allows both short and long options
87 // 3. automatically generates the usage message from the cmd line description
88 // 4. does type checks on the options values (number, date, ...)
90 // To use it you should:
92 // 1. construct it giving it the cmd line to parse and optionally its desc
93 // 2. construct the cmd line description using AddXXX() if not done in (1)
95 // 4. use GetXXX() to retrieve the parsed info
96 // ----------------------------------------------------------------------------
98 class WXDLLIMPEXP_BASE wxCmdLineParser
101 // ctors and initializers
102 // ----------------------
104 // default ctor or ctor giving the cmd line in either Unix or Win form
105 wxCmdLineParser() { Init(); }
106 wxCmdLineParser(int argc
, char **argv
) { Init(); SetCmdLine(argc
, argv
); }
108 wxCmdLineParser(int argc
, wxChar
**argv
) { Init(); SetCmdLine(argc
, argv
); }
109 wxCmdLineParser(int argc
, const wxCmdLineArgsArray
& argv
)
110 { Init(); SetCmdLine(argc
, argv
); }
111 #endif // wxUSE_UNICODE
112 wxCmdLineParser(const wxString
& cmdline
) { Init(); SetCmdLine(cmdline
); }
114 // the same as above, but also gives the cmd line description - otherwise,
115 // use AddXXX() later
116 wxCmdLineParser(const wxCmdLineEntryDesc
*desc
)
117 { Init(); SetDesc(desc
); }
118 wxCmdLineParser(const wxCmdLineEntryDesc
*desc
, int argc
, char **argv
)
119 { Init(); SetCmdLine(argc
, argv
); SetDesc(desc
); }
121 wxCmdLineParser(const wxCmdLineEntryDesc
*desc
, int argc
, wxChar
**argv
)
122 { Init(); SetCmdLine(argc
, argv
); SetDesc(desc
); }
123 wxCmdLineParser(const wxCmdLineEntryDesc
*desc
,
125 const wxCmdLineArgsArray
& argv
)
126 { Init(); SetCmdLine(argc
, argv
); SetDesc(desc
); }
127 #endif // wxUSE_UNICODE
128 wxCmdLineParser(const wxCmdLineEntryDesc
*desc
, const wxString
& cmdline
)
129 { Init(); SetCmdLine(cmdline
); SetDesc(desc
); }
131 // set cmd line to parse after using one of the ctors which don't do it
132 void SetCmdLine(int argc
, char **argv
);
134 void SetCmdLine(int argc
, wxChar
**argv
);
135 void SetCmdLine(int argc
, const wxCmdLineArgsArray
& argv
);
136 #endif // wxUSE_UNICODE
137 void SetCmdLine(const wxString
& cmdline
);
139 // not virtual, don't use this class polymorphically
142 // set different parser options
143 // ----------------------------
145 // by default, '-' is switch char under Unix, '-' or '/' under Win:
146 // switchChars contains all characters with which an option or switch may
148 void SetSwitchChars(const wxString
& switchChars
);
150 // long options are not POSIX-compliant, this option allows to disable them
151 void EnableLongOptions(bool enable
= true);
152 void DisableLongOptions() { EnableLongOptions(false); }
154 bool AreLongOptionsEnabled() const;
156 // extra text may be shown by Usage() method if set by this function
157 void SetLogo(const wxString
& logo
);
159 // construct the cmd line description
160 // ----------------------------------
162 // take the cmd line description from the wxCMD_LINE_NONE terminated table
163 void SetDesc(const wxCmdLineEntryDesc
*desc
);
165 // a switch: i.e. an option without value
166 void AddSwitch(const wxString
& name
, const wxString
& lng
= wxEmptyString
,
167 const wxString
& desc
= wxEmptyString
,
170 // an option taking a value of the given type
171 void AddOption(const wxString
& name
, const wxString
& lng
= wxEmptyString
,
172 const wxString
& desc
= wxEmptyString
,
173 wxCmdLineParamType type
= wxCMD_LINE_VAL_STRING
,
177 void AddParam(const wxString
& desc
= wxEmptyString
,
178 wxCmdLineParamType type
= wxCMD_LINE_VAL_STRING
,
184 // parse the command line, return 0 if ok, -1 if "-h" or "--help" option
185 // was encountered and the help message was given or a positive value if a
186 // syntax error occurred
188 // if showUsage is true, Usage() is called in case of syntax error or if
189 // help was requested
190 int Parse(bool showUsage
= true);
192 // give the usage message describing all program options
195 // return the usage string, call Usage() to directly show it to the user
196 wxString
GetUsageString() const;
198 // get the command line arguments
199 // ------------------------------
201 // returns true if the given switch was found
202 bool Found(const wxString
& name
) const;
204 // returns true if an option taking a string value was found and stores the
205 // value in the provided pointer
206 bool Found(const wxString
& name
, wxString
*value
) const;
208 // returns true if an option taking an integer value was found and stores
209 // the value in the provided pointer
210 bool Found(const wxString
& name
, long *value
) const;
212 // returns true if an option taking a double value was found and stores
213 // the value in the provided pointer
214 bool Found(const wxString
& name
, double *value
) const;
217 // returns true if an option taking a date value was found and stores the
218 // value in the provided pointer
219 bool Found(const wxString
& name
, wxDateTime
*value
) const;
220 #endif // wxUSE_DATETIME
222 // gets the number of parameters found
223 size_t GetParamCount() const;
225 // gets the value of Nth parameter (as string only for now)
226 wxString
GetParam(size_t n
= 0u) const;
228 // Resets switches and options
231 // break down the command line in arguments
232 static wxArrayString
ConvertStringToArgs(const wxString
& cmdline
);
235 // common part of all ctors
238 struct wxCmdLineParserData
*m_data
;
240 DECLARE_NO_COPY_CLASS(wxCmdLineParser
)
243 #else // !wxUSE_CMDLINE_PARSER
245 // this function is always available (even if !wxUSE_CMDLINE_PARSER) because it
246 // is used by wxWin itself under Windows
247 class WXDLLIMPEXP_BASE wxCmdLineParser
250 static wxArrayString
ConvertStringToArgs(const wxString
& cmdline
);
253 #endif // wxUSE_CMDLINE_PARSER/!wxUSE_CMDLINE_PARSER
255 #endif // _WX_CMDLINE_H_