FileOptions.hpp

Go to the documentation of this file.

/*
 * MOAB, a Mesh-Oriented datABase, is a software component for creating,
 * storing and accessing finite element mesh data.
 *
 * Copyright 2004 Sandia Corporation. Under the terms of Contract
 * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government
 * retains certain rights in this software.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 */
 
/**\file FileOptions.hpp
 *\author Jason Kraftcheck ([email protected])
 *\date 2007-08-21
 */
 
#ifndef FILE_OPTIONS_HPP
#define FILE_OPTIONS_HPP
 
#include <string>
#include <vector>
#include "moab/Types.hpp"
 
namespace moab
{
 
/**\brief Parse options string passed to file IO routines
 *
 * This is a utility class used by file-IO-related code to
 * parse the options string passed to Core::load_file and
 * Core::write_file
 */
class MOAB_EXPORT FileOptions
{
 public:
 /*\param options_string The concatenation of a list of
 * options, separated either by the default separator
 * (semicolon) with a custom separator specified at
 * the beginning of the string (semicolon followed by
 * destired separator character.)
 */
 FileOptions( const char* option_string );
 
 FileOptions( const FileOptions& copy );
 FileOptions& operator=( const FileOptions& copy );
 
 ~FileOptions();
 
 /**\brief Check for option with no value
 *
 * Check for an option w/out a value.
 *\param name The option name
 *\return - MB_SUCCESS if option is found
 * - MB_TYPE_OUT_OF_RANGE if options is found, but has value
 * - MB_ENTITY_NOT_FOUND if option is not found.
 */
 ErrorCode get_null_option( const char* name ) const;
 
 /**\brief Check for option with boolean (true/false, yes/no) value.
 *
 * Check for an option with a true/false value. Allowable values
 * are "true", "false", "yes", "no", "1", "0", "on", "off".
 *\param name The option name
 *\param default_value The value to return if the option is not specified.
 *\param value The resulting value. This argument is set to the passed
 * default value if the option is not found.
 *\return - MB_TYPE_OUT_OF_RANGE if options is found, but has an invalid value
 * - MB_SUCCESS otherwise
 */
 ErrorCode get_toggle_option( const char* name, bool default_value, bool& value ) const;
 
 /**\brief Check for option with an integer value.
 *
 * Check for an option with an integer value
 *\param name The option name
 *\param value Output. The value.
 *\return - MB_SUCCESS if option is found
 * - MB_TYPE_OUT_OF_RANGE if options is found, but does not have an integer value
 * - MB_ENTITY_NOT_FOUND if option is not found.
 */
 ErrorCode get_int_option( const char* name, int& value ) const;
 
 /**\brief Check for option with an integer value. Accept option with no value.
 *
 * Check for an option with an integer value.
 * If the option is found but has no value specified, then
 * pass back the user-specified default value.
 *
 *\NOTE: This function will not pass back the default_val, but will instead
 * return MB_ENTITY_NOT_FOUND if the option is not specified at all.
 * The default value is returned only when the option is specified,
 * but is specified w/out a value.
 *
 *\param name The option name
 *\param default_val The default value for the option.
 *\param value Output. The value.
 *\return - MB_SUCCESS if option is found
 * - MB_TYPE_OUT_OF_RANGE if options is found but has a value that cannot be parsed as an
 *int
 * - MB_ENTITY_NOT_FOUND if option is not found.
 */
 ErrorCode get_int_option( const char* name, int default_val, int& value ) const;
 
 /**\brief Check for option with a double value.
 *
 * Check for an option with a double value
 *\param name The option name
 *\param value Output. The value.
 *\return - MB_SUCCESS if option is found
 * - MB_TYPE_OUT_OF_RANGE if options is found, but does not have a double value
 * - MB_ENTITY_NOT_FOUND if option is not found.
 */
 ErrorCode get_real_option( const char* name, double& value ) const;
 
 /**\brief Check for option with any value.
 *
 * Check for an option with any value.
 *\param name The option name
 *\param value Output. The value.
 *\return - MB_SUCCESS if option is found
 * - MB_TYPE_OUT_OF_RANGE if options is found, but does not have a value
 * - MB_ENTITY_NOT_FOUND if option is not found.
 */
 ErrorCode get_str_option( const char* name, std::string& value ) const;
 
 /**\brief Check for option
 *
 * Check for an option
 *\param name The option name
 *\param value The option value, or an empty string if no value.
 *\return MB_SUCCESS or MB_ENTITY_NOT_FOUND
 */
 ErrorCode get_option( const char* name, std::string& value ) const;
 
 /**\brief Check the string value of an option
 *
 * Check which of a list of possible values a string option contains.
 *\param name The option name
 *\param values A NULL-terminated array of C-style strings enumerating
 * the possible option values.
 *\param index Output: The index into <code>values</code> for the
 * option value.
 *\return MB_SUCCESS if matched name and value.
 * MB_ENTITY_NOT_FOUND if the option was not specified
 * MB_FAILURE if the option value is not in the input <code>values</code> array.
 */
 ErrorCode match_option( const char* name, const char* const* values, int& index ) const;
 
 /**\brief Check if an option matches a string value
 *
 * Check if the value for an option is the passed string.
 *\param name The option name
 *\param value The expected value.
 *\return MB_SUCCESS if matched name and value.
 * MB_ENTITY_NOT_FOUND if the option was not specified
 * MB_FAILURE if the option value doesn't match the passed string/
 */
 ErrorCode match_option( const char* name, const char* value ) const;
 
 /**\brief Check for option for which the value is a list of ints
 *
 * Check for an option which is an int list. The value is expected to
 * be a comma-separated list of int ranges, where an int range can be
 * either a single integer value or a range of integer values separated
 * by a dash ('-').
 *
 *\param name The option name
 *\param values Output. The list of integer values.
 *\return - MB_SUCCESS if option is found
 * - MB_TYPE_OUT_OF_RANGE if options is found, but does not contain an ID list
 * - MB_ENTITY_NOT_FOUND if option is not found.
 */
 ErrorCode get_ints_option( const char* name, std::vector< int >& values ) const;
 
 /**\brief Check for option for which the value is a list of doubles
 *
 * Check for an option which is a double list. The value is expected to
 * be a comma-separated list of double values
 *
 *\param name The option name
 *\param values Output. The list of double values.
 *\return - MB_SUCCESS if option is found
 * - MB_TYPE_OUT_OF_RANGE if options is found, but does not contain an ID list
 * - MB_ENTITY_NOT_FOUND if option is not found.
 */
 ErrorCode get_reals_option( const char* name, std::vector< double >& values ) const;
 
 /**\brief Check for option for which the value is a list of strings
 *
 * Check for an option which is a string list. The value is expected to
 * be a comma-separated list of string values, with no embedded spaces or commas.
 *
 *\param name The option name
 *\param values Output. The list of string values.
 *\return - MB_SUCCESS if option is found
 * - MB_TYPE_OUT_OF_RANGE if options is found, but does not contain a string list
 * - MB_ENTITY_NOT_FOUND if option is not found.
 */
 ErrorCode get_strs_option( const char* name, std::vector< std::string >& values ) const;
 
 /** number of options */
 inline unsigned size() const
 {
 return mOptions.size();
 }
 
 /** true if no options */
 inline bool empty() const
 {
 return mOptions.empty();
 }
 
 /** Get list of options */
 void get_options( std::vector< std::string >& list ) const;
 
 /** Check if all options have been looked at */
 bool all_seen() const;
 
 /** Mark all options as seen. USed for non-root procs during bcast-delete read */
 void mark_all_seen() const;
 
 /** Get first unseen option */
 ErrorCode get_unseen_option( std::string& value ) const;
 
 private:
 /**\brief Check for option
 *
 * Check for an option
 *\param name The option name
 *\param value The option value, or an empty string if no value.
 *\return MB_SUCCESS or MB_ENTITY_NOT_FOUND
 */
 ErrorCode get_option( const char* name, const char*& value ) const;
 
 char* mData;
 std::vector< const char* > mOptions;
 mutable std::vector< bool > mSeen;
 
 /** Case-insensitive compare of name with option value. */
 static bool compare( const char* name, const char* option );
};
 
} // namespace moab
 
#endif