1 /*
2  * Software License Agreement (BSD License)
3  *
4  *  Point Cloud Library (PCL) - www.pointclouds.org
5  *  Copyright (c) 2010-2012, Willow Garage, Inc.
6  *  Copyright (c) 2012-, Open Perception, Inc.
7  *
8  *  All rights reserved.
9  *
10  *  Redistribution and use in source and binary forms, with or without
11  *  modification, are permitted provided that the following conditions
12  *  are met:
13  *
14  *   * Redistributions of source code must retain the above copyright
15  *     notice, this list of conditions and the following disclaimer.
16  *   * Redistributions in binary form must reproduce the above
17  *     copyright notice, this list of conditions and the following
18  *     disclaimer in the documentation and/or other materials provided
19  *     with the distribution.
20  *   * Neither the name of the copyright holder(s) nor the names of its
21  *     contributors may be used to endorse or promote products derived
22  *     from this software without specific prior written permission.
23  *
24  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
27  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
28  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
29  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
30  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
31  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
32  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
34  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35  *  POSSIBILITY OF SUCH DAMAGE.
36  *
37  */
38 
39 #pragma once
40 
41 #include <vector>
42 #include <sstream>
43 #include <pcl/pcl_macros.h>
44 
45 namespace pcl
46 {
47   namespace console
48   {
49     /** \brief Finds whether the argument with name "argument_name" is in the argument list "argv".
50       * An example for a widely used switch argument is the "-r" flag for unix commands that indicates whether
51       * the command should run recursively or not.
52       * \param[in] argc the number of command line arguments
53       * \param[in] argv the command line arguments
54       * \param[in] argument_name the string value to search for
55       * \return true if argument was found, false otherwise
56       * \note find_switch is simply returning find_argument != -1.
57       */
58     PCL_EXPORTS bool
59     find_switch (int argc, const char * const * argv, const char * argument_name);
60 
61     /** \brief Finds the position of the argument with name "argument_name" in the argument list "argv"
62       * \param[in] argc the number of command line arguments
63       * \param[in] argv the command line arguments
64       * \param[in] argument_name the string value to search for
65       * \return index of found argument or -1 if arguments do not appear in list
66      */
67     PCL_EXPORTS int
68     find_argument (int argc, const char * const * argv, const char * argument_name);
69 
70     /** \brief Template version for parsing arguments. Template parameter needs to have input stream operator overloaded!
71       * \param[in] argc the number of command line arguments
72       * \param[in] argv the command line arguments
73       * \param[in] argument_name the name of the argument to search for
74       * \param[out] value The value of the argument
75       * \return index of found argument or -1 if arguments do not appear in list
76      */
77     template<typename Type> int
parse(int argc,const char * const * argv,const char * argument_name,Type & value)78     parse (int argc, const char * const * argv, const char * argument_name, Type& value)
79     {
80       int index = find_argument (argc, argv, argument_name) + 1;
81 
82       if (index > 0 && index < argc)
83       {
84         std::istringstream stream;
85         stream.clear ();
86         stream.str (argv[index]);
87         stream >> value;
88       }
89 
90       return (index - 1);
91     }
92 
93     /** \brief Parse for a specific given command line argument.
94       * \param[in] argc the number of command line arguments
95       * \param[in] argv the command line arguments
96       * \param[in] str the string value to search for
97       * \param[out] val the resultant value
98       * \return index of found argument or -1 if arguments do not appear in list
99       */
100     PCL_EXPORTS int
101     parse_argument (int argc, const char * const * argv, const char * str, std::string &val);
102 
103     /** \brief Parse for a specific given command line argument.
104       * \param[in] argc the number of command line arguments
105       * \param[in] argv the command line arguments
106       * \param[in] str the string value to search for
107       * \param[out] val the resultant value
108       * \return index of found argument or -1 if arguments do not appear in list
109       */
110     PCL_EXPORTS int
111     parse_argument (int argc, const char * const * argv, const char * str, bool &val);
112 
113     /** \brief Parse for a specific given command line argument.
114       * \param[in] argc the number of command line arguments
115       * \param[in] argv the command line arguments
116       * \param[in] str the string value to search for
117       * \param[out] val the resultant value
118       * \return index of found argument or -1 if arguments do not appear in list
119       */
120     PCL_EXPORTS int
121     parse_argument (int argc, const char * const * argv, const char * str, float &val);
122 
123     /** \brief Parse for a specific given command line argument.
124       * \param[in] argc the number of command line arguments
125       * \param[in] argv the command line arguments
126       * \param[in] str the string value to search for
127       * \param[out] val the resultant value
128       * \return index of found argument or -1 if arguments do not appear in list
129       */
130     PCL_EXPORTS int
131     parse_argument (int argc, const char * const * argv, const char * str, double &val);
132 
133     /** \brief Parse for a specific given command line argument.
134       * \param[in] argc the number of command line arguments
135       * \param[in] argv the command line arguments
136       * \param[in] str the string value to search for
137       * \param[out] val the resultant value
138       * \return index of found argument or -1 if arguments do not appear in list
139       */
140     PCL_EXPORTS int
141     parse_argument (int argc, const char * const * argv, const char * str, int &val);
142 
143     /** \brief Parse for a specific given command line argument.
144       * \param[in] argc the number of command line arguments
145       * \param[in] argv the command line arguments
146       * \param[in] str the string value to search for
147       * \param[out] val the resultant value
148       * \return index of found argument or -1 if arguments do not appear in list
149       */
150     PCL_EXPORTS int
151     parse_argument (int argc, const char * const * argv, const char * str, unsigned int &val);
152 
153     /** \brief Parse for a specific given command line argument.
154       * \param[in] argc the number of command line arguments
155       * \param[in] argv the command line arguments
156       * \param[in] str the string value to search for
157       * \param[out] val the resultant value
158       * \return index of found argument or -1 if arguments do not appear in list
159       */
160     PCL_EXPORTS int
161     parse_argument (int argc, const char * const * argv, const char * str, long int &val) noexcept;
162 
163     /** \brief Parse for a specific given command line argument.
164       * \param[in] argc the number of command line arguments
165       * \param[in] argv the command line arguments
166       * \param[in] str the string value to search for
167       * \param[out] val the resultant value
168       * \return index of found argument or -1 if arguments do not appear in list
169       */
170     PCL_EXPORTS int
171     parse_argument (int argc, const char * const * argv, const char * str, char &val);
172 
173     /** \brief Parse for specific given command line arguments (2x values comma
174       * separated).
175       * \param[in] argc the number of command line arguments
176       * \param[in] argv the command line arguments
177       * \param[in] str the command line argument to search for
178       * \param[out] f the first output value
179       * \param[out] s the second output value
180       * \param[in] debug whether to print debug info or not
181       * \return index of found argument or -1 if arguments do not appear in list
182       */
183     PCL_EXPORTS int
184     parse_2x_arguments (int argc, const char * const * argv, const char * str, float &f, float &s, bool debug = true);
185 
186     /** \brief Parse for specific given command line arguments (2x values comma
187       * separated).
188       * \param[in] argc the number of command line arguments
189       * \param[in] argv the command line arguments
190       * \param[in] str the command line argument to search for
191       * \param[out] f the first output value
192       * \param[out] s the second output value
193       * \param[in] debug whether to print debug info or not
194       * \return index of found argument or -1 if arguments do not appear in list
195       */
196     PCL_EXPORTS int
197     parse_2x_arguments (int argc, const char * const * argv, const char * str, double &f, double &s, bool debug = true);
198 
199     /** \brief Parse for specific given command line arguments (2x values comma
200       * separated).
201       * \param[in] argc the number of command line arguments
202       * \param[in] argv the command line arguments
203       * \param[in] str the command line argument to search for
204       * \param[out] f the first output value
205       * \param[out] s the second output value
206       * \param[in] debug whether to print debug info or not
207       * \return index of found argument or -1 if arguments do not appear in list
208       */
209     PCL_EXPORTS int
210     parse_2x_arguments (int argc, const char * const * argv, const char * str, int &f, int &s, bool debug = true);
211 
212     /** \brief Parse for specific given command line arguments (3x values comma
213       * separated).
214       * \param[in] argc the number of command line arguments
215       * \param[in] argv the command line arguments
216       * \param[in] str the command line argument to search for
217       * \param[out] f the first output value
218       * \param[out] s the second output value
219       * \param[out] t the third output value
220       * \param[in] debug whether to print debug info or not
221       * \return index of found argument or -1 if arguments do not appear in list
222       */
223     PCL_EXPORTS int
224     parse_3x_arguments (int argc, const char * const * argv, const char * str, float &f, float &s, float &t, bool debug = true);
225 
226     /** \brief Parse for specific given command line arguments (3x values comma
227       * separated).
228       * \param[in] argc the number of command line arguments
229       * \param[in] argv the command line arguments
230       * \param[in] str the command line argument to search for
231       * \param[out] f the first output value
232       * \param[out] s the second output value
233       * \param[out] t the third output value
234       * \param[in] debug whether to print debug info or not
235       * \return index of found argument or -1 if arguments do not appear in list
236       */
237     PCL_EXPORTS int
238     parse_3x_arguments (int argc, const char * const * argv, const char * str, double &f, double &s, double &t, bool debug = true);
239 
240     /** \brief Parse for specific given command line arguments (3x values comma
241       * separated).
242       * \param[in] argc the number of command line arguments
243       * \param[in] argv the command line arguments
244       * \param[in] str the command line argument to search for
245       * \param[out] f the first output value
246       * \param[out] s the second output value
247       * \param[out] t the third output value
248       * \param[in] debug whether to print debug info or not
249       * return index of found argument or -1 if arguments do not appear in list
250       */
251     PCL_EXPORTS int
252     parse_3x_arguments (int argc, const char * const * argv, const char * str, int &f, int &s, int &t, bool debug = true);
253 
254     /** \brief Parse for specific given command line arguments (3x values comma
255       * separated).
256       * \param[in] argc the number of command line arguments
257       * \param[in] argv the command line arguments
258       * \param[in] str the command line argument to search for
259       * \param[out] v the vector into which the parsed values will be copied
260       * \return index of found argument or -1 if arguments do not appear in list
261       */
262     PCL_EXPORTS int
263     parse_x_arguments (int argc, const char * const * argv, const char * str, std::vector<double>& v);
264 
265     /** \brief Parse for specific given command line arguments (N values comma
266       * separated).
267       * \param[in] argc the number of command line arguments
268       * \param[in] argv the command line arguments
269       * \param[in] str the command line argument to search for
270       * \param[out] v the vector into which the parsed values will be copied
271       * \return index of found argument or -1 if arguments do not appear in list
272       */
273     PCL_EXPORTS int
274     parse_x_arguments (int argc, const char * const * argv, const char * str, std::vector<float>& v);
275 
276     /** \brief Parse for specific given command line arguments (N values comma
277       * separated).
278       * \param[in] argc the number of command line arguments
279       * \param[in] argv the command line arguments
280       * \param[in] str the command line argument to search for
281       * \param[out] v the vector into which the parsed values will be copied
282       * \return index of found argument or -1 if arguments do not appear in list
283       */
284     PCL_EXPORTS int
285     parse_x_arguments (int argc, const char * const * argv, const char * str, std::vector<int>& v);
286 
287     /** \brief Parse for specific given command line arguments (multiple occurrences
288       * of the same command line parameter).
289       * \param[in] argc the number of command line arguments
290       * \param[in] argv the command line arguments
291       * \param[in] str the command line argument to search for
292       * \param[out] values the resultant output values
293       * \return index of found argument or -1 if arguments do not appear in list
294       */
295     PCL_EXPORTS bool
296     parse_multiple_arguments (int argc, const char * const * argv, const char * str, std::vector<int> &values);
297 
298     /** \brief Parse for specific given command line arguments (multiple occurrences
299       * of the same command line parameter).
300       * \param[in] argc the number of command line arguments
301       * \param[in] argv the command line arguments
302       * \param[in] str the command line argument to search for
303       * \param[out] values the resultant output values
304       * \return true if found, false otherwise
305       */
306     PCL_EXPORTS bool
307     parse_multiple_arguments (int argc, const char * const * argv, const char * str, std::vector<float> &values);
308 
309     /** \brief Parse for specific given command line arguments (multiple occurrences
310       * of the same command line parameter).
311       * \param[in] argc the number of command line arguments
312       * \param[in] argv the command line arguments
313       * \param[in] str the command line argument to search for
314       * \param[out] values the resultant output values
315       * \return true if found, false otherwise
316       */
317     PCL_EXPORTS bool
318     parse_multiple_arguments (int argc, const char * const * argv, const char * str, std::vector<double> &values);
319 
320     /** \brief Parse for a specific given command line argument (multiple occurrences
321       * of the same command line parameter).
322       * \param[in] argc the number of command line arguments
323       * \param[in] argv the command line arguments
324       * \param[in] str the string value to search for
325       * \param[out] values the resultant output values
326       * \return true if found, false otherwise
327       */
328     PCL_EXPORTS bool
329     parse_multiple_arguments (int argc, const char * const * argv, const char * str, std::vector<std::string> &values);
330 
331     /** \brief Parse command line arguments for file names with given extension (multiple occurrences
332       * of 2x argument groups, separated by commas).
333       * \param[in] argc the number of command line arguments
334       * \param[in] argv the command line arguments
335       * \param[in] str the command line argument to search for
336       * \param[out] values_f the first vector of output values
337       * \param[out] values_s the second vector of output values
338       * \return true if found, false otherwise
339       */
340     PCL_EXPORTS bool
341     parse_multiple_2x_arguments (int argc, const char * const * argv, const char * str,
342                                  std::vector<double> &values_f,
343                                  std::vector<double> &values_s);
344 
345     /** \brief Parse command line arguments for file names with given extension (multiple occurrences
346       * of 3x argument groups, separated by commas).
347       * \param[in] argc the number of command line arguments
348       * \param[in] argv the command line arguments
349       * \param[in] str the command line argument to search for
350       * \param[out] values_f the first vector of output values
351       * \param[out] values_s the second vector of output values
352       * \param[out] values_t the third vector of output values
353       * \return true if found, false otherwise
354       */
355     PCL_EXPORTS bool
356     parse_multiple_3x_arguments (int argc, const char * const * argv, const char * str,
357                                  std::vector<double> &values_f,
358                                  std::vector<double> &values_s,
359                                  std::vector<double> &values_t);
360 
361     /** \brief Parse command line arguments for file names with given extension vector
362       * \param[in] argc the number of command line arguments
363       * \param[in] argv the command line arguments
364       * \param[in] extensions the extensions to search for
365       * \return a vector with file names indices
366       */
367     PCL_EXPORTS std::vector<int>
368     parse_file_extension_argument (int argc, const char * const * argv,
369       const std::vector<std::string> &extensions);
370 
371     /** \brief Parse command line arguments for file names with given extension
372       * \param[in] argc the number of command line arguments
373       * \param[in] argv the command line arguments
374       * \param[in] ext the extension to search for
375       * \return a vector with file names indices
376       */
377     PCL_EXPORTS std::vector<int>
378     parse_file_extension_argument (int argc, const char * const * argv, const std::string &ext);
379   }
380 }
381