icarus::trigger::PlotSandbox Class Reference

A helper to manage ROOT objects with consistent naming. More...

#include <PlotSandbox.h>

Classes
struct	Data_t
	The whole data in a convenient package! More...
struct	TFileDirectoryHelper
	Contains both a art::TFileDirectory and the TDirectory it manages. More...

Public Member Functions
	PlotSandbox (art::TFileDirectory parentDir, std::string name, std::string desc)
	Constructor: specifies all sandbox characteristics. More...
	PlotSandbox (PlotSandbox const &)=delete
	PlotSandbox (PlotSandbox &&from)
PlotSandbox &	operator= (PlotSandbox const &)=delete
PlotSandbox &	operator= (PlotSandbox &&from)=delete
virtual	~PlotSandbox ()=default
	Virtual destructor. Default, but C++ wants it. More...
bool	hasName () const
	Returns whether we have a non-empty name. More...
std::string const &	name () const
	Returns the sandbox name. More...
bool	hasDescription () const
	Returns whether we have a non-empty description. More...
std::string const &	description () const
	Returns the sandbox description. More...
virtual std::string const &	Description () const
std::string	ID () const
	Returns a string ID for this sandbox. More...
virtual std::string	processName (std::string const &name) const
	Processes the specified string as it were a name. More...
virtual std::string	processTitle (std::string const &title) const
	Processes the specified string as it were a description or title. More...
bool	deleteSubSandbox (std::string const &name)
	Deletes the subbox with the specified name and its directory. More...
template<typename Stream >
void	dump (Stream &&out, std::string indent, std::string firstIndent) const
	Dumps the hierarchy of sandboxes into the specified stream. More...
template<typename Stream >
void	dump (Stream &&out, std::string indent="") const
	Dumps the hierarchy of sandboxes into the specified stream. More...
ROOT object management
bool	empty () const
	Returns if the sandbox is empty (neither it nor subboxes hold objects). More...
template<typename Obj = TObject>
Obj const *	get (std::string const &name) const
	Fetches the object with the specified name from the sandbox. More...
template<typename Obj = TObject>
Obj *	use (std::string const &name) const
	Fetches an object with the specified name to be modified. More...
template<typename Obj = TObject>
Obj &	demand (std::string const &name) const
	Fetches an object with the specified name to be modified. More...
template<typename DirObj = TDirectory>
DirObj *	getDirectory () const
	Fetches the base directory of the sandbox. More...
template<typename DirObj = TDirectory>
DirObj *	getDirectory (std::string const &path) const
	Fetches the directory with the specified name from the sandbox. More...
template<typename Obj , typename... Args>
Obj *	make (std::string const &name, std::string const &title, Args &&...args)
	Creates a new ROOT object with the specified name and title. More...
Contained sandboxes
template<typename SandboxType = PlotSandbox, typename... Args>
SandboxType &	addSubSandbox (std::string const &name, std::string const &desc, Args &&...args)
	Creates a new sandbox contained in this one. More...
std::size_t	nSubSandboxes () const
	Returns the number of contained sand boxes. More...
PlotSandbox const *	findSandbox (std::string const &name) const
	Returns the first contained sandbox with the specified name. More...
PlotSandbox *	findSandbox (std::string const &name)
PlotSandbox const &	demandSandbox (std::string const &name) const
	Returns the first contained sandbox with the specified name. More...
PlotSandbox &	demandSandbox (std::string const &name)
decltype(auto)	subSandboxes () const
	Returns an object proper to iterate through all contained sand boxes. More...
decltype(auto)	subSandboxes ()

Protected Member Functions
	PlotSandbox (PlotSandbox const &parent, std::string name, std::string desc)
	Constructor: specifies all sandbox characteristics. More...
virtual void	setParent (PlotSandbox const *parent)
	Sets the parent of this box. More...
std::string	processPlotTitle (std::string const &title) const
	Applies title processing only at the title part of the string. More...
virtual std::string	processedSandboxName () const
virtual std::string	processedSandboxDesc () const
template<typename Stream >
void	dumpContent (Stream &&out, std::string indent, std::string firstIndent) const
	Dumps the content of this box (nosubboxes) into out stream. More...

Static Private Member Functions
template<typename SandboxType >
static auto *	findSandbox (SandboxType &sandbox, std::string const &name)
	Helper function for findSandbox() implementations. More...
template<typename SandboxType >
static auto &	demandSandbox (SandboxType &sandbox, std::string const &name)
	Helper function for demandSandbox() implementations. More...

Private Attributes
struct icarus::trigger::PlotSandbox::Data_t	fData

Object creation specializations
These are implementation details. PlotSandbox manages the creation of objects to be put into ROOT directories and acts as an interface between art::TFileDirectory and user code. In particular it takes the responsibility of constructing new objects to be stored in the directory. There are special arguments to these objects, that are the name and, to a lesser extent, a title. PlotSandbox manipulates the name of the object to make it unique, and therefore it has to have full control of everywhere a name is set. The name is crucial in ROOT because it is the key for searching the object. So it has a double role of the name of the object (property of the object itself) and the key of the container that hosts that object. Some ROOT objects can and must be constructed with a name, and usually a title too (e.g. TH1 and TTree hierarchies), and their constructor takes these as the first two arguments. Other object, though, do not follow that pattern (e.g. TGraph), and worse, these object might accept strings as first constructor arguments, assigning them a different meaning. For these objects a different initialization pattern is necessary, where the object is constructed with user-specified arguments first, and then the name (and, if supported, the title) are set. PlotSandbox interface attempts to save the user from this hassle, but because specific actions are needed for specific objects, it needs to know these needs case by case. This implementation tries to give the necessary flexibility to easily implement special cases. A few basic tools are provided, which support specific types of objects: makeWithNameTitle() supports the objects which can be constructed with a name and a title (e.g. TH1); makeAndSetNameTitle(), support objects which are known not to use name and title as first constructor arguments, but do provide SetName() (safe bet, coming from TObject) and SetTitle(). Building on that, different overloads of doConstruct() use one or another of these utilities, or none, to create the correct type of object. The overload is entrusted to C++ via the pointer type (which C++ matches with a pointer to a base class). Note that in this strategy it is not possible to use a constructor without name and title for an object that also supports the construction with name and title: as long as PlotSandbox recognizes an object as falling in that category, it will always construct it by calling a constructor with name and title as first arguments. Also note that no name decoration happens at this level: all object names and titles are expected to be final (processing happens e.g. in make()).
template<typename Obj , typename... Args>
Obj *	makeWithNameTitle (art::TFileDirectory &destDir, std::string const &name, std::string const &title, Args &&...args) const
	Creates, stores and returns a new object. More...
template<typename Obj , typename... Args>
Obj *	makeAndSetNameTitle (art::TFileDirectory &destDir, std::string const &name, std::string const &title, Args &&...args) const
	Creates, stores and returns a new object. More...
template<typename Obj , typename... Args>
Obj *	doConstruct (art::TFileDirectory &destDir, TObject *, std::string const &name, std::string const &title, Args &&...args) const
	General implementation: creates and registers an Obj (name and title used in Obj constructor). More...
template<typename GraphObj , typename... Args>
GraphObj *	doConstruct (art::TFileDirectory &destDir, TGraph *, std::string const &name, std::string const &title, Args &&...args) const
	Implementation for TGraph-derived objects. More...
static std::pair< std::string, std::string >	splitPath (std::string const &path, char sep= '/')
static std::string	joinPath (std::initializer_list< std::string > pathElements, char sep= '/')

Detailed Description

A helper to manage ROOT objects with consistent naming.

A sandbox includes a ROOT directory where all the objects are written. It also provides a name pattern to modify a generic object name in one specific to this sandbox, e.g. from "HEnergy" to "HMuonNeutrinoEnergy". Object descriptions (usually titles) may also be processed in the same way.

In addition, the sandbox can point to a parent sandbox, in which case the names and descriptions are first processed by this sandbox and then passed to that parent sandbox for further processing.

The sandbox has two characterizing strings:

• the name is a key used in ROOT object names and it is also by default the name of the output ROOT directory; for example: "MuonNeutrino" or "CC". This string becoming part of the ROOT object name, it is better to keep it short and simply alphanumeric.
• the description is a short wording for the content of the sandbox, used in processing ROOT object titles; for example, "#nu_{#mu}" or "charged current".

Note

By convention the subdirectory names are not processed.

Definition at line 95 of file PlotSandbox.h.

Constructor & Destructor Documentation

icarus::trigger::PlotSandbox::PlotSandbox	(	art::TFileDirectory	parentDir,
		std::string	name,
		std::string	desc
	)

Constructor: specifies all sandbox characteristics.

Parameters

parentDir	ROOT directory under which the sandbox is created
name	the name of the sandbox
desc	description of the sandbox

If the name is empty, as a special case, the sandbox is unnamed and it is created directly in parentDir. In that case, the title of the output directory (parentDir) is also not changed. If name or desc are empty, the pertaining processing is not performed: if name is empty, ROOT object names will be unchanged, and if desc is empty their descriptions/titles will be.

To create a sandbox with a parent, call addSubSandbox() of that parent.

Definition at line 80 of file PlotSandbox.cxx.

  : fData(std::move(name), std::move(desc), 
    name.empty()
      ? TFileDirectoryHelper::create(parentDir)
      : TFileDirectoryHelper::create(parentDir, name, desc)
    )
{}

icarus::trigger::PlotSandbox::PlotSandbox ( PlotSandbox const &  )

delete

icarus::trigger::PlotSandbox::PlotSandbox

(

PlotSandbox &&

from

)

Definition at line 93 of file PlotSandbox.cxx.

  : fData(std::move(from.fData))
{
  fData.resetSubboxParents(this); // adjust the parent pointers of the subboxes
} // PlotSandbox::PlotSandbox(PlotSandbox&&)

virtual icarus::trigger::PlotSandbox::~PlotSandbox ( )

virtualdefault

Virtual destructor. Default, but C++ wants it.

icarus::trigger::PlotSandbox::PlotSandbox ( PlotSandbox const &  parent, std::string  name, std::string  desc  )

protected

Constructor: specifies all sandbox characteristics.

Parameters

parent	the sandbox used as parent
name	the name of the sandbox
desc	description of the sandbox

Compared to the public constructor, this one picks the parent directory to be the output directory of the parent sandbox, and it registers that parent box as parent. Note that this constructor does not update the list of subboxes of the parent.

Definition at line 192 of file PlotSandbox.cxx.

  : PlotSandbox(parent.fData.outputDir.fDir, std::move(name), std::move(desc))
{
  setParent(&parent);
}

Member Function Documentation

template<typename SandboxType , typename... Args>

SandboxType & icarus::trigger::PlotSandbox::addSubSandbox	(	std::string const &	name,
		std::string const &	desc,
		Args &&...	args
	)

Creates a new sandbox contained in this one.

Template Parameters

SandboxType	(default: PlotSandbox) type of sandbox to be created
Args	types of the additional arguments for the sandbox constructor

Parameters

name	name of the new contained sand box
desc	description of the new contained sand box
args	additional arguments for the sandbox constructor

Returns

a reference to the created sandbox

Exceptions

cet::exception

(category: "PlotSandbox") if a sandbox with this name already exists.

The arguments of this method are equivalent to the ones of the constructor.

The new sand box parent is set to point to this sand box.

Definition at line 723 of file PlotSandbox.h.

{
  // we can't use make_unique() because the constructor it needs is protected:
  auto [ it, bInserted ] = fData.subBoxes.try_emplace
    (name, new SandboxType(*this, name, desc, std::forward<Args>(args)...));
  if (!bInserted) {
    throw cet::exception("PlotSandbox")
      << "PlotSandbox::addSubSandbox(): a subbox with name '" << name
      << "' already exists in  box '" << ID() << "'.\n";
  }
  return *(it->second); // it iterator to the inserted element
} // icarus::trigger::PlotSandbox::addSubSandbox()

bool icarus::trigger::PlotSandbox::deleteSubSandbox

(

std::string const &

name

)

Deletes the subbox with the specified name and its directory.

Returns

whether there was a subbox with that name

Definition at line 174 of file PlotSandbox.cxx.

                                                                     {
  
  auto const it = fData.subBoxes.find(name);
  if (it == fData.subBoxes.end()) return false;
  
  if (it->second) {
    auto&& subbox = std::move(it->second); // will get destroyed at end of scope
    if (subbox->getDirectory()) delete subbox->getDirectory();
    if (getDirectory()) getDirectory()->Delete((name + ";*").c_str());
  }
  
  fData.subBoxes.erase(it);
  return true;
} // icarus::trigger::PlotSandbox::deleteSubSandbox()

template<typename Obj >

Obj & icarus::trigger::PlotSandbox::demand

(

std::string const &

name

)

const

Fetches an object with the specified name to be modified.

Template Parameters

Obj	(default: TObject) type of the object to fetch

Parameters

name	unprocessed name and path of the object to fetch

Returns

the requested object

Exceptions

cet::exception

(category: "PlotSandbox") if no object with name exists in the box

See Also

get(), use()

This method is equivalent to use(), with the difference that the returned object must exist.

Definition at line 667 of file PlotSandbox.h.

                                                                 {
  
  auto* obj = use<Obj>(name);
  if (obj) return *obj;
  cet::exception e { "PlotSandbox" };
  e << "PlotSandbox::demand(): object '" << name
    << "' not available in the sandbox '" << ID() << "'"
    << "\nBox content: ";
  dumpContent(e, "", ""); // no indent
  
  throw e << "\n";
} // icarus::trigger::PlotSandbox::demand()

template<typename SandboxType >

auto & icarus::trigger::PlotSandbox::demandSandbox ( SandboxType &  sandbox, std::string const &  name  )

staticprivate

Helper function for demandSandbox() implementations.

Definition at line 750 of file PlotSandbox.h.

{
  auto* box = findSandbox(sandbox, name);
  if (box) return *box;
  
  cet::exception e { "PlotSandbox" };
  e << "PlotSandbox::demandSandbox(): box '" << name
    << "' not available in the sandbox '" << sandbox.ID() << "'";
  if (sandbox.nSubSandboxes()) {
    e << "\n" << "Available nested boxes (" << sandbox.nSubSandboxes() << "):";
    for (auto const& subbox: sandbox.subSandboxes())
      e << "\n * '" << subbox.ID() << "'";
  } // if has subboxes
  else {
    e << "  (no contained box!)";
  }
  throw e << "\n";

} // icarus::trigger::PlotSandbox::demandSandbox(SandboxType)

auto icarus::trigger::PlotSandbox::demandSandbox

(

std::string const &

name

)

const

Returns the first contained sandbox with the specified name.

Parameters

name	unprocessed name of the box to be retrieved

Returns

the requested contained sandbox

Exceptions

cet::exception

(category: "PlotSandbox") if no a sandbox with this name exists

See Also

findSandbox()

Definition at line 168 of file PlotSandbox.cxx.

  { return demandSandbox(*this, name); }

auto icarus::trigger::PlotSandbox::demandSandbox

(

std::string const &

name

)

Definition at line 164 of file PlotSandbox.cxx.

  { return demandSandbox(*this, name); }

std::string const& icarus::trigger::PlotSandbox::description ( ) const

inline

Returns the sandbox description.

Definition at line 202 of file PlotSandbox.h.

{ return fData.desc; }

virtual std::string const& icarus::trigger::PlotSandbox::Description ( ) const

inlinevirtual

Returns the sandbox description for use at the beginning of a sentence.

Todo:

Not implemented yet.

Definition at line 206 of file PlotSandbox.h.

{ return description(); }

template<typename Obj , typename... Args>

Obj * icarus::trigger::PlotSandbox::doConstruct ( art::TFileDirectory &  destDir, TObject *  , std::string const &  name, std::string const &  title, Args &&...  args  ) const

protected

General implementation: creates and registers an Obj (name and title used in Obj constructor).

Template Parameters

Obj	type of the object to construct
Args	type of additional arguments to Obj constructor, if any

Parameters

destDir	art::TFileDirectory where to store the object
obj	pointer to Obj; unused except to direct C++ overloading
name	final name of the object
title	final title of the object
args	additional arguments to Obj constructor

This is the most fundamental method constructing an object, which is used as fallback for all TObject-derived objects if nothing more appropriate is available. It is also the best option in general, when Obj supports it. It requires Obj to have a constructor whose first two arguments are name and title of the object.

Definition at line 795 of file PlotSandbox.h.

        {
  return
    makeWithNameTitle<Obj>(destDir, name, title, std::forward<Args>(args)...);
} // icarus::trigger::PlotSandbox::doConstruct()

template<typename GraphObj , typename... Args>

GraphObj * icarus::trigger::PlotSandbox::doConstruct ( art::TFileDirectory &  destDir, TGraph *  , std::string const &  name, std::string const &  title, Args &&...  args  ) const

protected

Implementation for TGraph-derived objects.

Template Parameters

GraphObj	type of TGraph-derived object to construct
Args	type of arguments to GraphObj constructor, if any

Parameters

destDir	art::TFileDirectory where to store the object
graph	pointer to GraphObj; unused except to direct C++ overloading
name	final name of the graph object
title	final title of the graph object
args	arguments to GraphObj constructor

This method manages the creation of objects derived from TGraph. Note that TGraph itself does feature a constructor with two strings as first arguments, but that is not the standard name/title constructor (in fact, there is no such standard constructor for TGraph, and that matching one takes a text file path for input and an option string...).

The name and title of the graph are still set, via SetName() and SetTitle() (this action is delegated to TFileDirectory::makeAndRegister()).

Definition at line 808 of file PlotSandbox.h.

        {
  return makeAndSetNameTitle<GraphObj>
      (destDir, name, title, std::forward<Args>(args)...);
} // icarus::trigger::PlotSandbox::doConstruct(TGraph)

template<typename Stream >

void icarus::trigger::PlotSandbox::dump	(	Stream &&	out,
		std::string	indent,
		std::string	firstIndent
	)		const

Dumps the hierarchy of sandboxes into the specified stream.

Definition at line 822 of file PlotSandbox.h.

{
  out << firstIndent;
  if (hasName()) out << "Box '" << name() << "'";
  else           out << "Unnamed box";
  if (hasDescription()) out << " (\"" << description() << "\")";
  out << " [ID=" << ID() << "] with ";
  dumpContent(std::forward<Stream>(out), indent, "");
  
  if (nSubSandboxes()) {
    out << "\n" << indent << "Nested boxes (" << nSubSandboxes() << "):";
    for (auto const& subbox: subSandboxes()) {
      out << "\n";
      subbox.dump(std::forward<Stream>(out), indent + "  ");
    }
  } // if has subboxes
} // icarus::trigger::PlotSandbox::dump()

template<typename Stream >

void icarus::trigger::PlotSandbox::dump ( Stream &&  out, std::string  indent = ""  ) const

inline

Dumps the hierarchy of sandboxes into the specified stream.

Definition at line 389 of file PlotSandbox.h.

    { dump(std::forward<Stream>(out), indent, indent); }

template<typename Stream >

void icarus::trigger::PlotSandbox::dumpContent ( Stream &&  out, std::string  indent, std::string  firstIndent  ) const

protected

Dumps the content of this box (nosubboxes) into out stream.

Definition at line 844 of file PlotSandbox.h.

{
  out << firstIndent;
  
  TDirectory const* pDir = fData.outputDir.fROOTdir;
  if (!pDir) {
    out << "no content available";
    return;
  }
  
  TList const* objects = pDir->GetList();
  TList const* keys = pDir->GetListOfKeys();
  if (objects && !objects->IsEmpty()) {
    out << objects->GetSize() << " direct entries:";
    for (TObject const* obj: *objects) {
      out << "\n" << indent << "  '" << obj->GetName() << "'  ["
        << obj->IsA()->GetName() << "]";
    } // for objects
  }
  else out << "no direct entries;";
  if (keys) {
    for (TObject const* keyObj: *keys) {
      auto key = dynamic_cast<TKey const*>(keyObj);
      if (!key) continue;
      if (objects->Contains(key->GetName())) continue; // already in objects
      out << "\n" << indent
        << "[KEY]  '" << key->GetName() << "'  ["
        << key->GetClassName() << "]"
        ;
    } // for
  } // if has keys
  
} // icarus::trigger::PlotSandbox::dumpContent()

bool icarus::trigger::PlotSandbox::empty

(

)

const

Returns if the sandbox is empty (neither it nor subboxes hold objects).

Definition at line 124 of file PlotSandbox.cxx.

                                           {
  
  std::vector<TDirectory const*> subDirectories; // directories of subboxes
  
  // if any of the subboxes is not empty, then this one is not either
  for (auto& subbox: subSandboxes()) {
    if (!subbox.empty()) return false;
    subDirectories.push_back(subbox.getDirectory());
  } // for
  
  auto const isSubDirectory = [b=subDirectories.begin(),e=subDirectories.end()]
    (TObject const* obj)
    {
      auto dir = dynamic_cast<TDirectory const*>(obj);
      return dir && std::find(b, e, dir) != e;
    };
  
  // if there is any object in memory associated to the directory,
  // that is not empty (directories from subboxes are exempted)
  for (TObject const* obj: *(getDirectory()->GetList()))
    if (!isSubDirectory(obj)) return false;
  
  // if there is any key associated to the directory, that is not empty
  if (getDirectory()->GetListOfKeys()->GetSize()) return false;
  
  return true;
} // icarus::trigger::PlotSandbox::empty()

template<typename SandboxType >

auto * icarus::trigger::PlotSandbox::findSandbox ( SandboxType &  sandbox, std::string const &  name  )

staticprivate

Helper function for findSandbox() implementations.

Definition at line 740 of file PlotSandbox.h.

{
  auto const it = sandbox.fData.subBoxes.find(name);
  return (it == sandbox.fData.subBoxes.end())? nullptr: it->second.get();
}

auto icarus::trigger::PlotSandbox::findSandbox

(

std::string const &

name

)

const

Returns the first contained sandbox with the specified name.

Parameters

name	unprocessed name of the box to be retrieved

Returns

the requested contained sandbox, or nullptr if not found

See Also

demandSandbox()

Definition at line 158 of file PlotSandbox.cxx.

  { return findSandbox(*this, name); }

auto icarus::trigger::PlotSandbox::findSandbox

(

std::string const &

name

)

Definition at line 154 of file PlotSandbox.cxx.

  { return findSandbox(*this, name); }

template<typename Obj >

Obj const * icarus::trigger::PlotSandbox::get

(

std::string const &

name

)

const

Fetches the object with the specified name from the sandbox.

Template Parameters

Obj	(default: TObject) type of the object to fetch

Parameters

name	unprocessed name and path of the object to fetch

Returns

a constant pointer to the requested object , or nullptr if not available or wrong type

See Also

use()

The name specification may contain a ROOT path. The directory component of the path, defined by everything preceding a / character, is not processed.

The fetched object is converted to the desired type via dynamic_cast. If conversion fails, a null pointer is returned.

Definition at line 646 of file PlotSandbox.h.

  { return use<std::add_const_t<Obj>>(name); }

template<typename DirObj >

DirObj * icarus::trigger::PlotSandbox::getDirectory

(

)

const

Fetches the base directory of the sandbox.

Returns

a pointer to the requested directory, or nullptr if wrong type

The directory is converted to the desired type via dynamic_cast. If conversion fails, a null pointer is returned.

Definition at line 683 of file PlotSandbox.h.

  { return dynamic_cast<DirObj*>(fData.outputDir.fROOTdir); }

template<typename DirObj >

DirObj * icarus::trigger::PlotSandbox::getDirectory

(

std::string const &

path

)

const

Fetches the directory with the specified name from the sandbox.

Template Parameters

DirObj

(default: TDirectory) type of ROOT directory object to get

Parameters

path	path of the directory to fetch within this sandbox

Returns

a constant pointer to the requested directory, or nullptr if not available or wrong type

The fetched object is converted to the desired type via dynamic_cast. If conversion fails, a null pointer is returned.

Definition at line 690 of file PlotSandbox.h.

{
  TDirectory* pBaseDir = fData.outputDir.fROOTdir;
  return dynamic_cast<DirObj*>
    (path.empty()? pBaseDir: pBaseDir->GetDirectory(path.c_str()));
} // icarus::trigger::PlotSandbox::getDirectory()

bool icarus::trigger::PlotSandbox::hasDescription ( ) const

inline

Returns whether we have a non-empty description.

Definition at line 199 of file PlotSandbox.h.

{ return !fData.desc.empty(); }

bool icarus::trigger::PlotSandbox::hasName ( ) const

inline

Returns whether we have a non-empty name.

Definition at line 193 of file PlotSandbox.h.

{ return !fData.name.empty(); }

std::string icarus::trigger::PlotSandbox::ID

(

)

const

Returns a string ID for this sandbox.

Definition at line 101 of file PlotSandbox.cxx.

  { return fData.parent? (fData.parent->ID() + '/' + name()): name(); }

std::string icarus::trigger::PlotSandbox::joinPath ( std::initializer_list< std::string >  pathElements, char  sep = '/'  )

staticprotected

Merges the pieces of path that are not empty into a path. One separator at the end of each piece is ignored.

Definition at line 269 of file PlotSandbox.cxx.

{
  if (std::empty(pathElements)) return {};
  
  auto stripSep = [sep](std::string const& s) -> std::string_view {
    return {
      s.data(),
      ((s.length() > 1) && (s.back() == sep))? s.length() - 1: s.length()
      };
    };
  
  auto iElem = pathElements.begin();
  auto const eend = pathElements.end();
  auto const& first = stripSep(*iElem);
  std::string s { first.begin(), first.end() };
  while (++iElem != eend) {
    auto const& elem = stripSep(*iElem);
    if (elem.empty()) continue;
    if (elem.front() != sep) s.push_back(sep);
    s += elem;
  } // while
  return s;
} // icarus::trigger::PlotSandbox::joinPath()

template<typename Obj , typename... Args>

Obj * icarus::trigger::PlotSandbox::make	(	std::string const &	name,
		std::string const &	title,
		Args &&...	args
	)

Creates a new ROOT object with the specified name and title.

Template Parameters

Obj	type of ROOT object to be created
Args	types of the argumenst to be forwarded to the constructor

Parameters

name	unprocessed name of the new object
title	unprocessed title of the new object
args	additional arguments forwarded to the constructor

Returns

a pointer to the newly created object

The name and title are processed with processName() and processTitle() method respectively, before the object is created.

Definition at line 701 of file PlotSandbox.h.

{
  auto [ objDir, objName ] = splitPath(name);
  
  std::string const processedName = processName(objName);
  std::string const processedTitle = processPlotTitle(title);
  
  art::TFileDirectory destDir
    = objDir.empty()? fData.outputDir.fDir: fData.outputDir.fDir.mkdir(objDir);
  
  using ObjPtr_t = Obj*;
  return doConstruct<Obj>(
    destDir, ObjPtr_t{},
    processedName, processedTitle, std::forward<Args>(args)...
    );
} // icarus::trigger::PlotSandbox::make()

template<typename Obj , typename... Args>

Obj * icarus::trigger::PlotSandbox::makeAndSetNameTitle ( art::TFileDirectory &  destDir, std::string const &  name, std::string const &  title, Args &&...  args  ) const

protected

Creates, stores and returns a new object.

Template Parameters

Obj	type of the new object to create
Args	type of the additional arguments to Obj constructor

Parameters

destDir	the art::TFileDirectory where the object is stored
name	final name of the object to be created
title	final title of the object to be created
args	additional arguments to Obj constructor, if any

Returns

a pointer to the registered object

See Also

makeAndRegister()

This method registers a new object into destDir via art::TFileDirectory::makeAndRegister(), using only the constructor arguments specified in args. The name and title are set afterwards via SetName() and SetTitle().

Definition at line 785 of file PlotSandbox.h.

        {
  return destDir.makeAndRegister<Obj>(name, title, std::forward<Args>(args)...);
} // icarus::trigger::PlotSandbox::justMake()

template<typename Obj , typename... Args>

Obj * icarus::trigger::PlotSandbox::makeWithNameTitle ( art::TFileDirectory &  destDir, std::string const &  name, std::string const &  title, Args &&...  args  ) const

protected

Creates, stores and returns a new object.

Template Parameters

Obj	type of the new object to create
Args	type of the additional arguments to Obj constructor

Parameters

destDir	the art::TFileDirectory where the object is stored
name	final name of the object to be created
title	final title of the object to be created
args	additional arguments to Obj constructor, if any

Returns

a pointer to the registered object

See Also

makeAndSetNameTitle()

This method registers a new object into destDir via art::TFileDirectory::makeAndRegister(), using the name and title as the first arguments of the constructor.

Definition at line 774 of file PlotSandbox.h.

        {
  return destDir.makeAndRegister<Obj>
    (name, title, name.c_str(), title.c_str(), std::forward<Args>(args)...);
} // icarus::trigger::PlotSandbox::makeWithNameTitle()

std::string const& icarus::trigger::PlotSandbox::name ( ) const

inline

Returns the sandbox name.

Definition at line 196 of file PlotSandbox.h.

{ return fData.name; }

std::size_t icarus::trigger::PlotSandbox::nSubSandboxes ( ) const

inline

Returns the number of contained sand boxes.

Definition at line 341 of file PlotSandbox.h.

{ return fData.subBoxes.size(); }

PlotSandbox& icarus::trigger::PlotSandbox::operator= ( PlotSandbox const &  )

delete

PlotSandbox& icarus::trigger::PlotSandbox::operator= ( PlotSandbox &&  from )

delete

std::string icarus::trigger::PlotSandbox::processedSandboxDesc ( ) const

protectedvirtual

Returns a processed version of the description of this sandbox.

This may be used when integrating the sandbox description into the processed object descriptions.

Definition at line 242 of file PlotSandbox.cxx.

{
  std::string processed;
  
  // if there is no name, the processed name is empty (we don't recurse parents)
  if (hasDescription()) processed += description();
  
  if (fData.parent) processed += ' ' + fData.parent->processedSandboxDesc();
  
  return processed;
} // icarus::trigger::PlotSandbox::processedSandboxDesc()

std::string icarus::trigger::PlotSandbox::processedSandboxName ( ) const

protectedvirtual

Returns a processed version of the name of this sandbox.

This may be used when integrating the sandbox name into the processed object names.

Definition at line 227 of file PlotSandbox.cxx.

{
  std::string processed;
  
  // if there is no name, the processed name is empty (we don't recurse parents)
  if (!hasName()) return processed;
  
  processed = name();
  if (fData.parent) processed += '_' + fData.parent->processedSandboxName();
  
  return processed;
} // icarus::trigger::PlotSandbox::processedSandboxName()

std::string icarus::trigger::PlotSandbox::processName ( std::string const &  name ) const

virtual

Processes the specified string as it were a name.

Definition at line 107 of file PlotSandbox.cxx.

{
  std::string const sandboxName = processedSandboxName();
  return sandboxName.empty()? name: name + '_' + sandboxName;
} // icarus::trigger::PlotSandbox::processName()

std::string icarus::trigger::PlotSandbox::processPlotTitle ( std::string const &  title ) const

protected

Applies title processing only at the title part of the string.

Definition at line 200 of file PlotSandbox.cxx.

{
  /*
   * We want to process the title of the plot, but this "title" string might
   * contain also axis labels (see e.g. `TH1::SetTitle()`).
   * 
   * We need to first identify the actual title portion of the "title",
   * then process it alone and merge it back (one Python line...).
   * 
   */
  
  // eat title until an unescaped ';' is found
  auto const tbegin = title.begin();
  auto const tend = title.end();
  auto atend = tbegin; // actual title end
  while (atend != tend) {
    if ((*atend == ';') && ((atend == tbegin) || (*std::prev(atend) != '\\')))
      break;
    ++atend;
  } // while
  
  return processTitle({ tbegin, atend }).append(atend, tend);
  
} // icarus::trigger::PlotSandbox::processedPlotTitle()

std::string icarus::trigger::PlotSandbox::processTitle ( std::string const &  title ) const

virtual

Processes the specified string as it were a description or title.

Definition at line 116 of file PlotSandbox.cxx.

{
  std::string const sandboxDesc = processedSandboxDesc();
  return sandboxDesc.empty()? title: title + ' ' + sandboxDesc;
} // icarus::trigger::PlotSandbox::processTitle()

virtual void icarus::trigger::PlotSandbox::setParent ( PlotSandbox const *  parent )

inlineprotectedvirtual

Sets the parent of this box.

Definition at line 410 of file PlotSandbox.h.

{ fData.parent = parent; }

std::pair< std::string, std::string > icarus::trigger::PlotSandbox::splitPath ( std::string const &  path, char  sep = '/'  )

staticprotected

Retrieves or, if not present, creates a ROOT subdirectory in the sandbox. Returns a pair with the directory and the name part of path. The directory part may be empty.

Definition at line 257 of file PlotSandbox.cxx.

{
  
  auto const iSep = path.rfind(sep);
  if (iSep == std::string::npos) return { {}, path };
  else return { path.substr(0U, iSep), path.substr(iSep + 1) };
  
} // icarus::trigger::PlotSandbox::splitPath()

decltype(auto) icarus::trigger::PlotSandbox::subSandboxes ( ) const

inline

Returns an object proper to iterate through all contained sand boxes.

Definition at line 369 of file PlotSandbox.h.

    { return details::map_dereferenced_values(fData.subBoxes); }

decltype(auto) icarus::trigger::PlotSandbox::subSandboxes ( )

inline

Definition at line 371 of file PlotSandbox.h.

    { return details::map_dereferenced_values(fData.subBoxes); }

template<typename Obj >

Obj * icarus::trigger::PlotSandbox::use

(

std::string const &

name

)

const

Fetches an object with the specified name to be modified.

Template Parameters

Obj	(default: TObject) type of the object to fetch

Parameters

name	unprocessed name and path of the object to fetch

Returns

a pointer to the requested object , or nullptr if not available or wrong type

See Also

get()

This method is fully equivalent to get(), with the difference that the returned object may be modified.

Definition at line 652 of file PlotSandbox.h.

                                                              {
  
  auto [ objDir, objName ] = splitPath(name);
  
  TDirectory* dir = getDirectory(objDir);
  if (!dir) return nullptr;
  
  std::string const processedName = processName(objName);
  return dir->Get<Obj>(processedName.c_str());
  
} // icarus::trigger::PlotSandbox::use()

Member Data Documentation

struct icarus::trigger::PlotSandbox::Data_t icarus::trigger::PlotSandbox::fData

private

---

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

• PlotSandbox.h
• PlotSandbox.cxx