1///////////////////////////////////////////////////////////////////////////////
2// Name:        wx/cmdline.h
3// Purpose:     wxCmdLineParser and related classes for parsing the command
4//              line options
5// Author:      Vadim Zeitlin
6// Modified by:
7// Created:     04.01.00
8// RCS-ID:      $Id: cmdline.h 49563 2007-10-31 20:46:21Z VZ $
9// Copyright:   (c) 2000 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
10// Licence:     wxWindows licence
11///////////////////////////////////////////////////////////////////////////////
12
13#ifndef _WX_CMDLINE_H_
14#define _WX_CMDLINE_H_
15
16#include "wx/defs.h"
17
18#include "wx/string.h"
19#include "wx/arrstr.h"
20
21#if wxUSE_CMDLINE_PARSER
22
23class WXDLLIMPEXP_FWD_BASE wxDateTime;
24
25// ----------------------------------------------------------------------------
26// constants
27// ----------------------------------------------------------------------------
28
29// by default, options are optional (sic) and each call to AddParam() allows
30// one more parameter - this may be changed by giving non-default flags to it
31enum
32{
33    wxCMD_LINE_OPTION_MANDATORY = 0x01, // this option must be given
34    wxCMD_LINE_PARAM_OPTIONAL   = 0x02, // the parameter may be omitted
35    wxCMD_LINE_PARAM_MULTIPLE   = 0x04, // the parameter may be repeated
36    wxCMD_LINE_OPTION_HELP      = 0x08, // this option is a help request
37    wxCMD_LINE_NEEDS_SEPARATOR  = 0x10  // must have sep before the value
38};
39
40// an option value or parameter may be a string (the most common case), a
41// number or a date
42enum wxCmdLineParamType
43{
44    wxCMD_LINE_VAL_STRING,  // should be 0 (default)
45    wxCMD_LINE_VAL_NUMBER,
46    wxCMD_LINE_VAL_DATE,
47    wxCMD_LINE_VAL_NONE
48};
49
50// for constructing the cmd line description using Init()
51enum wxCmdLineEntryType
52{
53    wxCMD_LINE_SWITCH,
54    wxCMD_LINE_OPTION,
55    wxCMD_LINE_PARAM,
56    wxCMD_LINE_NONE         // to terminate the list
57};
58
59// ----------------------------------------------------------------------------
60// wxCmdLineEntryDesc is a description of one command line
61// switch/option/parameter
62// ----------------------------------------------------------------------------
63
64struct wxCmdLineEntryDesc
65{
66    wxCmdLineEntryType kind;
67    const wxChar *shortName;
68    const wxChar *longName;
69    const wxChar *description;
70    wxCmdLineParamType type;
71    int flags;
72};
73
74// ----------------------------------------------------------------------------
75// wxCmdLineParser is a class for parsing command line.
76//
77// It has the following features:
78//
79// 1. distinguishes options, switches and parameters; allows option grouping
80// 2. allows both short and long options
81// 3. automatically generates the usage message from the cmd line description
82// 4. does type checks on the options values (number, date, ...)
83//
84// To use it you should:
85//
86// 1. construct it giving it the cmd line to parse and optionally its desc
87// 2. construct the cmd line description using AddXXX() if not done in (1)
88// 3. call Parse()
89// 4. use GetXXX() to retrieve the parsed info
90// ----------------------------------------------------------------------------
91
92class WXDLLIMPEXP_BASE wxCmdLineParser
93{
94public:
95    // ctors and initializers
96    // ----------------------
97
98    // default ctor or ctor giving the cmd line in either Unix or Win form
99    wxCmdLineParser() { Init(); }
100    wxCmdLineParser(int argc, char **argv) { Init(); SetCmdLine(argc, argv); }
101#if wxUSE_UNICODE
102    wxCmdLineParser(int argc, wxChar **argv) { Init(); SetCmdLine(argc, argv); }
103#endif // wxUSE_UNICODE
104    wxCmdLineParser(const wxString& cmdline) { Init(); SetCmdLine(cmdline); }
105
106    // the same as above, but also gives the cmd line description - otherwise,
107    // use AddXXX() later
108    wxCmdLineParser(const wxCmdLineEntryDesc *desc)
109        { Init(); SetDesc(desc); }
110    wxCmdLineParser(const wxCmdLineEntryDesc *desc, int argc, char **argv)
111        { Init(); SetCmdLine(argc, argv); SetDesc(desc); }
112#if wxUSE_UNICODE
113    wxCmdLineParser(const wxCmdLineEntryDesc *desc, int argc, wxChar **argv)
114        { Init(); SetCmdLine(argc, argv); SetDesc(desc); }
115#endif // wxUSE_UNICODE
116    wxCmdLineParser(const wxCmdLineEntryDesc *desc, const wxString& cmdline)
117        { Init(); SetCmdLine(cmdline); SetDesc(desc); }
118
119    // set cmd line to parse after using one of the ctors which don't do it
120    void SetCmdLine(int argc, char **argv);
121#if wxUSE_UNICODE
122    void SetCmdLine(int argc, wxChar **argv);
123#endif // wxUSE_UNICODE
124    void SetCmdLine(const wxString& cmdline);
125
126    // not virtual, don't use this class polymorphically
127    ~wxCmdLineParser();
128
129    // set different parser options
130    // ----------------------------
131
132    // by default, '-' is switch char under Unix, '-' or '/' under Win:
133    // switchChars contains all characters with which an option or switch may
134    // start
135    void SetSwitchChars(const wxString& switchChars);
136
137    // long options are not POSIX-compliant, this option allows to disable them
138    void EnableLongOptions(bool enable = true);
139    void DisableLongOptions() { EnableLongOptions(false); }
140
141    bool AreLongOptionsEnabled();
142
143    // extra text may be shown by Usage() method if set by this function
144    void SetLogo(const wxString& logo);
145
146    // construct the cmd line description
147    // ----------------------------------
148
149    // take the cmd line description from the wxCMD_LINE_NONE terminated table
150    void SetDesc(const wxCmdLineEntryDesc *desc);
151
152    // a switch: i.e. an option without value
153    void AddSwitch(const wxString& name, const wxString& lng = wxEmptyString,
154                   const wxString& desc = wxEmptyString,
155                   int flags = 0);
156
157    // an option taking a value of the given type
158    void AddOption(const wxString& name, const wxString& lng = wxEmptyString,
159                   const wxString& desc = wxEmptyString,
160                   wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
161                   int flags = 0);
162
163    // a parameter
164    void AddParam(const wxString& desc = wxEmptyString,
165                  wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
166                  int flags = 0);
167
168    // actions
169    // -------
170
171    // parse the command line, return 0 if ok, -1 if "-h" or "--help" option
172    // was encountered and the help message was given or a positive value if a
173    // syntax error occurred
174    //
175    // if showUsage is true, Usage() is called in case of syntax error or if
176    // help was requested
177    int Parse(bool showUsage = true);
178
179    // give the usage message describing all program options
180    void Usage();
181
182    // get the command line arguments
183    // ------------------------------
184
185    // returns true if the given switch was found
186    bool Found(const wxString& name) const;
187
188    // returns true if an option taking a string value was found and stores the
189    // value in the provided pointer
190    bool Found(const wxString& name, wxString *value) const;
191
192    // returns true if an option taking an integer value was found and stores
193    // the value in the provided pointer
194    bool Found(const wxString& name, long *value) const;
195
196#if wxUSE_DATETIME
197    // returns true if an option taking a date value was found and stores the
198    // value in the provided pointer
199    bool Found(const wxString& name, wxDateTime *value) const;
200#endif // wxUSE_DATETIME
201
202    // gets the number of parameters found
203    size_t GetParamCount() const;
204
205    // gets the value of Nth parameter (as string only for now)
206    wxString GetParam(size_t n = 0u) const;
207
208    // Resets switches and options
209    void Reset();
210
211    // break down the command line in arguments
212    static wxArrayString ConvertStringToArgs(const wxChar *cmdline);
213
214private:
215    // get usage string
216    wxString GetUsageString();
217
218    // common part of all ctors
219    void Init();
220
221    struct wxCmdLineParserData *m_data;
222
223    DECLARE_NO_COPY_CLASS(wxCmdLineParser)
224};
225
226#else // !wxUSE_CMDLINE_PARSER
227
228// this function is always available (even if !wxUSE_CMDLINE_PARSER) because it
229// is used by wxWin itself under Windows
230class WXDLLIMPEXP_BASE wxCmdLineParser
231{
232public:
233    static wxArrayString ConvertStringToArgs(const wxChar *cmdline);
234};
235
236#endif // wxUSE_CMDLINE_PARSER/!wxUSE_CMDLINE_PARSER
237
238#endif // _WX_CMDLINE_H_
239
240