Added some comments to this example

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%402499

examples/compress_stream_ex.cpp

@@ -28,18 +28,17 @@
 #include <iostream>
 #include <fstream>
 #include <string>
-#include <iomanip>
 
-// I am making a typedef for the verson of compress_stream I want to use.
+// I am making a typedef for the version of compress_stream I want to use.
 // I have selected kernel_1ec.
 typedef dlib::compress_stream::kernel_1ec cs;
 
-// Here I am making another typedef, this time for the verson of
-// cmd_line_parser I want to use.  I have selected print_1a_c,
-// this is the version of kernel_1a that checks all its 
-// preconditions (i.e. the debugging version) and is 
-// extended by print_kernel_1. 
-typedef dlib::cmd_line_parser<char>::print_1a_c clp;
+// Here I am making another typedef, this time for the version of
+// cmd_line_parser I want to use.  This version gives me a
+// command line parser object that has all the available extensions
+// for command line parsers applied to it.  So I will be able to use
+// its command line validation utilities as well as option printing.
+typedef dlib::cmd_line_parser<char>::check_1a_c clp;
 
 
 using namespace std;
@@ -53,34 +52,57 @@ int main(int argc, char** argv)
         clp parser;
         cs compressor;
 
-        // first I will define the command line options I want
+        // first I will define the command line options I want.  
+        // Add a -c option and tell the parser what the option is for.
         parser.add_option("c","Indicates that we want to compress a file.");
         parser.add_option("d","Indicates that we want to decompress a file.");
+        // add a --in option that takes 1 argument
         parser.add_option("in","This option takes one argument which specifies the name of the file we want to compress/decompress.",1);
+        // add a --out option that takes 1 argument
         parser.add_option("out","This option takes one argument which specifies the name of the output file.",1);
         parser.add_option("h","Display this help message.");
 
+
         // now I will parse the command line
         parser.parse(argc,argv);
 
+
+        // Now I will use the parser to validate some things about the command line.
+        // If any of the following checks fail then an exception will be thrown and it will
+        // contain a message that tells the user the problem was.
+
+        // First I want to check that none of the options were given on the command line
+        // more than once.  To do this I define an array that contains the options
+        // that shouldn't appear more than once and then I just call check_one_time_options()
+        const char* one_time_opts[] = {"c", "d", "in", "out", "h"};
+        parser.check_one_time_options(one_time_opts);
+        // Here I'm checking that the user didn't pick both the c and d options at the
+        // same time. 
+        parser.check_incompatible_options("c", "d");
+
+
         // check if the -h option was given on the command line
         if (parser.option("h"))
         {
             // display all the command line options
             cout << "Usage: dclib_example (-c|-d) --in input_file --out output_file\n";
-            parser.print_options(cout); // this print_options() function is really 
-                                        // convenient :)
+            // This function prints out a nicely formatted list of
+            // all the options the parser has
+            parser.print_options(cout); 
+                                       
             cout << endl;
             return 0;
         }
 
+        // Make some references to the options inside the parser.  This is just
+        // for convenience so we don't have to type out he longer form below.  
         const clp::option_type& option_c = parser.option("c");
         const clp::option_type& option_d = parser.option("d");
         const clp::option_type& option_in = parser.option("in");
         const clp::option_type& option_out = parser.option("out");
 
-        if ((option_c.count() != 0 && option_d.count() != 0 ) || 
-            (option_c.count() == 0 && option_d.count() == 0 ) )
+        // make sure one of the c or d options was given
+        if (!option_c && !option_d)
         {
             cout << "Error in command line:\n   You must specify either the c option or the d option.\n";
             cout << "\nTry the -h option for more information." << endl;
@@ -93,16 +115,10 @@ int main(int argc, char** argv)
 
         // check if the user told us the input file and if they did then 
         // get the file name
-        if (option_in.count() == 1)
+        if (option_in)
         {
             in_file = option_in.argument();
         }
-        else if (option_in.count() > 1)
-        {
-            cout << "Error in command line:\n   You must specify only one input file.\n";
-            cout << "\nTry the -h option for more information." << endl;
-            return 0;
-        }
         else
         {
             cout << "Error in command line:\n   You must specify an input file.\n";
@@ -113,16 +129,10 @@ int main(int argc, char** argv)
 
         // check if the user told us the output file and if they did then 
         // get the file name
-        if (option_out.count() == 1)
+        if (option_out)
         {
             out_file = option_out.argument();
         }
-        else if (option_out.count() > 1)
-        {
-            cout << "Error in command line:\n   You must specify only one output file.\n";
-            cout << "\nTry the -h option for more information." << endl;
-            return 0;
-        }
         else
         {
             cout << "Error in command line:\n   You must specify an output file.\n";
@@ -131,9 +141,11 @@ int main(int argc, char** argv)
         }
 
 
+        // open the files we will be reading from and writing to
         ifstream fin(in_file.c_str(),ios::binary);
         ofstream fout(out_file.c_str(),ios::binary);
 
+        // make sure the files opened correctly
         if (!fin)
         {
             cout << "Error opening file " << in_file << ".\n";