Replacement for the ParseFile method of TSAXParser. + * \brief Replacement for TSAXParser::ParseFile() that uses buffer-based parsing. * - *
return: - * - 1 if file cannot be read - * - 0 if the file has been parsed successfully - * - parse error code otherwise + * This function provides a workaround for environments where the standard + * TSAXParser::ParseFile() method fails but ParseBuffer() works correctly. + * It reads the entire XML file into memory and then parses it as a buffer. * - * \param saxParser pointer to a TSAXParser object - * \param startup_path_name full path to the XML file to be read + * Algorithm: + * -# Open XML file in binary mode, positioned at end to determine size + * -# Allocate buffer for entire file content + * -# Read file into buffer + * -# Close file + * -# Call saxParser->ParseBuffer() with buffer contents + * -# Free buffer memory + * + * Memory Management: + * The function allocates a buffer equal to the file size, which is freed + * after parsing completes. For very large XML files, this may consume + * significant memory temporarily. + * + * \param saxParser Pointer to an initialized TSAXParser object. The parser + * should have its signal slots connected to a handler object + * (e.g., PStartupHandler) before calling this function. + * \param startup_path_name Full filesystem path to the XML file to be parsed. + * + * \return Parse status code: + * - 0: Success (file parsed without errors) + * - 1: File could not be opened or read + * - Other: XML parse error code from TSAXParser::ParseBuffer() + * + * \see PStartupHandler for the XML content handler implementation */ int parseXmlFile(TSAXParser *saxParser, const char *startup_path_name) { @@ -89,7 +110,40 @@ int parseXmlFile(TSAXParser *saxParser, const char *startup_path_name) // Constructor //-------------------------------------------------------------------------- /** - *
Constructor. Check if the musrfit_startup.xml file is found in some standard search paths + * \brief Constructor that locates and optionally resets the musrfit startup configuration. + * + * Searches for the musrfit_startup.xml configuration file in standard locations + * and initializes the handler. If no file is found, creates a default configuration. + * + * Search Order: + * -# Current working directory: \c ./musrfit_startup.xml + * -# User config directory: \c $HOME/.musrfit/musrfit_startup.xml + * -# MUSRFITPATH environment variable: \c $MUSRFITPATH/musrfit_startup.xml + * -# ROOT installation: \c $ROOTSYS/bin/musrfit_startup.xml (with warning) + * + * File Creation: + * If no startup file is found in any location, a default configuration is + * automatically created at \c $HOME/.musrfit/musrfit_startup.xml. This includes: + * - Standard PSI facility data paths + * - Run name templates for all PSI instruments + * - Default Fourier transform settings + * - Standard marker and color lists + * + * Reset Mode: + * When reset_startup_file=true and a file is found, the existing file is + * overwritten with default content. This is useful for: + * - Restoring corrupted configurations + * - Updating to new default settings after software updates + * - Resetting user customizations to defaults + * + * \param reset_startup_file If true, overwrites existing startup file with defaults. + * If false (default), uses existing file or creates new one. + * + * \note This constructor only locates the file. Actual XML parsing must be + * performed separately by connecting this handler to a TSAXParser and + * calling parseXmlFile(). + * + * \see StartupFileFound(), GetStartupFilePath(), WriteDefaultStartupFile() */ PStartupHandler::PStartupHandler(bool reset_startup_file) { @@ -178,7 +232,16 @@ PStartupHandler::PStartupHandler(bool reset_startup_file) // Destructor //-------------------------------------------------------------------------- /** - *
Destructor + * \brief Destructor that releases all allocated configuration data. + * + * Clears all configuration vectors to free memory: + * - fDataPathList: Data file search paths + * - fMarkerList: ROOT marker style codes + * - fColorList: ROOT color codes + * - fRunNameTemplate: Instrument run name patterns + * + * \note The Fourier defaults structure is a value type and is automatically + * cleaned up when the object is destroyed. */ PStartupHandler::~PStartupHandler() { @@ -193,7 +256,25 @@ PStartupHandler::~PStartupHandler() // OnStartDocument //-------------------------------------------------------------------------- /** - *
Called on start of the XML file reading. Initializes all necessary variables. + * \brief SAX callback invoked at the start of XML document parsing. + * + * Initializes all configuration variables to default values before parsing + * begins. This ensures a clean state even if the same handler is reused. + * + * Initialization: + * - fKey = eEmpty (no active element) + * - Fourier defaults: + * - fFourierBlockPresent = false + * - fUnits = FOURIER_UNIT_GAUSS + * - fFourierPower = 0 (no zero-padding) + * - fApodization = FOURIER_APOD_NONE + * - fPlotTag = FOURIER_PLOT_REAL_AND_IMAG + * - fRangeForPhaseCorrection = [-1.0, -1.0] (auto) + * - fPlotRange = [-1.0, -1.0] (auto) + * - fPhaseIncrement = 1.0 degree + * + * \note This is a SAX parser callback connected via TQObject signals. + * It is automatically called by TSAXParser at document start. */ void PStartupHandler::OnStartDocument() { @@ -216,7 +297,16 @@ void PStartupHandler::OnStartDocument() // OnEndDocument //-------------------------------------------------------------------------- /** - *
Called on end of XML file reading. + * \brief SAX callback invoked at the end of XML document parsing. + * + * Finalizes configuration by calling CheckLists() to ensure all required + * settings have values. If any list is empty after parsing, it will be + * populated with default values. + * + * \note This is a SAX parser callback connected via TQObject signals. + * It is automatically called by TSAXParser when parsing completes. + * + * \see CheckLists() */ void PStartupHandler::OnEndDocument() { @@ -228,11 +318,33 @@ void PStartupHandler::OnEndDocument() // OnStartElement //-------------------------------------------------------------------------- /** - *
Called when a XML start element is found. Filters out the needed elements - * and sets a proper key. + * \brief SAX callback invoked when an XML start element tag is encountered. * - * \param str XML element name - * \param attributes not used + * Identifies the element type and sets the parsing state (fKey) accordingly. + * This state is used by OnCharacters() to determine how to process element content. + * + * Recognized Elements: + * - \c data_path → eDataPath (data file search directory) + * - \c run_name_template → eRunNameTemplate (with inst attribute extraction) + * - \c marker → eMarker (ROOT marker style code) + * - \c color → eColor (RGB color specification) + * - \c units → eUnits (Fourier frequency units) + * - \c fourier_power → eFourierPower (zero-padding power) + * - \c apodization → eApodization (windowing function) + * - \c plot → ePlot (Fourier plot type) + * - \c phase → ePhase (Fourier phase value) + * - \c phase_increment → ePhaseIncrement (phase adjustment step) + * + * Attribute Handling: + * For \c run_name_template elements, extracts the \c inst attribute value + * and stores it in fCurrentInstrumentName for use when processing the + * element content. + * + * \param str XML element name (tag name without angle brackets) + * \param attributes TList of TXMLAttr objects containing element attributes + * + * \note Unrecognized elements leave fKey unchanged (typically eEmpty), + * causing their content to be ignored. */ void PStartupHandler::OnStartElement(const Char_t *str, const TList *attributes) { @@ -270,9 +382,15 @@ void PStartupHandler::OnStartElement(const Char_t *str, const TList *attributes) // OnEndElement //-------------------------------------------------------------------------- /** - *
Called when a XML end element is found. Resets the handler key. + * \brief SAX callback invoked when an XML end element tag is encountered. * - * \param str not used + * Resets the parsing state (fKey) to eEmpty, indicating that any subsequent + * character data should be ignored until the next start element is found. + * + * \param str XML element name (unused, state is always reset to eEmpty) + * + * \note The element name parameter is not used because all elements reset + * to the same state. This simplifies handling of nested elements. */ void PStartupHandler::OnEndElement(const Char_t *str) { @@ -283,10 +401,53 @@ void PStartupHandler::OnEndElement(const Char_t *str) // OnCharacters //-------------------------------------------------------------------------- /** - *
Content of a given XML element. Filters out the data and feeds them to - * the internal variables. + * \brief SAX callback invoked with text content between XML element tags. * - * \param str XML element string + * Processes element content based on the current parsing state (fKey) set + * by OnStartElement(). Each element type has specific parsing logic and + * validation. + * + * Element Processing: + * + * - eDataPath: Adds path string directly to fDataPathList + * + * - eRunNameTemplate: Creates PRunNameTemplate with current instrument + * name and template string, adds to fRunNameTemplate + * + * - eMarker: Validates numeric string, converts to int, adds to fMarkerList + * + * - eColor: Parses "R,G,B" format (comma-separated integers 0-255), + * converts to ROOT color code via TColor::GetColor(), adds to fColorList + * + * - eUnits: Maps string to FOURIER_UNIT_* constant: + * - "gauss" → FOURIER_UNIT_GAUSS + * - "tesla" → FOURIER_UNIT_TESLA + * - "mhz" → FOURIER_UNIT_FREQ + * - "mc/s" → FOURIER_UNIT_CYCLES + * + * - eFourierPower: Validates integer 0-20, sets fFourierDefaults.fFourierPower + * + * - eApodization: Maps string to FOURIER_APOD_* constant: + * - "none" → FOURIER_APOD_NONE + * - "weak" → FOURIER_APOD_WEAK + * - "medium" → FOURIER_APOD_MEDIUM + * - "strong" → FOURIER_APOD_STRONG + * + * - ePlot: Maps string to FOURIER_PLOT_* constant: + * - "real" → FOURIER_PLOT_REAL + * - "imag" → FOURIER_PLOT_IMAG + * - "real_and_imag" → FOURIER_PLOT_REAL_AND_IMAG + * - "power" → FOURIER_PLOT_POWER + * - "phase" → FOURIER_PLOT_PHASE + * + * - ePhase: Validates float, adds to fFourierDefaults.fPhase vector + * + * - ePhaseIncrement: Validates float, sets fFourierDefaults.fPhaseIncrement + * + * \param str Text content between XML tags + * + * \note Invalid values generate warning messages to stderr but do not cause + * parsing to fail. The invalid value is simply ignored. */ void PStartupHandler::OnCharacters(const Char_t *str) { @@ -464,9 +625,14 @@ void PStartupHandler::OnCharacters(const Char_t *str) // OnComment //-------------------------------------------------------------------------- /** - *
Called when a XML comment is found. Not used. + * \brief SAX callback invoked when an XML comment is encountered. * - * \param str not used. + * Currently does nothing. XML comments in the startup file are ignored. + * + * \param str Comment text content (without \