testing::NameSelector Class Reference

Manages a set of names. More...

#include <NameSelector.h>

Classes
struct	NameResponse_t
	A data structure containing how to react to a name. More...

Public Types
enum	Response_t { rsRejected, rsAccepted, rsThrow, rsDefault = rsAccepted }
	Possible responses. More...
using	Name_t = std::string
	type representing a name More...
using	Names_t = std::set< Name_t >
	list of names More...
using	NameList = std::initializer_list< Name_t >

Public Member Functions
	NameSelector (Response_t default_answer=rsDefault)
	Constructor: an empty selector with a default answer for unknown names. More...
template<typename LIST >
	NameSelector (LIST const &items, Response_t default_answer=rsDefault)
	Constructor: Parse()s the specified items. More...
void	SetDefaultResponse (Response_t default_answer)
	Sets the default answer for names that are not registered. More...
template<typename LIST >
void	Parse (LIST const &items)
	Parses the names in the list and adds them to the selector. More...
void	ParseName (Name_t name)
	Parses a name and adds it to the selector. More...
template<typename... NAMES>
void	ParseNames (NAMES...names)
	Parses a list of names and adds them to the selector. More...
void	Clear ()
	Erases all the names in the selector (default answer is unchanged) More...
template<typename LIST >
void	Define (std::string set_name, LIST const &items)
	Defines a set. More...
template<typename... NAMES>
void	AddToDefinition (std::string set_name, NAMES...names)
	Parses a list of names and add them to the specified definition. More...
Response_t	Query (Name_t name) const
	Returns the response for the specified name (does not throw) More...
bool	Accepted (Name_t name) const
	Returns whether the name is accepted as good. More...
bool	Rejected (Name_t name) const
	Returns whether the name is rejected as bad. More...
Response_t	DefaultResponse () const
	Returns the default answer for names that are not registered. More...
bool	operator() (Name_t name) const
	Returns whether the name is accepted as good (alias for accept()) More...
void	PrintConfiguration (std::ostream &) const
	Prints the configuration into a stream. More...
Names_t	AcceptedNames () const
	Returns a list of names that were accepted. More...
Names_t	RejectedNames () const
	Returns a list of names that were rejected. More...
void	ClearQueryRegistry ()
	Reests the query registry. More...
template<>
void	AddFirstName (KnownNames_t &name_set, Name_t name)
bool	CheckQueryRegistry () const
	Checks that no known element with valid response was left unqueried. More...
bool	CheckQueryRegistry (std::ostream &out) const

Static Public Attributes
static Name_t const	DefaultName = "*"
	name representing the default More...
static Name_t const	ClearAllName = "!"
	name instructing to delete all names More...

Protected Types
using	KnownNames_t = std::map< Name_t, NameResponse_t >
	Information about known names. More...
using	Definitions_t = std::map< Name_t, KnownNames_t >
	Type of list of definitions. More...
using	QueryRegistry_t = std::map< Name_t, size_t >
	Type of query counters. More...

Protected Member Functions
Response_t	LookupResponse (Name_t name) const
	Returns the response for the specified name (does not register query) More...
template<typename LIST >
void	BuildNameSet (KnownNames_t &name_set, LIST const &items) const
	Fills name_set with a list of items. More...
template<typename... NAMES>
void	AddFirstName (KnownNames_t &name_set, Name_t name, NAMES...other_names)
	Parses the first of the provided names, and recurs. More...
void	InsertItem (KnownNames_t &name_set, Name_t item, Response_t response) const
	Adds an item to the name set, working in specified mode. More...
void	InsertItem (KnownNames_t &name_set, KnownNames_t::value_type item, Response_t response) const
	Adds an item with response to the name set, working in specified mode. More...
void	ProcessItem (KnownNames_t &name_set, Name_t item) const
	Fills name_set with an item. More...
Definitions_t::const_iterator	FindDefinition (Name_t &item) const
	Strips set specifier and returns iterator to the definition, or end() More...
void	ClearNameSet (KnownNames_t &name_set) const
	Erases all the names in the selector (default answer is unchanged) More...
Names_t	QueriedWithStatus (Response_t answer) const
	Returns the list of queried names whose response is answer. More...
bool	DoCheckQueryRegistry (std::ostream *out=nullptr) const

Static Protected Member Functions
static Response_t	ParseMode (Name_t &item, Response_t default_answer=rsAccepted)
	Strips the mode specifier from item and returns the insertion mode. More...

Protected Attributes
KnownNames_t	known_names
	list of known names, with category More...
Definitions_t	definitions
	a set of definitions More...
QueryRegistry_t	query_registry
	record of all the queries More...

Detailed Description

Manages a set of names.

This class contains a set of names to be "accepted" and a set of names to be "rejected". Queries on unknown names will generate a default answer that can be acceptance, rejection or an exception.

The class is initialized by a list of strings following the convention detailed in ProcessItem(). The default answer is set on construction, but it can be overridden to a "reject by default" using a specific identifier.

Definition at line 37 of file NameSelector.h.

Member Typedef Documentation

using testing::NameSelector::Definitions_t = std::map<Name_t, KnownNames_t>

protected

Type of list of definitions.

Definition at line 181 of file NameSelector.h.

using testing::NameSelector::KnownNames_t = std::map<Name_t, NameResponse_t>

protected

Information about known names.

Definition at line 178 of file NameSelector.h.

using testing::NameSelector::Name_t = std::string

type representing a name

Definition at line 40 of file NameSelector.h.

using testing::NameSelector::NameList = std::initializer_list<Name_t>

Definition at line 52 of file NameSelector.h.

using testing::NameSelector::Names_t = std::set<Name_t>

list of names

Definition at line 41 of file NameSelector.h.

using testing::NameSelector::QueryRegistry_t = std::map<Name_t, size_t>

protected

Type of query counters.

Definition at line 184 of file NameSelector.h.

Member Enumeration Documentation

enum testing::NameSelector::Response_t

Possible responses.

Enumerator
rsRejected	rejected
rsAccepted	accepted
rsThrow	throw art::Exception (art::errors::Configuration)
rsDefault

Definition at line 44 of file NameSelector.h.

                 {
      rsRejected,   ///< rejected
      rsAccepted,   ///< accepted
      rsThrow,      ///< throw art::Exception (art::errors::Configuration)
      rsDefault = rsAccepted
    } Response_t;

Constructor & Destructor Documentation

testing::NameSelector::NameSelector ( Response_t  default_answer = rsDefault )

inline

Constructor: an empty selector with a default answer for unknown names.

Definition at line 56 of file NameSelector.h.

      { SetDefaultResponse(default_answer); }

template<typename LIST >

testing::NameSelector::NameSelector ( LIST const &  items, Response_t  default_answer = rsDefault  )

inline

Constructor: Parse()s the specified items.

Definition at line 61 of file NameSelector.h.

      : NameSelector(default_answer)
      { Parse(items); }

Member Function Documentation

bool testing::NameSelector::Accepted

(

Name_t

name

)

const

Returns whether the name is accepted as good.

Definition at line 39 of file NameSelector.cxx.

                                               {
    Response_t response = Query(name);
    if (response == rsThrow) {
      throw art::Exception(art::errors::Configuration)
        << "NameSelector: name '" << name << "' not configured.";
    }
    return response == rsAccepted;
  } // NameSelector::Accepted()

Names_t testing::NameSelector::AcceptedNames ( ) const

inline

Returns a list of names that were accepted.

Definition at line 151 of file NameSelector.h.

{ return QueriedWithStatus(rsAccepted); }

void testing::NameSelector::AddFirstName	(	KnownNames_t &	name_set,
		Name_t	name
	)

Definition at line 109 of file NameSelector.cxx.

                                                                       {
    ProcessItem(name_set, name);
  } // NameSelector::AddFirstName<>()

template<typename... NAMES>

void testing::NameSelector::AddFirstName ( KnownNames_t &  name_set, Name_t  name, NAMES...  other_names  )

protected

Parses the first of the provided names, and recurs.

Definition at line 307 of file NameSelector.h.

{
  AddFirstName(name_set, name);
  AddFirstName(name_set, other_names...);
} // testing::NameSelector::AddFirstName()

template<typename... NAMES>

void testing::NameSelector::AddToDefinition ( std::string  set_name, NAMES...  names  )

inline

Parses a list of names and add them to the specified definition.

Template Parameters

NAMES

Name_t-compatible types

Parameters

set_name	name of the set to be defined
names	the definitions to be used

Specified items are processed with ProcessItem(); the result is added to the set with the specified name. If a set with that name does not exist, it's created empty.

Definition at line 128 of file NameSelector.h.

      { AddFirstName(definitions[set_name], names...);  }

template<typename LIST >

void testing::NameSelector::BuildNameSet ( KnownNames_t &  name_set, LIST const &  items  ) const

protected

Fills name_set with a list of items.

Template Parameters

LIST	type of container of name directives

Parameters

name_set	set to be modified
items	name directives

A name set is modified according to the instructions in each of the items. The items are parsed sequentially, and their order matters for the final result. Each item is processed through ProcessItem().

Definition at line 292 of file NameSelector.h.

{
  for (Name_t item: items) ProcessItem(name_set, item);
} // testing::NameSelector::BuildNameSet()

bool testing::NameSelector::CheckQueryRegistry ( ) const

inline

Checks that no known element with valid response was left unqueried.

Definition at line 161 of file NameSelector.h.

{ return DoCheckQueryRegistry(); }

bool testing::NameSelector::CheckQueryRegistry ( std::ostream &  out ) const

inline

Definition at line 162 of file NameSelector.h.

      { return DoCheckQueryRegistry(&out); }

void testing::NameSelector::Clear ( )

inline

Erases all the names in the selector (default answer is unchanged)

Definition at line 101 of file NameSelector.h.

{ ClearNameSet(known_names); }

void testing::NameSelector::ClearNameSet ( KnownNames_t &  name_set ) const

protected

Erases all the names in the selector (default answer is unchanged)

Definition at line 189 of file NameSelector.cxx.

                                                              {
    KnownNames_t::iterator iName = name_set.begin(), nend = name_set.end();
    while (iName != nend) {
      if (iName->first == DefaultName) ++iName;
      else iName = name_set.erase(iName);
    } // while
  } // NameSelector::ClearNameSet()

void testing::NameSelector::ClearQueryRegistry ( )

inline

Reests the query registry.

Definition at line 157 of file NameSelector.h.

{ query_registry.clear(); }

Response_t testing::NameSelector::DefaultResponse ( ) const

inline

Returns the default answer for names that are not registered.

Definition at line 141 of file NameSelector.h.

      { return known_names.find(DefaultName)->second.response; }

template<typename LIST >

void testing::NameSelector::Define	(	std::string	set_name,
		LIST const &	items
	)

Defines a set.

Template Parameters

LIST	type of list of strings

Parameters

set_name	name of the set to be defined
items	the definitions to be used

Specified items are processed with BuildSet(); the result is stored as a set with the specified name. If a set with that name already exists, it's replaced and the old one is lost.

Definition at line 282 of file NameSelector.h.

                                                                      {
  KnownNames_t name_set;
  BuildNameSet(name_set, items);
  definitions[set_name] = std::move(name_set);
} // testing::NameSelector::Define()

bool testing::NameSelector::DoCheckQueryRegistry ( std::ostream *  out = nullptr ) const

protected

Definition at line 214 of file NameSelector.cxx.

  {
    Names_t missing;
    for (auto const& elem: known_names) {
      if (query_registry[elem.first] > 0U) continue;
      if (elem.first == DefaultName) continue;
      missing.insert(elem.first);
    } // for
    if (out && !missing.empty()) {
      (*out) << missing.size() << " items not queried:";
      for (Name_t const& name: missing) (*out) << " " << name;
      (*out) << std::endl;
    }
    return missing.empty();
  } // NameSelector::CheckQueryRegistry()

NameSelector::Definitions_t::const_iterator testing::NameSelector::FindDefinition ( Name_t &  item ) const

protected

Strips set specifier and returns iterator to the definition, or end()

Definition at line 170 of file NameSelector.cxx.

  {
    bool bForceDef = false;
    if (!item.empty()) {
      if (item[0] == '@') {
        bForceDef = true;
        item.erase(0, 1);
      }
    }
    Definitions_t::const_iterator iDefinition = definitions.find(item);
    if ((iDefinition == definitions.end()) && bForceDef) {
      throw art::Exception(art::errors::LogicError)
        << "no set named '" << item << "'\n";
    }
    return iDefinition;
  } // NameSelector::FindDefinition()

void testing::NameSelector::InsertItem ( KnownNames_t &  name_set, Name_t  item, Response_t  response  ) const

protected

Adds an item to the name set, working in specified mode.

Definition at line 116 of file NameSelector.cxx.

  {
    name_set[item] = { response };
  } // NameSelector::InsertItem()

void testing::NameSelector::InsertItem ( KnownNames_t &  name_set, KnownNames_t::value_type  item, Response_t  response  ) const

protected

Adds an item with response to the name set, working in specified mode.

Definition at line 124 of file NameSelector.cxx.

  {
    // response is the instruction we have about how to add the item
    // item.second.response is what the default answer for that item is
    Response_t final_response; // uninitialized
    switch (response) {
      case rsAccepted:
        final_response = item.second.response; // respect the response
        break;
      case rsRejected: // flip the response
        switch (item.second.response) {
          case rsAccepted: final_response = rsRejected; break;
          case rsRejected: final_response = rsAccepted; break;
          default:
            throw art::Exception(art::errors::LogicError)
              << __func__ << ": unexpected code flow: invalid added response";
        } // switch item response
        break;
      default:
        throw art::Exception(art::errors::LogicError)
          << __func__ << ": unexpected code flow: invalid response";
    } // switch response
    InsertItem(name_set, item.first, final_response);
  } // NameSelector::InsertItem(KnownNames_t::value_type)

NameSelector::Response_t testing::NameSelector::LookupResponse ( Name_t  name ) const

protected

Returns the response for the specified name (does not register query)

Definition at line 100 of file NameSelector.cxx.

                                                                       {
    KnownNames_t::const_iterator iResponse = known_names.find(name);
    return (iResponse == known_names.end())?
      DefaultResponse(): iResponse->second.response;
  } // NameSelector::LookupResponse()

bool testing::NameSelector::operator() ( Name_t  name ) const

inline

Returns whether the name is accepted as good (alias for accept())

Definition at line 145 of file NameSelector.h.

{ return Accepted(name); }

template<typename LIST >

void testing::NameSelector::Parse ( LIST const &  items )

inline

Parses the names in the list and adds them to the selector.

Template Parameters

LIST	type of list of strings

Parameters

items

the definitions to be used

Specified items are processed with ProcessItem() and the current set is modified.

Definition at line 78 of file NameSelector.h.

{ BuildNameSet(known_names, items); }

NameSelector::Response_t testing::NameSelector::ParseMode ( Name_t &  item, Response_t  default_answer = rsAccepted  )

staticprotected

Strips the mode specifier from item and returns the insertion mode.

Definition at line 233 of file NameSelector.cxx.

  {
    if (item[0] == '+') {
      item.erase(0, 1);
      return rsAccepted;
    }
    if (item[0] == '-') {
      item.erase(0, 1);
      return rsRejected;
    }
    return default_mode;
  } // NameSelector::ParseMode()

void testing::NameSelector::ParseName

(

Name_t

name

)

Parses a name and adds it to the selector.

Parameters

name	name specification to be parsed

The name is processed with ProcessItem() and the current set is modified.

Definition at line 26 of file NameSelector.cxx.

                                          {
    ProcessItem(known_names, name);
  } // NameSelector::ParseName()

template<typename... NAMES>

void testing::NameSelector::ParseNames ( NAMES...  names )

inline

Parses a list of names and adds them to the selector.

Template Parameters

NAMES

Name_t-compatible types

Parameters

names

the definitions to be used

Specified items are processed with ProcessItem() and modify the current set.

Definition at line 98 of file NameSelector.h.

{ AddFirstName(known_names, names...); }

void testing::NameSelector::PrintConfiguration

(

std::ostream &

out

)

const

Prints the configuration into a stream.

Definition at line 50 of file NameSelector.cxx.

                                                             {

    // resort the known elements
    std::map<Response_t, Names_t> elements;
    for (KnownNames_t::value_type const& element: known_names)
      if (element.first != DefaultName)
        elements[element.second.response].insert(element.first);

    size_t nKnownElements = 0;
    if (!elements[rsAccepted].empty()) {
      auto const& selected_elements = elements[rsAccepted];
      Names_t::const_iterator iName = selected_elements.cbegin(),
        nend = selected_elements.cend();
      out << " accept " << selected_elements.size()
        << ": '" << *(iName++) << "'";
      while (iName != nend) out << ", '" << *(iName++) << "'";
      out << ";";
      nKnownElements += selected_elements.size();
    } // if accepting anything
    if (!elements[rsRejected].empty()) {
      auto const& selected_elements = elements[rsRejected];
      Names_t::const_iterator iName = selected_elements.cbegin(),
        nend = selected_elements.cend();
      out << " reject " << selected_elements.size()
        << ": '" << *(iName++) << "'";
      while (iName != nend) out << ", '" << *(iName++) << "'";
      out << ";";
      nKnownElements += selected_elements.size();
    } // if accepting anything
    if (!elements[rsThrow].empty()) {
      auto const& selected_elements = elements[rsThrow];
      Names_t::const_iterator iName = selected_elements.cbegin(),
        nend = selected_elements.cend();
      out << " throw on " << selected_elements.size()
        << ": '" << *(iName++) << "'";
      while (iName != nend) out << ", '" << *(iName++) << "'";
      out << ";";
      nKnownElements += selected_elements.size();
    } // if accepting anything
    if (nKnownElements > 0) out << " otherwise,";
    switch (DefaultResponse()) {
      case rsAccepted: out << " accept everything"; break;
      case rsRejected: out << " reject everything"; break;
      case rsThrow:    out << " throw on anything"; break;
      default:         out << " I don't know";
    } // switch
  } // NameSelector::PrintConfiguration()

void testing::NameSelector::ProcessItem ( KnownNames_t &  name_set, Name_t  item  ) const

protected

Fills name_set with an item.

Parameters

name_set	set to be modified
item	name directive

A name set is modified according to the instruction in the items. An identifier may represent either a single literal item or a set name; it can appear in two forms:

• "\@identifier": always denotes a set named "identifier"
• "identifier": if a set named "identifier" exists, the name represents that set; otherwise, it represents a literal item named "identifier"

The directives in items are:

• "identifier": the element or elements represented by the identifier replace the content of the current set
• "+identifier": the element or elements represented by the identifier are added to the current set; if the identifier is a predefined set, the elements accepted in the set are added as accepted here, the ones rejected are added as rejected here
• "-identifier": the element or elements represented by the identifier; if the identifier is a predefined set, the elements accepted in the set are added as rejected here, the ones rejected are added as accepted here

Definition at line 152 of file NameSelector.cxx.

                                                                          {
    // special: if this name is actually a directive to clear all
    if (item == ClearAllName) {
      ClearNameSet(name_set); // clear everything except the default
      return;
    } // if clear all
    Response_t response = ParseMode(item);
    Definitions_t::const_iterator iDefinition = FindDefinition(item);
    if (iDefinition == definitions.end()) InsertItem(name_set, item, response);
    else {
      for (KnownNames_t::value_type const& element: iDefinition->second)
        InsertItem(name_set, element, response);
    }
  } // NameSelector::ProcessItem()

NameSelector::Names_t testing::NameSelector::QueriedWithStatus ( Response_t  answer ) const

protected

Returns the list of queried names whose response is answer.

Definition at line 200 of file NameSelector.cxx.

  {
    NameSelector::Names_t names;
    for (auto const& query_info: query_registry) {
      if (query_info.first == DefaultName) continue;
      if (LookupResponse(query_info.first) != answer) continue;
      names.insert(query_info.first);
    } // for
    return names;
  } // NameSelector::QueriedWithStatus()

NameSelector::Response_t testing::NameSelector::Query

(

Name_t

name

)

const

Returns the response for the specified name (does not throw)

Definition at line 32 of file NameSelector.cxx.

                                                              {
    ++(query_registry[name]);
    return LookupResponse(name);
  } // NameSelector::Query()

bool testing::NameSelector::Rejected ( Name_t  name ) const

inline

Returns whether the name is rejected as bad.

Definition at line 138 of file NameSelector.h.

{ return !Accepted(name); }

Names_t testing::NameSelector::RejectedNames ( ) const

inline

Returns a list of names that were rejected.

Definition at line 154 of file NameSelector.h.

{ return QueriedWithStatus(rsRejected); }

void testing::NameSelector::SetDefaultResponse ( Response_t  default_answer )

inline

Sets the default answer for names that are not registered.

Definition at line 66 of file NameSelector.h.

      { known_names[DefaultName] = { default_answer }; }

Member Data Documentation

NameSelector::Name_t const testing::NameSelector::ClearAllName = "!"

static

name instructing to delete all names

Definition at line 168 of file NameSelector.h.

NameSelector::Name_t const testing::NameSelector::DefaultName = "*"

static

name representing the default

Definition at line 167 of file NameSelector.h.

Definitions_t testing::NameSelector::definitions

protected

a set of definitions

Definition at line 188 of file NameSelector.h.

KnownNames_t testing::NameSelector::known_names

protected

list of known names, with category

Definition at line 186 of file NameSelector.h.

QueryRegistry_t testing::NameSelector::query_registry

mutableprotected

record of all the queries

Definition at line 190 of file NameSelector.h.

---

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

• NameSelector.h
• NameSelector.cxx