Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/common/include/pcl/console/parse.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2010-2012, Willow Garage, Inc.
00006  *  Copyright (c) 2012-, Open Perception, Inc.
00007  *
00008  *  All rights reserved.
00009  *
00010  *  Redistribution and use in source and binary forms, with or without
00011  *  modification, are permitted provided that the following conditions
00012  *  are met:
00013  *
00014  *   * Redistributions of source code must retain the above copyright
00015  *     notice, this list of conditions and the following disclaimer.
00016  *   * Redistributions in binary form must reproduce the above
00017  *     copyright notice, this list of conditions and the following
00018  *     disclaimer in the documentation and/or other materials provided
00019  *     with the distribution.
00020  *   * Neither the name of the copyright holder(s) nor the names of its
00021  *     contributors may be used to endorse or promote products derived
00022  *     from this software without specific prior written permission.
00023  *
00024  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00025  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00026  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00027  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00028  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00029  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00030  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00031  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00032  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00033  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00034  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00035  *  POSSIBILITY OF SUCH DAMAGE.
00036  *
00037  */
00038 #ifndef PCL_CONSOLE_PARSE_H_
00039 #define PCL_CONSOLE_PARSE_H_
00040 
00041 #include <vector>
00042 #include <sstream>
00043 #include <pcl/pcl_macros.h>
00044 
00045 namespace pcl
00046 {
00047   namespace console
00048   {
00049     /** \brief Finds whether the argument with name "argument_name" is in the argument list "argv".
00050       * An example for a widely used switch argument is the "-r" flag for unix commands that indicates whether
00051       * the command should run recursively or not.
00052       * \param[in] argc the number of command line arguments
00053       * \param[in] argv the command line arguments
00054       * \param[in] argument_name the string value to search for
00055       * \return true if argument was found, false otherwise
00056       * \note find_switch is simply returning find_argument != -1.
00057       */
00058     PCL_EXPORTS bool
00059     find_switch (int argc, char** argv, const char* argument_name);
00060 
00061     /** \brief Finds the position of the argument with name "argument_name" in the argument list "argv"
00062       * \param[in] argc the number of command line arguments
00063       * \param[in] argv the command line arguments
00064       * \param[in] argument_name the string value to search for
00065       * \return index of found argument or -1 of arguments does not appear in list
00066      */
00067     PCL_EXPORTS int
00068     find_argument (int argc, char** argv, const char* argument_name);
00069 
00070     /** \brief Template version for parsing arguments. Template parameter needs to have input stream operator overloaded!
00071       * \param[in] argc the number of command line arguments
00072       * \param[in] argv the command line arguments
00073       * \param[in] argument_name the name of the argument to search for
00074       * \param[out] value The value of the argument
00075       * \return index of found argument or -1 of arguments does not appear in list
00076      */
00077     template<typename Type> int
00078     parse (int argc, char** argv, const char* argument_name, Type& value)
00079     {
00080       int index = find_argument (argc, argv, argument_name) + 1;
00081 
00082       if (index > 0 && index < argc)
00083       {
00084         std::istringstream stream;
00085         stream.clear ();
00086         stream.str (argv[index]);
00087         stream >> value;
00088       }
00089 
00090       return (index - 1);
00091     }
00092 
00093     /** \brief Parse for a specific given command line argument. Returns the value
00094       * sent as a string.
00095       * \param[in] argc the number of command line arguments
00096       * \param[in] argv the command line arguments
00097       * \param[in] str the string value to search for
00098       * \param[out] val the resultant value
00099       */
00100     PCL_EXPORTS int
00101     parse_argument (int argc, char** argv, const char* str, std::string &val);
00102 
00103     /** \brief Parse for a specific given command line argument. Returns the value
00104       * sent as a boolean.
00105       * \param[in] argc the number of command line arguments
00106       * \param[in] argv the command line arguments
00107       * \param[in] str the string value to search for
00108       * \param[out] val the resultant value
00109       */
00110     PCL_EXPORTS int
00111     parse_argument (int argc, char** argv, const char* str, bool &val);
00112 
00113     /** \brief Parse for a specific given command line argument. Returns the value
00114       * sent as a double.
00115       * \param[in] argc the number of command line arguments
00116       * \param[in] argv the command line arguments
00117       * \param[in] str the string value to search for
00118       * \param[out] val the resultant value
00119       */
00120     PCL_EXPORTS int
00121     parse_argument (int argc, char** argv, const char* str, float &val);
00122     
00123     /** \brief Parse for a specific given command line argument. Returns the value
00124       * sent as a double.
00125       * \param[in] argc the number of command line arguments
00126       * \param[in] argv the command line arguments
00127       * \param[in] str the string value to search for
00128       * \param[out] val the resultant value
00129       */
00130     PCL_EXPORTS int
00131     parse_argument (int argc, char** argv, const char* str, double &val);
00132 
00133     /** \brief Parse for a specific given command line argument. Returns the value
00134       * sent as an int.
00135       * \param[in] argc the number of command line arguments
00136       * \param[in] argv the command line arguments
00137       * \param[in] str the string value to search for
00138       * \param[out] val the resultant value
00139       */
00140     PCL_EXPORTS int
00141     parse_argument (int argc, char** argv, const char* str, int &val);
00142 
00143     /** \brief Parse for a specific given command line argument. Returns the value
00144       * sent as an unsigned int.
00145       * \param[in] argc the number of command line arguments
00146       * \param[in] argv the command line arguments
00147       * \param[in] str the string value to search for
00148       * \param[out] val the resultant value
00149       */
00150     PCL_EXPORTS int
00151     parse_argument (int argc, char** argv, const char* str, unsigned int &val);
00152 
00153     /** \brief Parse for a specific given command line argument. Returns the value
00154       * sent as an int.
00155       * \param[in] argc the number of command line arguments
00156       * \param[in] argv the command line arguments
00157       * \param[in] str the string value to search for
00158       * \param[out] val the resultant value
00159       */
00160     PCL_EXPORTS int
00161     parse_argument (int argc, char** argv, const char* str, char &val);
00162 
00163     /** \brief Parse for specific given command line arguments (2x values comma
00164       * separated). Returns the values sent as doubles.
00165       * \param[in] argc the number of command line arguments
00166       * \param[in] argv the command line arguments
00167       * \param[in] str the command line argument to search for
00168       * \param[out] f the first output value
00169       * \param[out] s the second output value
00170       * \param[in] debug whether to print debug info or not
00171       */
00172     PCL_EXPORTS int
00173     parse_2x_arguments (int argc, char** argv, const char* str, float &f, float &s, bool debug = true);
00174 
00175     /** \brief Parse for specific given command line arguments (2x values comma
00176       * separated). Returns the values sent as doubles.
00177       * \param[in] argc the number of command line arguments
00178       * \param[in] argv the command line arguments
00179       * \param[in] str the command line argument to search for
00180       * \param[out] f the first output value
00181       * \param[out] s the second output value
00182       * \param[in] debug whether to print debug info or not
00183       */
00184     PCL_EXPORTS int
00185     parse_2x_arguments (int argc, char** argv, const char* str, double &f, double &s, bool debug = true);
00186 
00187     /** \brief Parse for specific given command line arguments (2x values comma
00188       * separated). Returns the values sent as ints.
00189       * \param[in] argc the number of command line arguments
00190       * \param[in] argv the command line arguments
00191       * \param[in] str the command line argument to search for
00192       * \param[out] f the first output value
00193       * \param[out] s the second output value
00194       * \param[in] debug whether to print debug info or not
00195       */
00196     PCL_EXPORTS int
00197     parse_2x_arguments (int argc, char** argv, const char* str, int &f, int &s, bool debug = true);
00198 
00199     /** \brief Parse for specific given command line arguments (3x values comma
00200       * separated). Returns the values sent as doubles.
00201       * \param[in] argc the number of command line arguments
00202       * \param[in] argv the command line arguments
00203       * \param[in] str the command line argument to search for
00204       * \param[out] f the first output value
00205       * \param[out] s the second output value
00206       * \param[out] t the third output value
00207       * \param[in] debug whether to print debug info or not
00208       */
00209     PCL_EXPORTS int
00210     parse_3x_arguments (int argc, char** argv, const char* str, float &f, float &s, float &t, bool debug = true);
00211 
00212     /** \brief Parse for specific given command line arguments (3x values comma
00213       * separated). Returns the values sent as doubles.
00214       * \param[in] argc the number of command line arguments
00215       * \param[in] argv the command line arguments
00216       * \param[in] str the command line argument to search for
00217       * \param[out] f the first output value
00218       * \param[out] s the second output value
00219       * \param[out] t the third output value
00220       * \param[in] debug whether to print debug info or not
00221       */
00222     PCL_EXPORTS int
00223     parse_3x_arguments (int argc, char** argv, const char* str, double &f, double &s, double &t, bool debug = true);
00224 
00225     /** \brief Parse for specific given command line arguments (3x values comma
00226       * separated). Returns the values sent as ints.
00227       * \param[in] argc the number of command line arguments
00228       * \param[in] argv the command line arguments
00229       * \param[in] str the command line argument to search for
00230       * \param[out] f the first output value
00231       * \param[out] s the second output value
00232       * \param[out] t the third output value
00233       * \param[in] debug whether to print debug info or not
00234       */
00235     PCL_EXPORTS int
00236     parse_3x_arguments (int argc, char** argv, const char* str, int &f, int &s, int &t, bool debug = true);
00237 
00238     /** \brief Parse for specific given command line arguments (3x values comma
00239       * separated). Returns the values sent as doubles.
00240       * \param[in] argc the number of command line arguments
00241       * \param[in] argv the command line arguments
00242       * \param[in] str the command line argument to search for
00243       * \param[out] v the vector into which the parsed values will be copied
00244       */
00245     PCL_EXPORTS int
00246     parse_x_arguments (int argc, char** argv, const char* str, std::vector<double>& v);
00247 
00248     /** \brief Parse for specific given command line arguments (N values comma
00249       * separated). Returns the values sent as ints.
00250       * \param[in] argc the number of command line arguments
00251       * \param[in] argv the command line arguments
00252       * \param[in] str the command line argument to search for
00253       * \param[out] v the vector into which the parsed values will be copied
00254       */
00255     PCL_EXPORTS int
00256     parse_x_arguments (int argc, char** argv, const char* str, std::vector<float>& v);
00257 
00258     /** \brief Parse for specific given command line arguments (N values comma
00259       * separated). Returns the values sent as ints.
00260       * \param[in] argc the number of command line arguments
00261       * \param[in] argv the command line arguments
00262       * \param[in] str the command line argument to search for
00263       * \param[out] v the vector into which the parsed values will be copied
00264       */
00265     PCL_EXPORTS int
00266     parse_x_arguments (int argc, char** argv, const char* str, std::vector<int>& v);
00267 
00268     /** \brief Parse for specific given command line arguments (multiple occurances
00269       * of the same command line parameter). Returns the values sent as a vector.
00270       * \param[in] argc the number of command line arguments
00271       * \param[in] argv the command line arguments
00272       * \param[in] str the command line argument to search for
00273       * \param[out] values the resultant output values
00274       */
00275     PCL_EXPORTS bool
00276     parse_multiple_arguments (int argc, char** argv, const char* str, std::vector<int> &values);
00277 
00278     /** \brief Parse for specific given command line arguments (multiple occurances
00279       * of the same command line parameter). Returns the values sent as a vector.
00280       * \param[in] argc the number of command line arguments
00281       * \param[in] argv the command line arguments
00282       * \param[in] str the command line argument to search for
00283       * \param[out] values the resultant output values
00284       */
00285     PCL_EXPORTS bool
00286     parse_multiple_arguments (int argc, char** argv, const char* str, std::vector<float> &values);
00287 
00288     /** \brief Parse for specific given command line arguments (multiple occurances
00289       * of the same command line parameter). Returns the values sent as a vector.
00290       * \param[in] argc the number of command line arguments
00291       * \param[in] argv the command line arguments
00292       * \param[in] str the command line argument to search for
00293       * \param[out] values the resultant output values
00294       */
00295     PCL_EXPORTS bool
00296     parse_multiple_arguments (int argc, char** argv, const char* str, std::vector<double> &values);
00297 
00298     /** \brief Parse for a specific given command line argument (multiple occurences
00299       * of the same command line parameter). Returns the value sent as a vector.
00300       * \param[in] argc the number of command line arguments
00301       * \param[in] argv the command line arguments
00302       * \param[in] str the string value to search for
00303       * \param[out] values the resultant output values
00304       */
00305     PCL_EXPORTS bool
00306     parse_multiple_arguments (int argc, char** argv, const char* str, std::vector<std::string> &values);
00307 
00308     /** \brief Parse for specific given command line arguments (multiple occurances
00309       * of 2x argument groups, separated by commas). Returns 2 vectors holding the
00310       * given values.
00311       * \param[in] argc the number of command line arguments
00312       * \param[in] argv the command line arguments
00313       * \param[in] str the command line argument to search for
00314       * \param[out] values_f the first vector of output values
00315       * \param[out] values_s the second vector of output values
00316       */
00317     PCL_EXPORTS bool
00318     parse_multiple_2x_arguments (int argc, char** argv, const char* str, 
00319                                  std::vector<double> &values_f, 
00320                                  std::vector<double> &values_s);
00321 
00322     /** \brief Parse for specific given command line arguments (multiple occurances
00323       * of 3x argument groups, separated by commas). Returns 3 vectors holding the
00324       * given values.
00325       * \param[in] argc the number of command line arguments
00326       * \param[in] argv the command line arguments
00327       * \param[in] str the command line argument to search for
00328       * \param[out] values_f the first vector of output values
00329       * \param[out] values_s the second vector of output values
00330       * \param[out] values_t the third vector of output values
00331       */
00332     PCL_EXPORTS bool
00333     parse_multiple_3x_arguments (int argc, char** argv, const char* str, 
00334                                  std::vector<double> &values_f, 
00335                                  std::vector<double> &values_s, 
00336                                  std::vector<double> &values_t);
00337 
00338     /** \brief Parse command line arguments for file names. Returns a vector with
00339       * file names indices.
00340       * \param[in] argc the number of command line arguments
00341       * \param[in] argv the command line arguments
00342       * \param[in] ext the extension to search for
00343       */
00344     PCL_EXPORTS std::vector<int>
00345     parse_file_extension_argument (int argc, char** argv, const std::string &ext);
00346   }
00347 }
00348 
00349 #endif      // PCL_CONSOLE_PARSE_H_
00350