Codify some of the implicitly assumed conventions (#439)

include/podio/Frame.h

@@ -3,6 +3,7 @@
 
 #include "podio/CollectionBase.h"
 #include "podio/CollectionIDTable.h"
+#include "podio/FrameCategories.h" // mainly for convenience
 #include "podio/GenericParameters.h"
 #include "podio/ICollectionProvider.h"
 #include "podio/utilities/TypeHelpers.h"

include/podio/FrameCategories.h

@@ -0,0 +1,43 @@
+#ifndef PODIO_FRAMECATEGORIES_H
+#define PODIO_FRAMECATEGORIES_H
+
+#include <string>
+
+namespace podio {
+
+/**
+ * Create a parameterName that encodes the collection name and the parameter
+ * Name into one string.
+ *
+ * This codifies a convention that was decided on to store collection level
+ * parameters. These are parameters / metadata that are valid for all
+ * collections of a given name in a file, e.g. CellID encoding strings. These
+ * parameters are usually stored in a dedicated metadata Frame inside a file,
+ * see the predefined category names in the Cateogry namespace.
+ *
+ * @param collName the name of the collection
+ * @param paramName the name of the parameter
+ *
+ * @returns A single key string that combines the collection and parameter name
+ */
+inline std::string collMetadataParamName(const std::string& collName, const std::string& paramName) {
+  return collName + "__" + paramName;
+}
+
+/**
+ * This namespace mimics an enum (at least in its usage) and simply defines
+ * either commonly used category names, or category names that form a
+ * convention.
+ */
+namespace Category {
+  /// The event category
+  constexpr const auto Event = "events";
+  /// The run category
+  constexpr const auto Run = "runs";
+  /// The metadata cateogry that is used to store a single Frame that holds data
+  /// that is valid for a whole file, e.g. collection level parameters
+  constexpr const auto Metadata = "metadata";
+} // namespace Category
+} // namespace podio
+
+#endif

tests/read_frame.h

@@ -77,22 +77,22 @@ int read_frames(const std::string& filename) {
     return 1;
   }
 
-  if (reader.getEntries("events") != 10) {
+  if (reader.getEntries(podio::Category::Event) != 10) {
     std::cerr << "Could not read back the number of events correctly. "
-              << "(expected:" << 10 << ", actual: " << reader.getEntries("events") << ")" << std::endl;
+              << "(expected:" << 10 << ", actual: " << reader.getEntries(podio::Category::Event) << ")" << std::endl;
     return 1;
   }
 
-  if (reader.getEntries("events") != reader.getEntries("other_events")) {
+  if (reader.getEntries(podio::Category::Event) != reader.getEntries("other_events")) {
     std::cerr << "Could not read back the number of events correctly. "
               << "(expected:" << 10 << ", actual: " << reader.getEntries("other_events") << ")" << std::endl;
     return 1;
   }
 
   // Read the frames in a different order than when writing them here to make
   // sure that the writing/reading order does not impose any usage requirements
-  for (size_t i = 0; i < reader.getEntries("events"); ++i) {
-    auto frame = podio::Frame(reader.readNextEntry("events"));
+  for (size_t i = 0; i < reader.getEntries(podio::Category::Event); ++i) {
+    auto frame = podio::Frame(reader.readNextEntry(podio::Category::Event));
     if (reader.currentFileVersion() > podio::version::Version{0, 16, 2}) {
       if (frame.get("emptySubsetColl") == nullptr) {
         std::cerr << "Could not retrieve an empty subset collection" << std::endl;
@@ -114,7 +114,7 @@ int read_frames(const std::string& filename) {
     }
   }
 
-  if (reader.readNextEntry("events")) {
+  if (reader.readNextEntry(podio::Category::Event)) {
     std::cerr << "Trying to read more frame data than is present should return a nullptr" << std::endl;
     return 1;
   }
@@ -127,10 +127,10 @@ int read_frames(const std::string& filename) {
 
   // Reading specific (jumping to) entry
   {
-    auto frame = podio::Frame(reader.readEntry("events", 4));
+    auto frame = podio::Frame(reader.readEntry(podio::Category::Event, 4));
     processEvent(frame, 4, reader.currentFileVersion());
     // Reading the next entry after jump, continues from after the jump
-    auto nextFrame = podio::Frame(reader.readNextEntry("events"));
+    auto nextFrame = podio::Frame(reader.readNextEntry(podio::Category::Event));
     processEvent(nextFrame, 5, reader.currentFileVersion());
 
     auto otherFrame = podio::Frame(reader.readEntry("other_events", 4));
@@ -147,7 +147,7 @@ int read_frames(const std::string& filename) {
     }
 
     // Trying to read a Frame that is not present returns a nullptr
-    if (reader.readEntry("events", 10)) {
+    if (reader.readEntry(podio::Category::Event, 10)) {
       std::cerr << "Trying to read a specific entry that does not exist should return a nullptr" << std::endl;
       return 1;
     }

tests/read_frame_auxiliary.h

@@ -56,9 +56,9 @@ int test_frame_aux_info(const std::string& fileName) {
   reader.openFile(fileName);
 
   // Test on the first event only here. Additionally, also only testing the
-  // "events" category, since that is the one where not all collections are
+  // events category, since that is the one where not all collections are
   // written
-  auto event = podio::Frame(reader.readEntry("events", 0));
+  auto event = podio::Frame(reader.readEntry(podio::Category::Event, 0));
 
   auto collsToRead = collsToWrite;
   if (reader.currentFileVersion() < podio::version::Version{0, 16, 3}) {

tests/write_frame.h

@@ -444,7 +444,7 @@ void write_frames(const std::string& filename) {
 
   for (int i = 0; i < 10; ++i) {
     auto frame = makeFrame(i);
-    writer.writeFrame(frame, "events", collsToWrite);
+    writer.writeFrame(frame, podio::Category::Event, collsToWrite);
   }
 
   for (int i = 100; i < 110; ++i) {