Parsing keyed options to a test

The multiple-value option allows you to specify that a key can take more than
one argument.

The naked option allows you to specify that a key takes no arguments.

This example shows how to run a test that uses special options. The test requires these arguments:

• The sample count (-s) must be in the range 1 through 256.
• Logging (-l) takes no arguments.
• The output file (-o) takes a single text argument.
• The input file (-i) takes multiple text arguments.

This is the Setup function that parses the command line:

  // Copyright (C) 1995 Taligent, Inc. All rights reserved.
  void TSampleObjectParmTest::Setup()
  
  //    Setup reads input arguments of the form:
  //    
  //        [-s <sampleCount>] [-l] [-o <outputfile>] [-i <inputfiles>...]
  //    
  // The sample count must be in the range 1..256. The logging option (-l) does not take 
  // any arguments. 
  // The output file option (-o) takes a single text argument.  The input file option 
  // takes multiple text arguments.  If the arguments are not given, the default values 
  // that were set 
  // in the constructor remains unchanged. If a bad input is given or an invalid option 
  // is specified, the test fails.
  
  {
      const TStandardText kSampleCountKey("-s");
      const TStandardText kOutputFileKey("-o");
      const TStandardText kLoggingKey("-l");
      const TStandardText kInputFilesKey("-i");
      const long kMinSampleCount = 1;
      const long kMaxSampleCount = 256;
  
      // Create dictionary object and pass it this test object and keys
      // Ssecond parameter to the constructor represents arguments that do not have values.
      // Third parameter to the constructor represents arguments that have multiple values. 
      TTextArgumentDictionary args(*this, kLoggingKey, kInputFilesKey);
  
      // Remove key-value pairs during lookup. Test owns text returned from lookup calls.
      args.RemoveOnLookup(true);
                                    
      try {
      // Call NumberAt to look up numbers corresponding to key and check if value is within 
      // specified range
          args.NumberAt(kSampleCountKey, fSampleCount, kMinSampleCount, kMaxSampleCount);
      }
      // If the number does not parse or is out of range, catch exception  
      catch(const TArgumentDictionaryLookupFailureException& obj) {
          OutputTextStream() << "Bad input for " << kSampleCountKey << " option.\n";
          SetSuccess(false); // Bad input
      }
  
      // Test owns text returned from following lookup calls to TextAt and MultipleValuesAt.
      TText *text;
      
      // Look up the value for kOutputFileKey (-o).  If an argument was specified, copy the 
      // retrieved value (text) to fOutputFileName.  Because RemoveOnLookup has been set
      // above, the test owns the text returned, so the test needs to delete it to 
      // clean up the storage.
      if (text = args.TextAt(kOutputFileKey)) {
          fOutputFileName = *text;                            
          delete text;    // don't need the text; delete it.
      }
  
      // Look up the value for kLoggingKey (-l).  Because this is a naked option, 
      // TextAt returns a pointer to an empty text object, if the argument was specified, or 
      // NIL, if the argument was not specified.
      // The test still needs to clean up the storage because RemoveOnLookup has been set.
      if (text = args.TextAt(kLoggingKey)) {
          fIsLogging = true;                                    
          delete text;    // don't need the text; delete it.
      }
  
      // Retrieves the collection of values associated with the kInputFilesKey (-i)
      // and adds the values to the collection fKeywords.  The test owns the text values
      // that are added to the collection because RemoveOnLookup has been set.
      args.MultipleValuesAt(kInputFilesKey, fKeywords);        
  
      // Check for invalid arguments.
      // Any arguments left in the argument dictionary are invalid because the test has 
      // parsed and removed all the valid arguments from the dictionary.  Here, the test 
      // checks to make sure that the argument dictionary contains no more arguments and is 
      // empty. If any arguments are left, print out an error message and fail the test.
      if (args.CountOfArguments() != 0) {
          TStandardText badArguments;
          args.ExportTextArguments(badArguments);
          OutputTextStream() << "Unknown options specified: " << badArguments << "\n";
          SetSuccess(false);
      }
  }