include/G4OCCT/G4OCCTSensitiveDetectorMapReader.hh

0001 // SPDX-License-Identifier: LGPL-2.1-or-later
0002 // Copyright (C) 2026 G4OCCT Contributors
0003
0004 /// @file G4OCCTSensitiveDetectorMapReader.hh
0005 /// @brief Declaration of G4OCCTSensitiveDetectorMapReader.
0006
0007 #ifndef G4OCCT_G4OCCTSensitiveDetectorMapReader_hh
0008 #define G4OCCT_G4OCCTSensitiveDetectorMapReader_hh
0009
0010 #include "G4OCCT/G4OCCTSensitiveDetectorMap.hh"
0011
0012 #include <G4String.hh>
0013
0014 /**
0015  * @brief Parses an XML sensitive-detector-map file into a G4OCCTSensitiveDetectorMap.
0016  *
0017  * Reads a simple XML file and resolves sensitive detector names via
0018  * `G4SDManager`.  **This reader must be called after all sensitive detectors
0019  * have been registered in `G4SDManager`.**
0020  *
0021  * ## File format
0022  *
0023  * The root element must be `<sensitive_detector_map>`.  Each child
0024  * `<volume>` element carries two required attributes:
0025  *
0026  * - `name`    — volume name pattern used for matching (see
0027  *               `G4OCCTSensitiveDetectorMap` for matching rules).
0028  * - `sensDet` — the sensitive detector name as registered in `G4SDManager`
0029  *               (i.e. the string passed to
0030  *               `G4SDManager::AddNewDetector()`).
0031  *
0032  * ```xml
0033  * <sensitive_detector_map>
0034  *   <volume name="Absorber" sensDet="AbsorberSD"/>
0035  *   <volume name="Gap"      sensDet="GapSD"/>
0036  * </sensitive_detector_map>
0037  * ```
0038  *
0039  * ## Error codes
0040  *
0041  * | Code                  | Condition                                      |
0042  * |-----------------------|------------------------------------------------|
0043  * | `G4OCCT_SDReader000`  | `<volume>` element missing `name` attribute    |
0044  * | `G4OCCT_SDReader001`  | `<volume>` element missing `sensDet` attribute |
0045  * | `G4OCCT_SDReader002`  | SD name not found in `G4SDManager`             |
0046  * | `G4OCCT_SDReader003`  | Xerces `XMLException` during parse             |
0047  * | `G4OCCT_SDReader004`  | Xerces `DOMException` during parse             |
0048  * | `G4OCCT_SDReader005`  | Null DOM document after parse                  |
0049  * | `G4OCCT_SDReader006`  | Null root element                              |
0050  * | `G4OCCT_SDReader007`  | Wrong root tag (not `sensitive_detector_map`)  |
0051  *
0052  * ## Usage
0053  * ```cpp
0054  * // After SDs are registered:
0055  * G4OCCTSensitiveDetectorMapReader reader;
0056  * G4OCCTSensitiveDetectorMap sdMap = reader.ReadFile("sd_map.xml");
0057  * ```
0058  */
0059 class G4OCCTSensitiveDetectorMapReader {
0060 public:
0061   G4OCCTSensitiveDetectorMapReader()  = default;
0062   ~G4OCCTSensitiveDetectorMapReader() = default;
0063
0064   /**
0065    * Parse the sensitive-detector-map XML file at @p path and return the
0066    * populated map.
0067    *
0068    * Must be called **after** all sensitive detectors have been registered
0069    * in `G4SDManager`.
0070    *
0071    * @param path Filesystem path to the XML sensitive-detector-map file.
0072    * @return `G4OCCTSensitiveDetectorMap` with one entry per `<volume>` element.
0073    * @throws G4Exception (FatalException) on any parse or resolution error.
0074    */
0075   G4OCCTSensitiveDetectorMap ReadFile(const G4String& path);
0076 };
0077
0078 #endif // G4OCCT_G4OCCTSensitiveDetectorMapReader_hh