Teuchos Package Browser (Single Doxygen Collection)  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
core/example/CommandLineProcessor/cxx_main.cpp
Go to the documentation of this file.
1 /*
2 // @HEADER
3 // ***********************************************************************
4 //
5 // Teuchos: Common Tools Package
6 // Copyright (2004) Sandia Corporation
7 //
8 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
9 // license for use of this work by or on behalf of the U.S. Government.
10 //
11 // Redistribution and use in source and binary forms, with or without
12 // modification, are permitted provided that the following conditions are
13 // met:
14 //
15 // 1. Redistributions of source code must retain the above copyright
16 // notice, this list of conditions and the following disclaimer.
17 //
18 // 2. Redistributions in binary form must reproduce the above copyright
19 // notice, this list of conditions and the following disclaimer in the
20 // documentation and/or other materials provided with the distribution.
21 //
22 // 3. Neither the name of the Corporation nor the names of the
23 // contributors may be used to endorse or promote products derived from
24 // this software without specific prior written permission.
25 //
26 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
27 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
29 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
30 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
31 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
32 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
33 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
34 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
35 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
36 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37 //
38 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
39 //
40 // ***********************************************************************
41 // @HEADER
42 */
43 
48 #include "Teuchos_Version.hpp"
49 #include "Teuchos_ConfigDefs.hpp"
51 
52 // Enum for the speed option
54 
55 int main(int argc, char* argv[])
56 {
57  Teuchos::GlobalMPISession mpiSession(&argc,&argv);
58  const int procRank = Teuchos::GlobalMPISession::getRank();
59 
60  Teuchos::oblackholestream blackhole;
61  std::ostream &out = ( procRank == 0 ? std::cout : blackhole );
62 
63  bool success = true;
64 
65  try {
66 
67  out << Teuchos::Teuchos_Version() << std::endl << std::endl;
68 
69  // Creating an empty command line processor looks like:
71 
72  My_CLP.setDocString(
73  "This example program demonstrates how to use this Teuchos::CommandLineProcessor class\n"
74  "to get options from the command-line and print this help messange automatically.\n"
75  );
76 
77  /* To set and option, it must be given a name and default value. Additionally,
78  each option can be given a help std::string. Although it is not necessary, a help
79  std::string aids a users comprehension of the acceptable command line arguments.
80  Some examples of setting command line options are:
81  */
82  // Set an integer command line option.
83  int NumIters = 1550;
84  My_CLP.setOption("iterations", &NumIters, "Number of iterations");
85  // Set a long integer command line option
86  long int MatrixDim = Teuchos::OrdinalTraits<long int>::max();
87  My_CLP.setOption("long-matrix-dim", &MatrixDim, "Matrix dimension (long)");
88  long long int MatrixDim2 = Teuchos::OrdinalTraits<long long int>::max();
89  My_CLP.setOption("long-long-matrix-dim", &MatrixDim2, "Matrix dimension (long long)");
90  // Set a double-precision command line option.
91  double Tolerance = 1e-10;
92  My_CLP.setOption("tolerance", &Tolerance, "Tolerance");
93  // Set a std::string command line option.
94  std::string Solver = "GMRES";
95  My_CLP.setOption("solver", &Solver, "Linear solver");
96  // Set a boolean command line option.
97  bool Precondition = true;
98  My_CLP.setOption("precondition","no-precondition",
99  &Precondition,"Preconditioning flag");
100  // Set an enumeration command line option
101  const int num_speed_values = 3;
102  const ESpeed speed_opt_values[] = { SPEED_SLOW, SPEED_MEDIUM, SPEED_FAST };
103  const char* speed_opt_names[] = { "slow", "medium", "fast" };
104  ESpeed Speed = SPEED_MEDIUM;
105  My_CLP.setOption(
106  "speed", &Speed,
107  num_speed_values, speed_opt_values, speed_opt_names,
108  "Speed of our solver"
109  );
110 
111  /* There are also two methods that control the behavior of the
112  command line processor. First, for the command line processor to
113  allow an unrecognized a command line option to be ignored (and
114  only have a warning printed), use:
115  */
116  My_CLP.recogniseAllOptions(true);
117 
118  /* Second, by default, if the parser finds a command line option it
119  doesn't recognize or finds the --help option, it will throw an
120  std::exception. If you want prevent a command line processor from
121  throwing an std::exception (which is important in this program since
122  we don't have an try/catch around this) when it encounters a
123  unrecognized option or help is printed, use:
124  */
125  My_CLP.throwExceptions(false);
126 
127  /* We now parse the command line where argc and argv are passed to
128  the parse method. Note that since we have turned off std::exception
129  throwing above we had better grab the return argument so that
130  we can see what happened and act accordingly.
131  */
133  parseReturn= My_CLP.parse( argc, argv );
135  return 0;
136  }
138  return 1; // Error!
139  }
140  // Here is where you would use these command line arguments but for this example program
141  // we will just print the help message with the new values of the command-line arguments.
142  if (procRank == 0)
143  out << "\nPrinting help message with new values of command-line arguments ...\n\n";
144  My_CLP.printHelpMessage(argv[0],out);
145 
146  // Now we will print the option values
147  if (procRank == 0) {
148  out << "\nPrinting user options after parsing ...\n\n";
149  out << "NumIters = " << NumIters << std::endl;
150  out << "MatrixDim = " << MatrixDim << std::endl;
151  out << "MatrixDim2 = " << MatrixDim2 << std::endl;
152  out << "Tolerance = " << Tolerance << std::endl;
153  out << "Solver = \"" << Solver << "\"\n";
154  out << "Precondition = " << Precondition << std::endl;
155  out << "Speed = " << Speed << std::endl;
156  }
157 
158  } // try
159  TEUCHOS_STANDARD_CATCH_STATEMENTS(true,std::cerr,success);
160 
161  if(success)
162  out << "\nEnd Result: TEST PASSED" << std::endl;
163 
164  return ( success ? 0 : 1 );
165 }
static int getRank()
The rank of the calling process in MPI_COMM_WORLD.
void recogniseAllOptions(const bool &recogniseAllOptions)
Set if all options must be recognized or not.
void printHelpMessage(const char program_name[], std::ostream &out) const
Print the help message.
basic_ostream&lt;&gt; subclass that does nothing but discard output.
Teuchos header file which uses auto-configuration information to include necessary C++ headers...
Initialize, finalize, and query the global MPI session.
void setOption(const char option_true[], const char option_false[], bool *option_val, const char documentation[]=NULL)
Set a boolean option.
#define TEUCHOS_STANDARD_CATCH_STATEMENTS(VERBOSE, ERR_STREAM, SUCCESS_FLAG)
Simple macro that catches and reports standard exceptions and other exceptions.
static T max()
Returns a value designating the maximum value accessible by code using OrdinalTraits.
EParseCommandLineReturn parse(int argc, char *argv[], std::ostream *errout=&std::cerr) const
Parse a command line.
void throwExceptions(const bool &throwExceptions)
Set if an std::exception is thrown, there is a parse error, or help is printed.
std::string Teuchos_Version()
int main(int argc, char *argv[])
EParseCommandLineReturn
Return value for CommandLineProcessor::parse(). Note: These enums are all given non-negative values s...
Defines basic traits for the ordinal field type.
A MPI utilities class, providing methods for initializing, finalizing, and querying the global MPI se...
Basic command line parser for input from (argc,argv[])
void setDocString(const char doc_string[])
Set a documentation sting for the entire program printed when –help is specified. ...
Class that helps parse command line input arguments from (argc,argv[]) and set options.