OPUS API Class: Oresource

Oresource - OPUS Oresource File Class

Availability:

This class is available for the OPUS Blackboard API. The initial OPUS 2.0 release is described here

Constructors:

Oresource( )
~Oresource( )

Methods:

get_value( ) get keyword value
load( ) load indicated file load indicated object
is_loaded( ) check state of object
source( ) Return name of source file
begin( ) Return iterator to first item in object
end( ) Return iterator to one past the last item in the object
get_class( )
get class of keyword value pairs
purge( ) delete contents of map if loaded
add_item( ) add new key/value pair to map
remove_item( ) remove key/value pair from map given key
size( ) return number of entries in object
report( ) write contents of an object to stream
test_driver( ) test driver

Description

The Oresource class implements a general container for the contents of OPUS resource files. OPUS uses this class to access data in process resource files, path files, etc.

Example

  
    
    OResource path(path_file_name)
    cout << "Inpath directory "<< path.lookup_value("INPATH")<<endl;
    cout << "Number of max blocks " << path.lookup_value("MAXBLOCKS")<<endl;

See Also:

"OPUS API Blackboard and Support Classes Design Document"

Oresource::Oresource - The Oresource object constructor.

Synopsis

Oresource::Oresource(const char  optional_separator,
		     const char  optional_delimeter) 

Oresource::Oresource(
                   const string& f, // I - full file spec of file to load
		   const char  optional_separator,
		   const char  optional_delimeter)   

Oresource::Oresource(
                   const Ofile& f, // I - object containing file to load
		   const char  optional_separator,
		   const char  optional_delimeter)

Description

Creates a Oresource object. The user can either create an empty object or load the object via a filename or Ofile object argument. The Oresource constructor allows the user to choose keyword, value, and comment separators. Default values are used if no separators are selected.

Exceptions Thrown

No_entry - if file does not exist
Corrupt - if Oresource file is corrupt
Io_error - if file error encountered loading file
Bad_val<string> - if the stretch cannot be resolved; Bad_val.arg contains the stretched file name
Bad_val<vector<string>> - if the calling arguments are incorrect; Bad_val.arg is a vector containing the calling arguments
Io_error<int> - if the disk space check fails; Io_error.arg contains the value of errno
Bad_val<vector<string>> - if calling arguments are incorrect; Bad_val.arg is a vector containing the calling arguments
Exec<int> - if the subprocess spawn attempt fails; Exec.arg contains the return status from the spawn attemp

Example

  
    Oresource path("/leo/opus/definitions/red.path");
    Oresource empty();
    Oresource path("/leo/opus/definitions/red.path",'+','=');

Oresource::~Oresource - The Oresource object destructor.

Synopsis

Oresource::~Oresource()

Description

A no-op.

Exceptions Thrown

none

Oresource::load - Loads the resource file into the object.

Synopsis

void Oresource::load(const string& fname) // I - file to load

void Oresource::load(const Ofile& f) // I - file to load

Description

Loads the keyword/value pairs from a file into the Oresource object.

Exceptions Thrown

No_entry - if file does not exist
Corrupt - if Oresource file is corrupt
Io_error - if file error encountered loading file

Example

  
    path.load("/leo/opus/definitions/red.path");

Oresource::is_loaded - Returns load status of object.

Synopsis

bool Oresource::is_loaded() const

Description

Tells the user if the Oresource object has been loaded with a file of keyword/value pairs.

Returns

true - if object loaded.

false - if object not loaded.

Exceptions Thrown

none

Example

  
    if (path.is_loaded) cout << "Path file already loaded"<<endl;

Oresource::source - Returns the file specification for the file used to load the object.

Synopsis

string Oresource::source() const

Description

Tells the user the name of the file used to load the object.

Returns

File specification.

Exceptions Thrown

Not_ready - if no file loaded

Example

  
    cout << path.source() << " was loaded into Oresource object"<<endl;

Oresource::get_class - Allows the user to gather all keyword/value pairs that start with the same prefix.

Synopsis

void Oresource::get_class(
                         const string& key,        // I   - class
                         map<string, string>& res) // I/O - results map
                         const

void Oresource::get_class(
                         const char* key,          // I   - class
                         map<string, string>& res) // I/O - results map
                         const

Description

Returns the remaining portion of the key and the value in the supplied map given a class in the key of the form:

key. or

.key

Multiple matches are possible.

Exceptions Thrown

No_entry - if matching entry not found
Not_ready - if file not loaded

Example

  
    Oresource resource(file_name);
    map <string, string> success;
    resource.get_class("OSF_SUCCESS.",success);
    cout<<"keyword value pairs for OSF_SUCCESS state are "
	  << sucess
	  << endl;

Oresource::purge - Empties container.

Synopsis

void Oresource::purge()

Description

Allows the user to empty the Oresource object

Exceptions Thrown

Not_ready - if file not loaded

Example

	path.purge();

Oresource::add_item - Adds a unique key and its value to the map.

Synopsis

void Oresource::add_item(
                        const string& key, // I - key to add
                        const string& val) // I - key value

void Oresource::add_item(
                        const char* key,   // I - key to add
                        const string& val) // I - key value

Description

Allows the user to add keyword/ value pairs to the Oresource object.

Exceptions Thrown

Bad_val - if key already exists in map.

Example

  
    path.add_item("INPATH","/home/");

Oresource::remove_item - Removes a key and its value from the map.

Synopsis

void Oresource::remove_item(
                           const string& key) // I - the key to remove

void Oresource::remove_item(
                           const char* key) // I - the key to remove

Description

Allows the user to add keyword/ value pairs to the Oresource object.

Exceptions Thrown

No_entry - if key not in map.
Not_ready - if file not loaded

Example

  
    path.remove_item("INPATH");

Oresource::report - Reports on contents of Oresource file object.

Synopsis

void Oresource::report(ostream &outs) const

Description

Allows the user to display the Oresource object entries to an output stream.

Exceptions Thrown

Not_ready - if Oresource object not loaded

Example

  
      ofstream file(file_name.c_str());
      path1.report(file);

Oresource::test_driver - Tests the methods of the Oresource class.

Synopsis

bool Oresource::test_driver(const string& file_name)

Description

Tests the methods of the Oresource class.

Returns

true - successfully tested Oresource methods.

false - failed testing of Oresource method.

Exceptions Thrown

None

Example

  
    status = path.test_driver(temp_file_name);

Oresource::begin - Get an iterator that points to the beginning of the resource list.

Synopsis

Oresource::iterator Oresource::begin()

Oresource::const_iterator Oresource::begin() const

Description

An iterator initialized with the beginning of the resource list is created and returned to the caller. The iterator points to an instance of pair. Be aware that future calls to other methods (e.g., remove_item) might invalidate an iterator returned by this method.

Returns

    An iterator that points to a pair<string, string> object.

Exceptions Thrown

none

Oresource::end - Get an iterator that points to one past the end of the resource list.

Synopsis

Oresource::iterator Oresource::end()

Oresource::const_iterator Oresource::end() const

Description

An iterator initialized with one past the end of the resource list is created and returned to the caller. Be aware that future calls to other methods (e.g., add_item) might invalidate an iterator returned by this method.

Returns

An iterator that points to one past the end of the object's contents.

Exceptions Thrown

none

Oresource::size - Get the number of entries in the loaded object.

Synopsis

int Oresource::size() const

Description

The number of keyword/value pairs loaded in the object is returned.

Returns

The number of entries in the object.

Exceptions Thrown

Not_ready<void*> - if object has not been loaded; Not_ready.arg contains 0

Oresource::get_value - Returns the value associated with the provided key.

Synopsis

   void Oresource::get_value(const std::string &key, Result &r) const
   {
	std::string entry;			// Value as a string
	entry = lookup_value(key);	// Lookup value in Oresource object
	try { 
	  Str_to_num cv(entry);
	  cv.convert(r);	// Convert value to required type
        catch (...) {
          Msg m;
            m << sev(Msg::E) << type(Msg::BADVAL)   <<
            "Failed to convert" << key << " value, "<<
             entry << " to desired type " << endl << endm;
          throw Bad_val<std::string>(key);
   }
   template <class Result> 
   void Oresource::get_value(const char *key, Result &r) const
   {
     if (key==NULL) {
       Msg m;
       std::string s("blank");
       m << sev(Msg::D) << type(Msg::MISSING) << "Blank keyword passed "
        << endm;
       throw No_entry<std::string>(s);
     }
     std::string keyword(key);
     get_value(keyword,r);
   }

Description

Allows the user to access the keyword values in the Oresource object. This is a template function that allows the user to use any type variables to access entries in the Oresource object.

Exceptions Thrown

No_entry - if no value is found for that key
Not_ready - if file not loaded
Bad_val - value cannot be expressed as desired type.

Example

     Oresource path2(file_name);
     std::string c("MINBLOCKS");
     int    i;
     std::string test;
     path2.get_value(c,i);
     path2.get_value(c,test);
     if (i != atoi(test.c_str())  cout << "Error" << endl;

OPUS API index · STScI Home Page · Search · Topics · Index

For more information, contact opushelp@stsci.edu

Last modified: 25 April 2000

get_value( )	get keyword value
load( )	load indicated file load indicated object
is_loaded( )	check state of object
source( )	Return name of source file
begin( )	Return iterator to first item in object
end( )	Return iterator to one past the last item in the object
get_class( )
	get class of keyword value pairs
purge( )	delete contents of map if loaded
add_item( )	add new key/value pair to map
remove_item( )	remove key/value pair from map given key
size( )	return number of entries in object
report( )	write contents of an object to stream
test_driver( )	test driver

No_entry	- if file does not exist
Corrupt	- if Oresource file is corrupt
Io_error	- if file error encountered loading file
Bad_val<string>	- if the stretch cannot be resolved; Bad_val.arg contains the stretched file name
Bad_val<vector<string>>	- if the calling arguments are incorrect; Bad_val.arg is a vector containing the calling arguments
Io_error<int>	- if the disk space check fails; Io_error.arg contains the value of errno
Bad_val<vector<string>>	- if calling arguments are incorrect; Bad_val.arg is a vector containing the calling arguments
Exec<int>	- if the subprocess spawn attempt fails; Exec.arg contains the return status from the spawn attemp

No_entry	- if matching entry not found
Not_ready	- if file not loaded

No_entry	- if no value is found for that key
Not_ready	- if file not loaded
Bad_val	- value cannot be expressed as desired type.