MOOCHO (Single Doxygen Collection) Version of the Day
OptionsFromStreamPack_OptionsFromStream.hpp
Go to the documentation of this file.
00001 // @HEADER
00002 // ***********************************************************************
00003 // 
00004 // Moocho: Multi-functional Object-Oriented arCHitecture for Optimization
00005 //                  Copyright (2003) Sandia Corporation
00006 // 
00007 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00008 // license for use of this work by or on behalf of the U.S. Government.
00009 // 
00010 // Redistribution and use in source and binary forms, with or without
00011 // modification, are permitted provided that the following conditions are
00012 // met:
00013 //
00014 // 1. Redistributions of source code must retain the above copyright
00015 // notice, this list of conditions and the following disclaimer.
00016 //
00017 // 2. Redistributions in binary form must reproduce the above copyright
00018 // notice, this list of conditions and the following disclaimer in the
00019 // documentation and/or other materials provided with the distribution.
00020 //
00021 // 3. Neither the name of the Corporation nor the names of the
00022 // contributors may be used to endorse or promote products derived from
00023 // this software without specific prior written permission.
00024 //
00025 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
00026 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00027 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00028 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
00029 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00030 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00031 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00032 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00033 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00034 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00035 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00036 //
00037 // Questions? Contact Roscoe A. Bartlett (rabartl@sandia.gov) 
00038 // 
00039 // ***********************************************************************
00040 // @HEADER
00041 
00042 #ifndef OPTIONS_FROM_STREAM_H
00043 #define OPTIONS_FROM_STREAM_H
00044 
00045 #include "Moocho_ConfigDefs.hpp"
00046 
00047 // /////////////////////////////////////////////////
00048 // Forward declarations.
00049 
00050 namespace OptionsFromStreamPack {
00051   namespace OptionsFromStreamUtilityPack {
00052 
00053     // Simple class for a boolean variable that is false on construction.
00054     class false_bool_t {
00055     public:
00056       false_bool_t() : val_(false) {}
00057       void set(bool val) { val_ = val; }
00058       operator bool() const { return val_; }
00059     private:
00060       bool val_;
00061     };
00062 
00063     // Implementation type for the map for looking up a value given
00064     // a an options name.
00065     typedef std::map< std::string , std::string >     option_to_value_map_t;
00066 
00067     // Implementation type for an options group's options and
00068     // a boolean variable to determine if this option has been visited yet.
00069     typedef std::pair< option_to_value_map_t, false_bool_t >  options_group_pair_t;
00070 
00071     // Implementation type of the map for looking up a set of options
00072     // given the option groups name.
00073     typedef std::map< std::string, options_group_pair_t > options_group_map_t;
00074 
00075     // The above declarations sets up the data structure:
00076     // 
00077     //       map<string,options_group_pair_t> (options_group_map_t)
00078     //                  |
00079     //                  | value_type
00080     //                 `.'
00081     //       pair<string,options_group_pair_t> 
00082     //                  |
00083     //       -----------------------              
00084     //      |                       |         
00085     //      | first                 | second
00086     //     `.'                     `.'
00087     //    string         pair<option_to_value_map_t,false_bool_t> (options_group_pair_t)
00088     //      |                      |
00089     // "solver_options"            |
00090     //                             |
00091     //        ------------------------------------------------
00092     //       |                                                |
00093     //       | first                                          | second
00094     //      `.'                                              `.'
00095     //    map<string,string> (option_to_value_map_t)       false_bool_t
00096     //       |                                                |
00097     //       | value_type                                   "true"
00098     //      `.'
00099     // pair<string,string>
00100     //       |
00101     //     --------------
00102     //    | first        | second
00103     //   `.'            `.'
00104     //  string         string
00105     //    |              |    
00106     //  "tol"          "1e-6"
00107     //  
00108 
00109     class OptionsGroup;
00110   }
00111   class OptionsFromStream;
00112 }
00113 
00114 // //////////////////////////////////////////////////
00115 // Class and function declarations
00116 
00117 namespace OptionsFromStreamPack {
00118 
00119 /* \defgroup OptionsFromStreamPack_grp Untilities for maintianing a simple options database.
00120  * \ingroup Misc_grp
00121  * 
00122  */
00123 // @ {
00124 
00125 namespace OptionsFromStreamUtilityPack {
00126 
00229 class OptionsGroup {
00230 public:
00231 
00232   // friends
00233   friend class OptionsFromStream;
00234 
00237 
00239   typedef option_to_value_map_t::iterator     iterator;
00241   typedef option_to_value_map_t::const_iterator const_iterator;
00242 
00244 
00251 
00253 
00260 
00262   std::string& option_value( const std::string& option_name );
00264   const std::string& option_value( const std::string& option_name ) const;
00265 
00267 
00269   static bool option_exists( const std::string& option_value );
00270 
00272   bool options_group_exists() const;
00273 
00276 
00278   int       num_options() const;
00280   iterator    begin();
00282   iterator    end();
00284   const_iterator  begin() const;
00286   const_iterator  end() const;
00287 
00289 
00290 private:
00291   
00292   option_to_value_map_t*  option_to_value_map_; // 0 used for no options group.
00293   static std::string    option_does_not_exist_;
00294 
00295   // Not defined and not to be called
00296   OptionsGroup();
00297   OptionsGroup& operator=(const OptionsGroup&);
00298 
00299 public:
00300   // Is given zero by OptionsFromStream to signify the option group does't exist.
00301   // It is put here to keep it away from the eyes of the general user.
00302   OptionsGroup( option_to_value_map_t* option_to_value_map )
00303     : option_to_value_map_(option_to_value_map)
00304   {}
00305 
00306 };  // end class OptionsGroup
00307 
00308 inline
00310 const std::string& option_name( OptionsGroup::const_iterator& itr ) {
00311   return (*itr).first;
00312 }
00313 
00314 inline
00316 const std::string& option_value( OptionsGroup::const_iterator& itr ) {
00317   return (*itr).second;
00318 }
00319 
00320 
00321 // @ }
00322 
00323 } // end namespace OptionsFromStreamUtilityPack 
00324 
00325 
00422 class OptionsFromStream {
00423 public:
00424 
00427 
00429   typedef OptionsFromStreamUtilityPack::options_group_map_t::iterator     iterator;
00431   typedef OptionsFromStreamUtilityPack::options_group_map_t::const_iterator const_iterator;
00432 
00434   typedef OptionsFromStreamUtilityPack::OptionsGroup              options_group_t;
00435 
00437   class InputStreamError : public std::logic_error
00438   {public: InputStreamError(const std::string& what_arg) : std::logic_error(what_arg) {}};
00439 
00441 
00448 
00450   OptionsFromStream();
00451 
00457   explicit OptionsFromStream( std::istream& in );
00458 
00460   void clear_options();
00461 
00475   void read_options( std::istream& in );
00476 
00478 
00483   void print_options( std::ostream& out ) const;
00484 
00492 
00494   options_group_t options_group( const std::string& options_group_name );
00496   const options_group_t options_group( const std::string& options_group_name ) const;
00497 
00499 
00501   static bool options_group_exists( const options_group_t& options_group );
00502 
00512 
00514   void reset_unaccessed_options_groups();
00515 
00517   void print_unaccessed_options_groups( std::ostream& out ) const;
00518 
00520 
00523 
00525   int       num_options_groups() const;
00527   iterator    begin();
00529   iterator    end();
00531   const_iterator  begin() const;
00533   const_iterator  end() const;
00534 
00536 
00537 private:
00538   typedef OptionsFromStreamUtilityPack::false_bool_t      false_bool_t;
00539   typedef OptionsFromStreamUtilityPack::option_to_value_map_t option_to_value_map_t;
00540   typedef OptionsFromStreamUtilityPack::options_group_map_t options_group_map_t;
00541   options_group_map_t                     options_group_map_;
00542 
00543 };  // end class OptionsFromStream
00544 
00546 inline
00547 const std::string&
00548 options_group_name( OptionsFromStream::const_iterator& itr )
00549 {
00550   return (*itr).first;
00551 }
00552 
00554 inline
00555 const OptionsFromStream::options_group_t
00556 options_group( OptionsFromStream::const_iterator& itr )
00557 {
00558   return OptionsFromStream::options_group_t(
00559     const_cast<OptionsFromStreamUtilityPack::option_to_value_map_t*>(&(*itr).second.first) );
00560 }
00561 
00562 
00563 // @ }
00564 
00565 /* @name Return the name or value of an option from an OptionsGroup iterator. */
00566 // @ {
00567 
00568 //
00569 using OptionsFromStreamUtilityPack::option_name;
00570 //
00571 using OptionsFromStreamUtilityPack::option_value;
00572 
00573 // @ }
00574 
00575 //  end namespace OptionsFromStreamPack 
00576 // @ }
00577 
00578 } // end namespace OptionsFromStreamPack
00579 
00580 // //////////////////////////////////////////////////////////////////////////////////////////
00581 // Inline definitions.
00582 
00583 namespace OptionsFromStreamPack {
00584 
00585 namespace OptionsFromStreamUtilityPack {
00586 
00587 // class OptionsGroup.
00588 
00589 inline
00590 std::string& OptionsGroup::option_value( const std::string& option_name ) {
00591   option_to_value_map_t::iterator itr = option_to_value_map_->find( option_name );
00592   return ( itr != option_to_value_map_->end() ? (*itr).second : option_does_not_exist_ );
00593 }
00594 
00595 inline
00596 const std::string& OptionsGroup::option_value( const std::string& option_name ) const {
00597   option_to_value_map_t::const_iterator itr = option_to_value_map_->find( option_name );
00598   return ( itr != option_to_value_map_->end() ? (*itr).second : option_does_not_exist_ );
00599 }
00600 
00601 inline
00602 bool OptionsGroup::option_exists( const std::string& option_value ) {
00603   return &option_value != &option_does_not_exist_;
00604 }
00605 
00606 inline
00607 bool OptionsGroup::options_group_exists() const {
00608   return option_to_value_map_ != 0;
00609 }
00610 
00611 inline
00612 int OptionsGroup::num_options() const {
00613   return option_to_value_map_->size();
00614 }
00615 
00616 inline
00617 OptionsGroup::iterator    OptionsGroup::begin() {
00618   return option_to_value_map_->begin();
00619 }
00620 
00621 inline
00622 OptionsGroup::iterator    OptionsGroup::end() {
00623   return option_to_value_map_->end();
00624 }
00625 
00626 inline
00627 OptionsGroup::const_iterator  OptionsGroup::begin() const {
00628   return option_to_value_map_->begin();
00629 }
00630 
00631 inline
00632 OptionsGroup::const_iterator  OptionsGroup::end() const {
00633   return option_to_value_map_->end();
00634 }
00635 
00636 } // end namespace OptionsFromStreamPack
00637 
00638 // class OptionsFromStream
00639 
00640 inline
00641 OptionsFromStream::OptionsFromStream()
00642 {}
00643 
00644 inline
00645 OptionsFromStream::OptionsFromStream( std::istream& in ) {
00646   read_options(in);
00647 }
00648 
00649 inline
00650 void OptionsFromStream::clear_options() {
00651   options_group_map_.clear();
00652 }
00653 
00654 inline
00655 bool OptionsFromStream::options_group_exists( const options_group_t& options_group )
00656 {
00657   return options_group.options_group_exists();
00658 }
00659 
00660 inline
00661 int OptionsFromStream::num_options_groups() const {
00662   return options_group_map_.size();
00663 }
00664 
00665 inline
00666 OptionsFromStream::iterator OptionsFromStream::begin() {
00667   return options_group_map_.begin();
00668 }
00669 
00670 inline
00671 OptionsFromStream::iterator OptionsFromStream::end() {
00672   return options_group_map_.end();
00673 }
00674 
00675 inline
00676 OptionsFromStream::const_iterator OptionsFromStream::begin() const {
00677   return options_group_map_.begin();
00678 }
00679 
00680 inline
00681 OptionsFromStream::const_iterator OptionsFromStream::end() const {
00682   return options_group_map_.end();
00683 }
00684 
00685 } // end namespace OptionsFromStreamPack
00686 
00687 #endif  // OPTIONS_FROM_STREAM_H
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines