improve the doxygen docu of PStartupHandler.*
This commit is contained in:
@@ -49,15 +49,36 @@ ClassImpQ(PStartupHandler)
|
||||
// It is needed because in certain environments ParseFile does not work but ParseBuffer does.
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p> Replacement for the ParseFile method of TSAXParser.
|
||||
* \brief Replacement for TSAXParser::ParseFile() that uses buffer-based parsing.
|
||||
*
|
||||
* <p><b>return:</b>
|
||||
* - 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
|
||||
* <b>Algorithm:</b>
|
||||
* -# 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
|
||||
*
|
||||
* <b>Memory Management:</b>
|
||||
* 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
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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.
|
||||
*
|
||||
* <b>Search Order:</b>
|
||||
* -# 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)
|
||||
*
|
||||
* <b>File Creation:</b>
|
||||
* 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
|
||||
*
|
||||
* <b>Reset Mode:</b>
|
||||
* 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
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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.
|
||||
*
|
||||
* <b>Initialization:</b>
|
||||
* - 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
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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.
|
||||
*
|
||||
* <b>Recognized Elements:</b>
|
||||
* - \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)
|
||||
*
|
||||
* <b>Attribute Handling:</b>
|
||||
* 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
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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.
|
||||
*
|
||||
* <b>Element Processing:</b>
|
||||
*
|
||||
* - <b>eDataPath:</b> Adds path string directly to fDataPathList
|
||||
*
|
||||
* - <b>eRunNameTemplate:</b> Creates PRunNameTemplate with current instrument
|
||||
* name and template string, adds to fRunNameTemplate
|
||||
*
|
||||
* - <b>eMarker:</b> Validates numeric string, converts to int, adds to fMarkerList
|
||||
*
|
||||
* - <b>eColor:</b> Parses "R,G,B" format (comma-separated integers 0-255),
|
||||
* converts to ROOT color code via TColor::GetColor(), adds to fColorList
|
||||
*
|
||||
* - <b>eUnits:</b> Maps string to FOURIER_UNIT_* constant:
|
||||
* - "gauss" → FOURIER_UNIT_GAUSS
|
||||
* - "tesla" → FOURIER_UNIT_TESLA
|
||||
* - "mhz" → FOURIER_UNIT_FREQ
|
||||
* - "mc/s" → FOURIER_UNIT_CYCLES
|
||||
*
|
||||
* - <b>eFourierPower:</b> Validates integer 0-20, sets fFourierDefaults.fFourierPower
|
||||
*
|
||||
* - <b>eApodization:</b> Maps string to FOURIER_APOD_* constant:
|
||||
* - "none" → FOURIER_APOD_NONE
|
||||
* - "weak" → FOURIER_APOD_WEAK
|
||||
* - "medium" → FOURIER_APOD_MEDIUM
|
||||
* - "strong" → FOURIER_APOD_STRONG
|
||||
*
|
||||
* - <b>ePlot:</b> 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
|
||||
*
|
||||
* - <b>ePhase:</b> Validates float, adds to fFourierDefaults.fPhase vector
|
||||
*
|
||||
* - <b>ePhaseIncrement:</b> 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
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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 \<!-- and --\> delimiters)
|
||||
*
|
||||
* \note Comments in musrfit_startup.xml are for documentation purposes only
|
||||
* and have no effect on configuration.
|
||||
*/
|
||||
void PStartupHandler::OnComment(const Char_t *str)
|
||||
{
|
||||
@@ -477,9 +643,17 @@ void PStartupHandler::OnComment(const Char_t *str)
|
||||
// OnWarning
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Called when the XML parser emits a warning.
|
||||
* \brief SAX callback invoked when the XML parser generates a warning.
|
||||
*
|
||||
* \param str warning string
|
||||
* Outputs the warning message to stderr with a "PStartupHandler **WARNING**"
|
||||
* prefix. Warnings typically indicate non-fatal issues such as:
|
||||
* - Deprecated XML constructs
|
||||
* - Minor schema violations
|
||||
* - Character encoding issues
|
||||
*
|
||||
* \param str Warning message from the XML parser
|
||||
*
|
||||
* \note Parsing continues after warnings; they do not cause failure.
|
||||
*/
|
||||
void PStartupHandler::OnWarning(const Char_t *str)
|
||||
{
|
||||
@@ -491,9 +665,18 @@ void PStartupHandler::OnWarning(const Char_t *str)
|
||||
// OnError
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Called when the XML parser emits an error.
|
||||
* \brief SAX callback invoked when the XML parser encounters an error.
|
||||
*
|
||||
* \param str error string
|
||||
* Outputs the error message to stderr with a "PStartupHandler **ERROR**"
|
||||
* prefix. Errors indicate significant parsing problems such as:
|
||||
* - Malformed XML syntax
|
||||
* - Missing required elements
|
||||
* - Invalid attribute values
|
||||
*
|
||||
* \param str Error message from the XML parser
|
||||
*
|
||||
* \note Depending on error severity, parsing may or may not continue.
|
||||
* The configuration may be incomplete after errors.
|
||||
*/
|
||||
void PStartupHandler::OnError(const Char_t *str)
|
||||
{
|
||||
@@ -505,9 +688,19 @@ void PStartupHandler::OnError(const Char_t *str)
|
||||
// OnFatalError
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Called when the XML parser emits a fatal error.
|
||||
* \brief SAX callback invoked when the XML parser encounters a fatal error.
|
||||
*
|
||||
* \param str fatal error string
|
||||
* Outputs the error message to stderr with a "PStartupHandler **FATAL ERROR**"
|
||||
* prefix. Fatal errors indicate unrecoverable parsing failures such as:
|
||||
* - Document not well-formed (mismatched tags)
|
||||
* - Invalid XML declaration
|
||||
* - Character encoding that cannot be processed
|
||||
*
|
||||
* \param str Fatal error message from the XML parser
|
||||
*
|
||||
* \warning After a fatal error, parsing stops immediately and the configuration
|
||||
* will be incomplete. CheckLists() will provide default values for
|
||||
* missing settings when OnEndDocument() is called.
|
||||
*/
|
||||
void PStartupHandler::OnFatalError(const Char_t *str)
|
||||
{
|
||||
@@ -519,10 +712,17 @@ void PStartupHandler::OnFatalError(const Char_t *str)
|
||||
// OnCdataBlock
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Not used.
|
||||
* \brief SAX callback invoked when a CDATA section is encountered.
|
||||
*
|
||||
* \param str not used
|
||||
* \param len not used
|
||||
* Currently does nothing. CDATA sections in the startup file are not used.
|
||||
* CDATA sections would typically be used for content containing special
|
||||
* characters that would otherwise need escaping.
|
||||
*
|
||||
* \param str CDATA content (without \<![CDATA[ and ]]\> delimiters)
|
||||
* \param len Length of the CDATA content in characters
|
||||
*
|
||||
* \note The musrfit_startup.xml format does not require CDATA sections
|
||||
* as all content uses standard XML escaping where needed.
|
||||
*/
|
||||
void PStartupHandler::OnCdataBlock(const Char_t *str, Int_t len)
|
||||
{
|
||||
@@ -533,8 +733,35 @@ void PStartupHandler::OnCdataBlock(const Char_t *str, Int_t len)
|
||||
// CheckLists
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Check if the default lists are present and if not, feed them with some default settings
|
||||
* \brief Validates configuration lists and populates empty ones with defaults.
|
||||
*
|
||||
* Called at the end of XML parsing (OnEndDocument) to ensure all required
|
||||
* configuration lists have values. If any list is empty after parsing,
|
||||
* it is populated with sensible defaults.
|
||||
*
|
||||
* <b>Default Data Paths:</b>
|
||||
* Standard PSI facility data directories:
|
||||
* - /mnt/data/nemu/his, /mnt/data/nemu/wkm
|
||||
* - /afs/psi.ch/project/nemu/data/his, /afs/psi.ch/project/nemu/data/wkm
|
||||
* - /afs/psi.ch/project/bulkmusr/data/gps, dolly, gpd, ltf, alc
|
||||
*
|
||||
* <b>Default Markers:</b>
|
||||
* ROOT TMarker style codes for distinguishing multiple data sets:
|
||||
* - 24 (open circle), 25 (open square), 26 (open triangle)
|
||||
* - 27 (open diamond), 28 (open cross), 29 (full star)
|
||||
* - 30 (open star), 20 (full circle), 21 (full square)
|
||||
* - 22 (full triangle), 23 (full down triangle)
|
||||
* - 2 (thin cross), 3 (thin star), 5 (thin x)
|
||||
*
|
||||
* <b>Default Colors:</b>
|
||||
* Standard plotting colors (RGB → ROOT color code):
|
||||
* - Black (0,0,0), Red (255,0,0), Green (0,255,0)
|
||||
* - Blue (0,0,255), Magenta (255,0,255), Cyan (0,255,255)
|
||||
* - Violet (156,0,255), Yellow-ish (99,101,49)
|
||||
* - Dark Green (49,101,49), Orange (156,48,0)
|
||||
*
|
||||
* \note This method only populates empty lists. If a list has any entries
|
||||
* from the XML file, no defaults are added.
|
||||
*/
|
||||
void PStartupHandler::CheckLists()
|
||||
{
|
||||
@@ -590,13 +817,18 @@ void PStartupHandler::CheckLists()
|
||||
// StartupFileExists
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Checks if a file is present on the disc.
|
||||
* \brief Checks if a file exists and is readable at the specified path.
|
||||
*
|
||||
* <b>return:</b>
|
||||
* - true, if the file is present
|
||||
* - false, otherwise
|
||||
* Attempts to open the file for reading to verify its existence and
|
||||
* accessibility. The file is immediately closed after the check.
|
||||
*
|
||||
* \param fln file name
|
||||
* \param fln Full filesystem path to the file to check
|
||||
*
|
||||
* \return true if file exists and can be opened for reading,
|
||||
* false if file does not exist or cannot be accessed
|
||||
*
|
||||
* \note This method uses std::ifstream for portability across platforms.
|
||||
* It only checks readability, not write permissions.
|
||||
*/
|
||||
Bool_t PStartupHandler::StartupFileExists(Char_t *fln)
|
||||
{
|
||||
@@ -617,6 +849,52 @@ Bool_t PStartupHandler::StartupFileExists(Char_t *fln)
|
||||
//--------------------------------------------------------------------------
|
||||
// WriteDefaultStartupFile
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* \brief Creates or overwrites a startup configuration file with default content.
|
||||
*
|
||||
* Writes a complete musrfit_startup.xml file containing comprehensive default
|
||||
* settings for the musrfit package. This method is called when:
|
||||
* - No startup file is found in any search location
|
||||
* - User requests reset of existing configuration (reset_startup_file=true)
|
||||
*
|
||||
* <b>File Location:</b>
|
||||
* - If reset_startup_file=true: Overwrites file at fStartupFilePath
|
||||
* - If reset_startup_file=false: Creates new file at $HOME/.musrfit/musrfit_startup.xml
|
||||
* (creates .musrfit directory if it doesn't exist)
|
||||
*
|
||||
* <b>Default Content Includes:</b>
|
||||
*
|
||||
* <b>Data Paths:</b>
|
||||
* - PSI LEM, GPS, GPD, Dolly, Flame, HIFI, LTF, ALC data directories
|
||||
* - Both local mount points and AFS paths
|
||||
*
|
||||
* <b>Run Name Templates:</b>
|
||||
* - Templates for all PSI μSR instruments (GPS, GPD, Dolly, Flame, etc.)
|
||||
* - Templates for various data formats (ROOT, binary, MDU)
|
||||
* - Year and run number placeholder patterns
|
||||
*
|
||||
* <b>Fourier Settings:</b>
|
||||
* - Units: Gauss
|
||||
* - Fourier power: 0 (no zero-padding)
|
||||
* - Apodization: none
|
||||
* - Plot type: real_and_imag
|
||||
* - Phase: 0.0 degrees
|
||||
* - Phase increment: 1.0 degree
|
||||
*
|
||||
* <b>ROOT Settings:</b>
|
||||
* - Marker list: 14 distinct marker styles
|
||||
* - Color list: 10 distinct colors (RGB format)
|
||||
*
|
||||
* \param reset_startup_file If true, overwrites existing file at fStartupFilePath.
|
||||
* If false, creates new file at $HOME/.musrfit/musrfit_startup.xml.
|
||||
*
|
||||
* \return true if file was successfully written, false on error:
|
||||
* - $HOME environment variable not set
|
||||
* - Cannot create .musrfit directory
|
||||
* - Cannot open file for writing
|
||||
*
|
||||
* \see PStartupHandler() constructor, CheckLists()
|
||||
*/
|
||||
Bool_t PStartupHandler::WriteDefaultStartupFile(bool reset_startup_file)
|
||||
{
|
||||
Char_t startup_path_name[256];
|
||||
|
||||
@@ -41,62 +41,313 @@
|
||||
//--------------------------------------------------------------------------
|
||||
// This function is a replacement for the ParseFile method of TSAXParser.
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* \brief Replacement function for TSAXParser::ParseFile().
|
||||
*
|
||||
* This standalone function provides a workaround for environments where
|
||||
* TSAXParser::ParseFile() does not work correctly but ParseBuffer() does.
|
||||
* It reads the entire XML file into memory and then parses it as a buffer.
|
||||
*
|
||||
* \param saxParser Pointer to an initialized TSAXParser object with connected slots
|
||||
* \param startup_path_name Full path to the XML file to be parsed
|
||||
*
|
||||
* \return Parse status:
|
||||
* - 0: Success
|
||||
* - 1: File could not be read
|
||||
* - Other: XML parse error code from TSAXParser::ParseBuffer()
|
||||
*
|
||||
* \see PStartupHandler
|
||||
*/
|
||||
int parseXmlFile(TSAXParser*, const char*);
|
||||
|
||||
/**
|
||||
* <p>Handles the XML musrfit startup file (musrfit_startup.xml) in which default settings
|
||||
* are stored:
|
||||
* - list of search paths for the data files
|
||||
* - Fourier transform default settings
|
||||
* - marker list for plotting
|
||||
* - color list for plotting
|
||||
* \brief Handles the musrfit XML startup configuration file (musrfit_startup.xml).
|
||||
*
|
||||
* PStartupHandler is responsible for locating, parsing, and providing access to
|
||||
* the musrfit startup configuration file. This XML file contains default settings
|
||||
* that customize musrfit behavior across different installations and user preferences.
|
||||
*
|
||||
* \section startup_contents Configuration File Contents
|
||||
*
|
||||
* The musrfit_startup.xml file stores:
|
||||
* - <b>Data search paths:</b> Directories to search for μSR data files
|
||||
* - <b>Run name templates:</b> Instrument-specific patterns for constructing data file paths
|
||||
* - <b>Fourier transform defaults:</b> Units, apodization, plot type, phase settings
|
||||
* - <b>ROOT marker list:</b> Marker styles for data point display
|
||||
* - <b>ROOT color list:</b> RGB colors for multi-run plotting
|
||||
*
|
||||
* \section startup_search File Search Order
|
||||
*
|
||||
* The startup file is searched in the following locations (first found wins):
|
||||
* -# Current working directory: \c ./musrfit_startup.xml
|
||||
* -# User config directory: \c $HOME/.musrfit/musrfit_startup.xml
|
||||
* -# MUSRFITPATH environment: \c $MUSRFITPATH/musrfit_startup.xml
|
||||
* -# ROOT installation: \c $ROOTSYS/bin/musrfit_startup.xml (with warning)
|
||||
*
|
||||
* If no file is found, a default configuration is automatically created in
|
||||
* \c $HOME/.musrfit/musrfit_startup.xml.
|
||||
*
|
||||
* \section startup_xml XML File Structure
|
||||
*
|
||||
* \code{.xml}
|
||||
* <?xml version="1.0" encoding="UTF-8"?>
|
||||
* <musrfit xmlns="http://lmu.web.psi.ch/musrfit/user/MUSR/WebHome.html">
|
||||
* <comment>Configuration description</comment>
|
||||
* <data_path>/path/to/data/directory</data_path>
|
||||
* <run_name_template inst="gps">d%yyyy%/tdc/root/deltat_tdc_gps_%yyyy%_%rrrr%.root</run_name_template>
|
||||
* <fourier_settings>
|
||||
* <units>Gauss</units>
|
||||
* <fourier_power>0</fourier_power>
|
||||
* <apodization>none</apodization>
|
||||
* <plot>real_and_imag</plot>
|
||||
* <phase>0.0</phase>
|
||||
* <phase_increment>1.0</phase_increment>
|
||||
* </fourier_settings>
|
||||
* <root_settings>
|
||||
* <marker_list>
|
||||
* <marker>24</marker>
|
||||
* </marker_list>
|
||||
* <color_list>
|
||||
* <color>255,0,0</color>
|
||||
* </color_list>
|
||||
* </root_settings>
|
||||
* </musrfit>
|
||||
* \endcode
|
||||
*
|
||||
* \section startup_templates Run Name Templates
|
||||
*
|
||||
* Run name templates use placeholders for automatic file path construction:
|
||||
* - \c %yyyy% : 4-digit year (e.g., 2024)
|
||||
* - \c %yy% : 2-digit year (e.g., 24)
|
||||
* - \c %rrrr% : 4-digit run number with leading zeros
|
||||
* - \c %rrrrr% : 5-digit run number with leading zeros
|
||||
*
|
||||
* Example: \c d%yyyy%/tdc/root/deltat_tdc_gps_%yyyy%_%rrrr%.root
|
||||
* → \c d2024/tdc/root/deltat_tdc_gps_2024_1234.root
|
||||
*
|
||||
* \section startup_sax SAX Parser Implementation
|
||||
*
|
||||
* This class implements the TQObject signal/slot mechanism to handle SAX parser
|
||||
* callbacks. The parser events trigger the following methods:
|
||||
* - OnStartDocument(): Initialize default values
|
||||
* - OnStartElement(): Identify XML element type, set parsing state
|
||||
* - OnCharacters(): Extract element content
|
||||
* - OnEndElement(): Reset parsing state
|
||||
* - OnEndDocument(): Validate and fill missing defaults
|
||||
* - OnWarning/OnError/OnFatalError(): Error handling
|
||||
*
|
||||
* \section startup_usage Usage Example
|
||||
*
|
||||
* \code{.cpp}
|
||||
* // Create handler (searches for and parses startup file)
|
||||
* PStartupHandler startupHandler;
|
||||
*
|
||||
* // Check if configuration was loaded successfully
|
||||
* if (startupHandler.StartupFileFound()) {
|
||||
* // Get data search paths
|
||||
* PStringVector paths = startupHandler.GetDataPathList();
|
||||
*
|
||||
* // Get Fourier transform defaults
|
||||
* PMsrFourierStructure fourier = startupHandler.GetFourierDefaults();
|
||||
*
|
||||
* // Get plotting colors and markers
|
||||
* PIntVector colors = startupHandler.GetColorList();
|
||||
* PIntVector markers = startupHandler.GetMarkerList();
|
||||
* }
|
||||
* \endcode
|
||||
*
|
||||
* \see PMsrHandler for MSR file parsing
|
||||
* \see PRunDataHandler for data file loading with path resolution
|
||||
*/
|
||||
class PStartupHandler : public TObject, public TQObject
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* \brief Constructor that locates and parses the musrfit startup configuration file.
|
||||
*
|
||||
* Searches for musrfit_startup.xml in standard locations and parses it if found.
|
||||
* If no file is found, creates a default configuration in $HOME/.musrfit/.
|
||||
*
|
||||
* <b>Search order:</b>
|
||||
* -# ./musrfit_startup.xml (current directory)
|
||||
* -# $HOME/.musrfit/musrfit_startup.xml
|
||||
* -# $MUSRFITPATH/musrfit_startup.xml
|
||||
* -# $ROOTSYS/bin/musrfit_startup.xml (with warning)
|
||||
*
|
||||
* \param reset_startup_file If true and file is found, rewrites it with default content.
|
||||
* Useful for restoring corrupted or outdated configurations.
|
||||
*
|
||||
* \note The actual XML parsing is performed by connecting this handler to a TSAXParser
|
||||
* and calling parseXmlFile() externally.
|
||||
*
|
||||
* \see StartupFileFound(), GetStartupFilePath()
|
||||
*/
|
||||
PStartupHandler(bool reset_startup_file=false);
|
||||
|
||||
/**
|
||||
* \brief Destructor releasing allocated resources.
|
||||
*
|
||||
* Clears all configuration vectors:
|
||||
* - fDataPathList
|
||||
* - fMarkerList
|
||||
* - fColorList
|
||||
* - fRunNameTemplate
|
||||
*/
|
||||
virtual ~PStartupHandler();
|
||||
|
||||
/** \brief SAX callback: Called when XML document parsing begins.
|
||||
* Initializes all configuration variables to default values. */
|
||||
virtual void OnStartDocument(); // SLOT
|
||||
|
||||
/** \brief SAX callback: Called when XML document parsing ends.
|
||||
* Triggers CheckLists() to ensure all required settings have values. */
|
||||
virtual void OnEndDocument(); // SLOT
|
||||
|
||||
/** \brief SAX callback: Called when an XML start element is encountered.
|
||||
* \param str Element name (e.g., "data_path", "marker", "units")
|
||||
* \param attributes XML attributes (used for inst attribute in run_name_template) */
|
||||
virtual void OnStartElement(const Char_t*, const TList*); // SLOT
|
||||
|
||||
/** \brief SAX callback: Called when an XML end element is encountered.
|
||||
* \param str Element name (unused, resets parsing state) */
|
||||
virtual void OnEndElement(const Char_t*); // SLOT
|
||||
|
||||
/** \brief SAX callback: Called with element text content.
|
||||
* \param str Text content between XML tags (the actual configuration values) */
|
||||
virtual void OnCharacters(const Char_t*); // SLOT
|
||||
|
||||
/** \brief SAX callback: Called when XML comment is found (unused).
|
||||
* \param str Comment text */
|
||||
virtual void OnComment(const Char_t*); // SLOT
|
||||
|
||||
/** \brief SAX callback: Called when XML parser issues a warning.
|
||||
* \param str Warning message (output to stderr) */
|
||||
virtual void OnWarning(const Char_t*); // SLOT
|
||||
|
||||
/** \brief SAX callback: Called when XML parser encounters an error.
|
||||
* \param str Error message (output to stderr) */
|
||||
virtual void OnError(const Char_t*); // SLOT
|
||||
|
||||
/** \brief SAX callback: Called when XML parser encounters a fatal error.
|
||||
* \param str Fatal error message (output to stderr) */
|
||||
virtual void OnFatalError(const Char_t*); // SLOT
|
||||
|
||||
/** \brief SAX callback: Called for CDATA blocks (unused).
|
||||
* \param str CDATA content
|
||||
* \param len Length of CDATA content */
|
||||
virtual void OnCdataBlock(const Char_t*, Int_t); // SLOT
|
||||
|
||||
virtual Bool_t StartupFileFound() { return fStartupFileFound; } ///< true = musrfit_startup.xml found
|
||||
virtual TString GetStartupFilePath() { return fStartupFilePath; } ///< returns FULLPATH/musrfit_startup.xml, where FULLPATH=path were the musrfit_startup.xml is found
|
||||
/**
|
||||
* \brief Checks if the startup configuration file was successfully located.
|
||||
* \return true if musrfit_startup.xml was found (in any search location), false otherwise
|
||||
*/
|
||||
virtual Bool_t StartupFileFound() { return fStartupFileFound; }
|
||||
|
||||
/**
|
||||
* \brief Returns the full path to the located startup configuration file.
|
||||
* \return Full path including filename (e.g., "/home/user/.musrfit/musrfit_startup.xml"),
|
||||
* or empty string if not found
|
||||
*/
|
||||
virtual TString GetStartupFilePath() { return fStartupFilePath; }
|
||||
|
||||
/**
|
||||
* \brief Validates configuration lists and fills missing entries with defaults.
|
||||
*
|
||||
* Called at end of XML parsing to ensure all required lists have values.
|
||||
* If a list is empty, populates it with sensible defaults:
|
||||
* - Data paths: PSI facility standard locations
|
||||
* - Markers: ROOT marker codes (circles, squares, triangles, etc.)
|
||||
* - Colors: Standard plotting colors (black, red, green, blue, etc.)
|
||||
*/
|
||||
virtual void CheckLists();
|
||||
|
||||
virtual PMsrFourierStructure GetFourierDefaults() { return fFourierDefaults; } ///< returns the Fourier defaults
|
||||
/**
|
||||
* \brief Returns Fourier transform default settings.
|
||||
* \return PMsrFourierStructure containing units, apodization, plot type, phase settings
|
||||
*/
|
||||
virtual PMsrFourierStructure GetFourierDefaults() { return fFourierDefaults; }
|
||||
|
||||
/**
|
||||
* \brief Returns the list of instrument-specific run name templates.
|
||||
* \return Vector of PRunNameTemplate structures (instrument name + path pattern)
|
||||
*/
|
||||
virtual const PRunNameTemplateList GetRunNameTemplateList() { return fRunNameTemplate; }
|
||||
virtual const PStringVector GetDataPathList() const { return fDataPathList; } ///< returns the search data path list
|
||||
virtual const PIntVector GetMarkerList() const { return fMarkerList; } ///< returns the marker list
|
||||
virtual const PIntVector GetColorList() const { return fColorList; } ///< returns the color list
|
||||
|
||||
/**
|
||||
* \brief Returns the list of data file search paths.
|
||||
* \return Vector of directory paths to search for μSR data files
|
||||
*/
|
||||
virtual const PStringVector GetDataPathList() const { return fDataPathList; }
|
||||
|
||||
/**
|
||||
* \brief Returns the list of ROOT marker codes for plotting.
|
||||
* \return Vector of ROOT TMarker style codes (e.g., 24=open circle, 25=open square)
|
||||
*/
|
||||
virtual const PIntVector GetMarkerList() const { return fMarkerList; }
|
||||
|
||||
/**
|
||||
* \brief Returns the list of ROOT color codes for plotting.
|
||||
* \return Vector of ROOT TColor codes (generated from RGB values)
|
||||
*/
|
||||
virtual const PIntVector GetColorList() const { return fColorList; }
|
||||
|
||||
private:
|
||||
enum EKeyWords {eEmpty, eComment, eDataPath, eRunNameTemplate, eOptions,
|
||||
eFourierSettings, eUnits, eFourierPower,
|
||||
eApodization, ePlot, ePhase, ePhaseIncrement,
|
||||
eRootSettings, eMarkerList, eMarker,
|
||||
eColorList, eColor};
|
||||
EKeyWords fKey; ///< xml filter key
|
||||
/**
|
||||
* \brief Enumeration of XML element types for SAX parser state machine.
|
||||
*
|
||||
* Used by OnStartElement() to set parsing context and by OnCharacters()
|
||||
* to determine how to interpret element content.
|
||||
*/
|
||||
enum EKeyWords {
|
||||
eEmpty, ///< No active element (between elements or unknown)
|
||||
eComment, ///< Inside \<comment\> element
|
||||
eDataPath, ///< Inside \<data_path\> element
|
||||
eRunNameTemplate, ///< Inside \<run_name_template\> element
|
||||
eOptions, ///< Inside \<options\> element (reserved)
|
||||
eFourierSettings, ///< Inside \<fourier_settings\> container
|
||||
eUnits, ///< Inside \<units\> element (Gauss/Tesla/MHz/Mc/s)
|
||||
eFourierPower, ///< Inside \<fourier_power\> element (0-20)
|
||||
eApodization, ///< Inside \<apodization\> element (none/weak/medium/strong)
|
||||
ePlot, ///< Inside \<plot\> element (real/imag/real_and_imag/power/phase)
|
||||
ePhase, ///< Inside \<phase\> element (degrees)
|
||||
ePhaseIncrement, ///< Inside \<phase_increment\> element (degrees per step)
|
||||
eRootSettings, ///< Inside \<root_settings\> container
|
||||
eMarkerList, ///< Inside \<marker_list\> container
|
||||
eMarker, ///< Inside \<marker\> element (ROOT marker code)
|
||||
eColorList, ///< Inside \<color_list\> container
|
||||
eColor ///< Inside \<color\> element (RGB comma-separated)
|
||||
};
|
||||
|
||||
Bool_t fStartupFileFound; ///< startup file found flag
|
||||
TString fStartupFilePath; ///< full musrfit_startup.xml startup file paths
|
||||
TString fCurrentInstrumentName; ///< current instrument name
|
||||
PMsrFourierStructure fFourierDefaults; ///< Fourier defaults
|
||||
PStringVector fDataPathList; ///< search data path list
|
||||
PRunNameTemplateList fRunNameTemplate; ///< run name template vector
|
||||
PIntVector fMarkerList; ///< marker list
|
||||
PIntVector fColorList; ///< color list
|
||||
EKeyWords fKey; ///< Current XML element type (SAX parser state)
|
||||
Bool_t fStartupFileFound; ///< True if musrfit_startup.xml was located
|
||||
TString fStartupFilePath; ///< Full path to located startup file (empty if not found)
|
||||
TString fCurrentInstrumentName; ///< Instrument name from run_name_template inst attribute
|
||||
PMsrFourierStructure fFourierDefaults; ///< Fourier transform default settings structure
|
||||
PStringVector fDataPathList; ///< List of directories to search for data files
|
||||
PRunNameTemplateList fRunNameTemplate; ///< List of instrument-specific run name patterns
|
||||
PIntVector fMarkerList; ///< List of ROOT TMarker style codes for plotting
|
||||
PIntVector fColorList; ///< List of ROOT TColor codes (from RGB) for plotting
|
||||
|
||||
/**
|
||||
* \brief Checks if a file exists at the specified path.
|
||||
* \param fln Full path to check
|
||||
* \return true if file exists and is readable, false otherwise
|
||||
*/
|
||||
Bool_t StartupFileExists(Char_t *fln);
|
||||
|
||||
/**
|
||||
* \brief Creates or overwrites a startup file with default configuration.
|
||||
*
|
||||
* Writes a complete musrfit_startup.xml with:
|
||||
* - Standard PSI data paths
|
||||
* - Run name templates for all PSI instruments
|
||||
* - Default Fourier settings
|
||||
* - Standard marker and color lists
|
||||
*
|
||||
* \param reset_startup_file If true, overwrites existing file at fStartupFilePath.
|
||||
* If false, creates new file at $HOME/.musrfit/musrfit_startup.xml.
|
||||
* \return true on success, false on write failure
|
||||
*/
|
||||
Bool_t WriteDefaultStartupFile(bool reset_startup_file=false);
|
||||
|
||||
ClassDef(PStartupHandler, 1)
|
||||
|
||||
Reference in New Issue
Block a user