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

#include <AntelopePf.h>

Inheritance diagram for mspass::utility::AntelopePf:

[legend]

Collaboration diagram for mspass::utility::AntelopePf:

[legend]

Public Member Functions
	AntelopePf ()

	AntelopePf (std::string pfbase)
	Construct from a base pf name.

	AntelopePf (std::list< std::string > lines)
	Construct from a set of text lines.

	AntelopePf (const AntelopePf &parent)

std::list< std::string >	get_tbl (const std::string key) const
	get a Tbl component by key.

AntelopePf	get_branch (const std::string key) const
	used for subtrees (nested Arrs in antelope)

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.

AntelopePf &	operator= (const AntelopePf &parent)

void	pfwrite (std::ostream &ofs)
	save result in a pf format.

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.

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.

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.

template<>
double	get (const std::string key) const

template<>
int	get (const std::string key) const

template<>
long	get (const std::string key) const

template<>
bool	get (const std::string key) const

template<>
float	get (const std::string key) const

template<>
double	get (const string key) const

template<>
int	get (const string key) const

template<>
long	get (const string key) const

template<>
bool	get (const string key) const

template<>
float	get (const string key) const

Public Member Functions inherited from mspass::utility::BasicMetadata
virtual	~BasicMetadata ()

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.

64: Metadata() {};

mspass::utility::Metadata::Metadata

Metadata()

Definition Metadata.h:105

◆ 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. A relative base name is first read from the MsPASS data directory when available: MSPASS_HOME/data when MSPASS_HOME is set, or the installed mspasspy package data after the Python extension registers it. A standalone caller without MSPASS_HOME instead starts with the directories defined by PFPATH; if PFPATH is not defined, that path defaults to ".". As with the antelope pfread procedure, the last file read takes precedence, so PFPATH or the current directory can override the MsPASS data file. 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 the base pf name. Relative names may include or omit the .pf suffix; it is added when absent.

Exceptions

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

                                       {
  try {
    list<string> pffiles;
    const bool is_absolute = !pfbase.empty() && pfbase[0] == '/';
    string pfname(pfbase);
    if (!is_absolute && (pfname.size() < 3 ||
                         pfname.compare(pfname.size() - 3, 3, ".pf") != 0)) {
      pfname += ".pf";
    }
    if (!is_absolute) {
      try {
        pffiles.push_back(data_directory() + "/pf/" + pfname);
      } catch (const MsPASSError &) {
        /* A standalone C++ caller without MSPASS_HOME has no package data
         * directory.  Preserve the existing PFPATH/current-directory search.
         */
      }
    }
    const string envname("PFPATH");
    char *s = getenv(envname.c_str());
    /* Test to see if pfbase is an absolute path - if so just use
     * it and ignore the pfpath feature */
    if (is_absolute) {
      pffiles.push_back(pfbase);
    } else if (s == NULL) {
      pffiles.push_back(pfname);
    } else {
      list<string> pfpath_files = split_pfpath(pfname, s);
      pffiles.splice(pffiles.end(), pfpath_files);
    }
    list<string>::iterator pfptr;
    int nread;
 
    for (nread = 0, pfptr = pffiles.begin(); pfptr != pffiles.end(); ++pfptr) {
      // Skip pf files that do not exist
      if (access(pfptr->c_str(), R_OK))
        continue;
      if (nread == 0) {
        *this = pfread(*pfptr);
      } else {
        AntelopePf pfnext = pfread(*pfptr);
        this->merge_pfmf(pfnext);
      }
      ++nread;
    }
    if (nread == 0) {
      if (s == NULL) {
        // This was necessary to avoid seg faults when s was a null pointer
        // which happens when PFPATH is not set
        throw MsPASSError(string("PFPATH is not defined and default pf=") +
                              pfbase + " was not found",
                          ErrorSeverity::Invalid);
      } else {
        throw MsPASSError(string("PFPATH=") + s + " had no pf files matching " +
                              pfbase,
                          ErrorSeverity::Invalid);
      }
    }
  } catch (...) {
    throw;
  };
}

References mspass::utility::Metadata::get().

◆ 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.

                                                  : Metadata() {
  const string base_error("AntelopePf constructor:  ");
  list<string>::iterator lptr, end_block;
  list<string> block;
  string key, token2;
  try {
    for (lptr = alllines.begin(); lptr != alllines.end(); ++lptr) {
      int i, ival;
      int lines_this_block;
      /* This is redundant, but cost is low for long term stability*/
      if (is_comment_line(*lptr))
        continue;
      /* Older version used a stringstream here but it would not
         parse string attributes with embedded white space.  This
         revised algorithm will do that.  returned pair has the
         key as first and the string with the key trimmed in second. */
      /*
      istringstream is(*lptr);
      is>>key;
      is>>token2;
      */
      pair<string, string> sl = split_line(*lptr);
      key = sl.first;
      token2 = sl.second;
      PfStyleInputType type_of_this_line = arg_type(token2);
      switch (type_of_this_line) {
      /* Note all simple type variables are duplicated in
         as strings.  This is a failsafe mechanism used
         because Metadata will always fall back to string
         map if the type specific versions fail.   Realize
         if Metadata changes this will be wasted effort. */
      case PFMDSTRING:
        this->put(key, token2);
        break;
      case PFMDREAL:
        this->put(key, token2);
        this->put(key, atof(token2.c_str()));
        break;
      case PFMDINT:
        /* save ints as both string and int some string
           values could be all digits. */
        this->put(key, token2);
        this->put(key, atoi(token2.c_str()));
        break;
      case PFMDBOOL:
        ival = yesno(token2);
        if (ival != 0)
          this->put<bool>(key, true);
        else
          this->put<bool>(key, false);
        break;
      case PFMDTBL:
      case PFMDARR:
        lines_this_block = find_end_block(alllines, lptr);
        block.clear();
        /* Skips first and last lines in this loop.  first with
           if and last with termination condition.  Note this
           will cause problem if a curly back is not alone on
           the last line */
        for (i = 0; i < (lines_this_block - 1); ++i, ++lptr)
          if (i > 0)
            block.push_back(*lptr);
        if (type_of_this_line == PFMDTBL)
          pftbls.insert(pair<string, list<string>>(key, block));
        else {
          AntelopePf thispfarr(block);
          pfbranches.insert(pair<string, AntelopePf>(key, thispfarr));
        }
        break;
      default:
        throw AntelopePfError(base_error + "Error parsing this line->" + *lptr);
      }
    }
  } catch (...) {
    throw;
  };
}

References mspass::utility::Metadata::get(), and mspass::utility::Metadata::put().

◆ AntelopePf() [4/4]

mspass::utility::AntelopePf::AntelopePf ( const AntelopePf & parent )

Standard copy constructor.

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

References mspass::utility::Metadata::get().

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;
}

References mspass::utility::Metadata::get().

◆ 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;
  };
}

References mspass::utility::Metadata::get(), and mspass::utility::Metadata::put().

◆ 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;
}

References mspass::utility::Metadata::get().

◆ 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);
}

References mspass::utility::Metadata::get().

◆ 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::get(), and 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);
}

References mspass::utility::Metadata::get().

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

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ AntelopePf() [1/4]

◆ AntelopePf() [2/4]

◆ AntelopePf() [3/4]

◆ AntelopePf() [4/4]

Member Function Documentation

◆ arr_keys()

◆ ConvertToMetadata()

◆ get_branch()

◆ get_tbl()

◆ operator=()

◆ pfwrite()

◆ tbl_keys()