mspass::utility::AntelopePf Class Reference

C++ object version of a parameter file. More...

#include <AntelopePf.h>

Inheritance diagram for mspass::utility::AntelopePf:

Public Member Functions
	AntelopePf ()
	AntelopePf (std::string pfbase)
	Construct from a base pf name. More...
	AntelopePf (std::list< std::string > lines)
	Construct from a set of text lines. More...
	AntelopePf (const AntelopePf &parent)
std::list< std::string >	get_tbl (const std::string key) const
	get a Tbl component by key. More...
AntelopePf	get_branch (const std::string key) const
	used for subtrees (nested Arrs in antelope) More...
std::list< std::string >	arr_keys () const
std::list< std::string >	tbl_keys () const
Metadata	ConvertToMetadata ()
	Return an object with only simple name:value pairs. More...
AntelopePf &	operator= (const AntelopePf &parent)
void	pfwrite (std::ostream &ofs)
	save result in a pf format. More...
Public Member Functions inherited from mspass::utility::Metadata
	Metadata ()
	Metadata (std::ifstream &ifs, const std::string form=std::string("pf"))
	Metadata (const Metadata &mdold)
virtual	~Metadata ()
Metadata &	operator= (const Metadata &mdold)
Metadata &	operator+= (const Metadata &rhs) noexcept
const Metadata	operator+ (const Metadata &other) const
double	get_double (const std::string key) const override
int	get_int (const std::string key) const override
long	get_long (const std::string key) const
std::string	get_string (const std::string key) const override
bool	get_bool (const std::string key) const override
template<typename T >
T	get (const std::string key) const
template<typename T >
T	get (const char *key) const
	Generic get interface for C char array. More...
boost::any	get_any (const std::string key) const
std::string	type (const std::string key) const
template<typename T >
void	put (const std::string key, T val) noexcept
template<typename T >
void	put (const char *key, T val) noexcept
void	put (const std::string key, const double val) override
void	put (const std::string key, const int val) override
void	put (const std::string key, const bool val) override
void	put (const std::string key, const std::string val) override
void	put (const char *key, const char *val)
void	put (std::string key, const char *val)
void	put_object (const std::string key, const pybind11::object val)
void	put_int (const std::string key, const int val)
void	put_string (const std::string key, const std::string val)
void	put_bool (const std::string key, const bool val)
void	put_double (const std::string key, const double val)
void	put_long (const std::string key, const long val)
void	append_chain (const std::string key, const std::string val, const std::string separator=std::string(":"))
std::set< std::string >	modified () const
void	clear_modified ()
	Mark all data as unmodified. More...
std::set< std::string >	keys () const noexcept
bool	is_defined (const std::string key) const noexcept
void	erase (const std::string key)
std::size_t	size () const noexcept
std::map< std::string, boost::any >::const_iterator	begin () const noexcept
std::map< std::string, boost::any >::const_iterator	end () const noexcept
void	change_key (const std::string oldkey, const std::string newkey)
	Change the keyword to access an attribute. More...

Additional Inherited Members
Protected Attributes inherited from mspass::utility::Metadata
std::map< std::string, boost::any >	md
std::set< std::string >	changed_or_set

Detailed Description

C++ object version of a parameter file.

This object encapsulates the Antelope concept of a parameter file in a single wrapper. The main constructor is actually act much like the Antelope pfread procedure. Internally this object does not use an antelope Pf at all directly, but it is a child of Metadata. Simple attributes (i.e. key-value pairs) are posted directly to the Metadata associative array (map) container. Note that the parser attempts to guess the type of each value given in the obvious ways (periods imply real numbers, e or E imply real numbers, etc.) but the algorithm used may not be foolproof. The get methods are from the Metadata object. Be warned like the Metadata object the type of an entry for a key can change and will be the last one set.
An Antelope Tbl in a pf file is converted to an stl list container of stl::string's that contain the input lines. This is a strong divergence from the tbl interface of Antelope, but one I judged a reasonable modernization. Similarly, Arr's are converted to what I am here calling a "branch". Branches are map indexed containers with the key pointing to nested versions of this sampe object type. This is in keeping with the way Arr's are used in antelope, but with an object flavor instead of the pointer style of pfget_arr. Thus, get_branch returns a AntelopePf object instead of a pointer that has to be memory managed. A final note about this beast is that the entire thing was created with a tacit assumption the object itself is not huge. i.e. this implementation may not scale well if applied to very large (millions) line pf files. This is a job for something like MongoDB. View this as a convenient format for building a Metadata object. Note, a code fragment to use this to create lower level metadata would go like this: AntelopePf pfdata("example"); //parameter file constructor Metadata md(dynamic_cast<Metadata&>(pfdata);

Author

Gary L. Pavlis, Indiana University

This version for MsPASS is derived from a similar thing called a PfStyleMetadata object in antelope contrib.

Constructor & Destructor Documentation

AntelopePf() [1/4]

mspass::utility::AntelopePf::AntelopePf ( )

inline

Default constructor - does nothing.

:Metadata(){};

AntelopePf() [2/4]

mspass::utility::AntelopePf::AntelopePf

(

std::string

pfbase

)

Construct from a base pf name.

This constructor acts like the antelope pfread function for parameter files constructed in plain C. That is, the argument is a base name sans the .pf extension. Like antelope's pfread it will follow the chain of directories defined by PFPATH. As with the antelope pfread procedure the last file read takes precendence. Note if PFPATH is not defined the path defaults to ".". Further if pfbase begins with a slash (i.e. "/") it is assumed to be the actual file name to read and the PFPATH feature is disabled.

Parameters

pfbase

is a the base pf name (always adds .pf to each name in PFPATH)

Exceptions

-	throws a MsPASSError object with an informative message if constuctor fails for any reason.

AntelopePf() [3/4]

mspass::utility::AntelopePf::AntelopePf

(

std::list< std::string >

lines

)

Construct from a set of text lines.

This is a cruder constructor that could be used for small pf file. Read the contents of a pf file into a vector of lines with each line being one line from the pf. The constructor then sequentially parses this series of lines as it would if reading from a file.

Parameters

lines

is the modified version of the text pf file.

AntelopePf() [4/4]

mspass::utility::AntelopePf::AntelopePf

(

const AntelopePf &

parent

)

Standard copy constructor.

    : Metadata(parent)
{
    pftbls=parent.pftbls;
    pfbranches=parent.pfbranches;
}

Member Function Documentation

arr_keys()

list< string > mspass::utility::AntelopePf::arr_keys

(

)

const

Return a list of keys for branches (Arrs) in the pf file.

{
    map<string,AntelopePf>::const_iterator iptr;
    list<string> result;
    for(iptr=pfbranches.begin(); iptr!=pfbranches.end(); ++iptr)
        result.push_back((*iptr).first);
    return result;
}

ConvertToMetadata()

Metadata mspass::utility::AntelopePf::ConvertToMetadata

(

)

Return an object with only simple name:value pairs.

The Metadata parent of this object only handles name:value pairs. The values can, however, be any object boost::any can handle.
The documentation says that means it is copy constructable.
For now this method returns an object containin the boost::any values. Any Arr and Tbl entries are pushed directly to the output Metadata using boost::any and the two keys defined as const strings at the top of this file (pftbl_key and pfarr_key).

Returns

Metadata sans any Arr and Tbl entries.

{
    try {
        Metadata result(dynamic_cast<Metadata&>(*this));
        boost::any aTbl=this->pftbls;
        //boost::any<map<string,list<string>> aTbl(this->pftbl);
        boost::any aArr=this->pfbranches;
        result.put<boost::any>(pftbl_key,aTbl);
        result.put<boost::any>(pfarr_key,aArr);
        return result;
    } catch(...) {
        throw;
    };
}

get_branch()

AntelopePf mspass::utility::AntelopePf::get_branch

(

const std::string

key

)

const

used for subtrees (nested Arrs in antelope)

This method is used for nested Arr constructs. This returns a copy of the branch defined by key attached to this object. The original from the parent is retained.

Parameters

key	is the key used to locate this branch.

Returns

a copy of the contents of the branch linked to key.

Exceptions

AntelopePfError

will be thrown if the key is not found.

{
    map<string,AntelopePf>::const_iterator iptr;
    iptr=pfbranches.find(key);
    if(iptr==pfbranches.end()) throw AntelopePfError(
            "get_branch failed trying to find data for key="+key);
    return iptr->second;
}

get_tbl()

list< string > mspass::utility::AntelopePf::get_tbl

(

const std::string

key

)

const

get a Tbl component by key.

Antelope has the idea of a tbl, which is a list of lines that are parsed independently. This is the get method to extract one of these by its key.

Parameters

key	is the key for the Tbl desired.

Exceptions

AntelopePfError

will be thrown if the key is not present.

{
    map<string,list<string> >::const_iterator iptr;
    iptr=pftbls.find(key);
    if(iptr==pftbls.end()) throw AntelopePfError(
            "get_tbl failed trying to find data for key="+key);
    return(iptr->second);
}

operator=()

AntelopePf & mspass::utility::AntelopePf::operator=

(

const AntelopePf &

parent

)

Standard assignment operator,

{
    if(this!=&parent)
    {
        /* This uses a trick to use operator = of the parent object */
        this->Metadata::operator=(parent);
        pftbls=parent.pftbls;
        pfbranches=parent.pfbranches;
    }
    return(*this);
}

References mspass::utility::Metadata::operator=().

pfwrite()

void mspass::utility::AntelopePf::pfwrite

(

std::ostream &

ofs

)

save result in a pf format.

This is functionally equivalent to the Antelope pfwrite procedure, but is a member of this object. A feature of the current implementation is that all simply type parameters will usually be listed twice in the output file. The reason is that the constructor attempts to guess type, but to allow for mistakes all simple parameters are also treated as string variables so get methods are more robust.

Parameters

ofs	is a std::ostream (e.g. cout) where the result will be written in pf style. Usually should end in ".pf".

tbl_keys()

list< string > mspass::utility::AntelopePf::tbl_keys

(

)

const

Return a list of keys for Tbls in the pf.

{
    map<string,list<string> >::const_iterator iptr;
    list<string> result;
    for(iptr=pftbls.begin(); iptr!=pftbls.end(); ++iptr)
        result.push_back((*iptr).first);
    return(result);
}

---

The documentation for this class was generated from the following files:

• /home/runner/work/mspass/mspass/cxx/include/mspass/utility/AntelopePf.h
• /home/runner/work/mspass/mspass/cxx/src/lib/utility/AntelopePf.cc