//-----------------------------------------------------------------------
/**
 * \mainpage FrameCPP Library
 *
 * @anchor LDASToolsFrameCPP
 *
 * The FrameCPP library is intended to allow easy reading and writing of
 * frame streams.
 * The library currently implements
 * <I>Specification of a Common Data Frame Format for Interferometric Gravitational Wave Detectors</I>
 * as referenced by DCC numbers LIGO-T970130-B-E through LIGO-T9670130-v1.
 * Several interfaces are defined allowing developers to read and write frames using
 * one of several languages.
 * There are also utility programs allowing for basic frame generation, inspection, validation
 * and correction.
 *
 * \section user_sec Users
 *
 * This package provides the following command line tools.
 * 
 *  \li \ref CommandFramecppCompressor
 *  \li \ref CommandFramecppDumpChannel
 *  \li \ref CommandFramecppDumpObjects
 *  \li \ref CommandFramecppDumpToc
 *  \li \ref CommandFramecppFixMetadata
 *  \li \ref CommandFramecppQuery
 *  \li \ref CommandFramecppSample
 *  \li \ref CommandFramecppVerify
 *  \li \ref CommandFramecppChecksum
 *
 * \section devel_sec Developers
 *
 * \li \ref FrameCPPCPlusPlusInterface
 * \li \ref FrameCPPCInterface
 * \li \ref FrameCPPPythonInterface
 * \li \ref FrameCPPDebugArchiver
 *
 */
//-----------------------------------------------------------------------

/**
 * \page FrameCPPDebugArchiver Frame Debug Archiver
 *
 * @anchor FrameCPPDebugArchiver
 *
 * The Frame Debug Archiver provides comprehensive debugging capabilities for Frame structures
 * using human-readable output with configurable formatting options. It leverages the existing
 * boost serialization infrastructure to automatically extract field names and values from
 * any Frame type.
 *
 * \section debug_features Key Features
 *
 * \li **Automatic Field Extraction**: Uses boost::serialization to access private fields with proper names
 * \li **Multiple Alignment Modes**: NONE (compact), SEPARATOR (right-aligned names), COLUMNS (tabular format)
 * \li **Version-Aware Output**: Supports all Frame specification versions (3-9) with version-specific formatting
 * \li **Type Information**: Shows human-readable C++ type names using automatic demangling
 * \li **Configurable Formatting**: Customizable separators, indentation, field widths, and display options
 * \li **Universal Compatibility**: Works with all Frame types (FrTOCData, FrameH, FrVect, FrTable, etc.)
 *
 * \section debug_usage Basic Usage Examples
 *
 * \subsection debug_simple Simple Usage
 * ```cpp
 * #include "framecpp/OOInterface/FrameDebugPrint.hh"
 * 
 * // Create any Frame object
 * FrameCPP::Universal::FrTOCData tocData;
 * FrameCPP::Universal::FrameH frameHeader;
 * FrameCPP::Universal::FrVect vector;
 * 
 * // Simple debug printing with defaults
 * FrameCPP::Debug::FramePrinter printer;
 * printer(tocData);     // Uses version=9, SEPARATOR alignment, std::cout
 * printer(frameHeader); // Same configuration for different type
 * printer(vector);      // Works with any Frame type
 * ```
 *
 * \subsection debug_config Configured Usage
 * ```cpp
 * // Method chaining for configuration
 * printer.setAlignment(FrameCPP::Debug::AlignmentMode::COLUMNS)
 *        .setVersion(7)
 *        .setSeparator(" => ")
 *        .setIndentation(4)
 *        .showTypeInfo(false);
 * printer(frameHeader);
 * 
 * // Direct attribute modification
 * printer.version = 6;
 * printer.alignment = FrameCPP::Debug::AlignmentMode::NONE;
 * printer.separator = " = ";
 * printer(vector);
 * 
 * // Version override for single call
 * printer(tocData, 8);  // Uses version 8, keeps other settings
 * ```
 *
 * \subsection debug_factory Factory Functions
 * ```cpp
 * // Pre-configured printers for common use cases
 * auto compact = FrameCPP::Debug::compactPrinter();
 * auto aligned = FrameCPP::Debug::alignedPrinter();
 * auto columnar = FrameCPP::Debug::columnarPrinter();
 * 
 * compact(tocData);   // Compact format: "field:value field2:value2"
 * aligned(tocData);   // Right-aligned names: "    field : value"
 * columnar(tocData);  // Tabular format: "field     : value        [type]"
 * ```
 *
 * \subsection debug_custom Custom Stream Output
 * ```cpp
 * std::ostringstream oss;
 * std::ofstream logfile("frame_debug.log");
 * 
 * FrameCPP::Debug::FramePrinter stringPrinter(oss);
 * FrameCPP::Debug::FramePrinter filePrinter(logfile);
 * 
 * stringPrinter(frameHeader);
 * std::string debugOutput = oss.str();  // Capture output as string
 * 
 * filePrinter(vector);  // Write directly to file
 * ```
 *
 * \section debug_alignment Alignment Modes
 *
 * \subsection debug_none NONE Mode (Compact)
 * Produces compact output with minimal spacing:
 * ```
 * name:"" compress:32768 type:0 nData:0 nBytes:0
 * ```
 *
 * \subsection debug_separator SEPARATOR Mode (Right-Aligned Names)
 * Right-justifies field names with aligned separators:
 * ```
 *      name : ""
 *  compress : 32768
 *      type : 0
 *     nData : 0
 *    nBytes : 0
 * ```
 *
 * \subsection debug_columns COLUMNS Mode (Tabular)
 * Left-justifies both names and values in separate columns:
 * ```
 * name     : ""                                    [std::string]
 * compress : 32768                                 [unsigned int]
 * type     : 0                                     [unsigned int]
 * nData    : 0                                     [unsigned long]
 * nBytes   : 0                                     [unsigned long]
 * ```
 *
 * \section debug_architecture Technical Architecture
 *
 * \subsection debug_archive DebugArchive Class
 * The core component is FrameCPP::Debug::DebugArchive, a custom boost::serialization
 * archive that:
 * 
 * \li Implements boost::archive::detail::common_oarchive interface
 * \li Extracts field names from boost::serialization::nvp objects
 * \li Performs two-pass processing for alignment calculations
 * \li Uses SFINAE to detect streamable vs non-streamable types
 * \li Provides automatic C++ type name demangling
 *
 * \subsection debug_printer FramePrinter Class
 * The high-level interface FrameCPP::Debug::FramePrinter provides:
 * 
 * \li Fluent interface with method chaining
 * \li Public attributes for direct configuration
 * \li Function call operators for easy usage
 * \li Automatic type name resolution
 * \li Integration with existing serialization methods
 *
 * \section debug_integration Integration with Frame Types
 *
 * The debug archiver automatically works with any Frame type that implements boost serialization.
 * It uses the same save() methods that are used for binary serialization, ensuring:
 *
 * \li **Consistency**: Debug output reflects actual serialized data
 * \li **Version Compatibility**: Supports all Frame specification versions
 * \li **Field Access**: Can access private/protected fields through serialization friendship
 * \li **No Code Changes**: Existing Frame classes work without modification
 *
 * \section debug_performance Performance Considerations
 *
 * \li **Two-Pass Processing**: SEPARATOR and COLUMNS modes require two serialization passes
 * \li **Type Detection**: SFINAE-based type detection happens at compile time
 * \li **Memory Efficient**: Uses string streams for formatting, minimal memory overhead
 * \li **Selective Output**: Type information and formatting can be disabled for faster output
 *
 * \section debug_examples Output Examples
 *
 * \subsection debug_frvect FrVect Debug Output
 * ```
 * FrameCPP::Universal::FrVect (Version 9):
 *     name                : ""                     [std::string]
 *     compress            : 32768                  [unsigned int]
 *     type                : 0                      [unsigned int]
 *     nData               : 0                      [unsigned long]
 *     nBytes              : 0                      [unsigned long]
 *     dimension           : [0 elements of type FrameCPP::Universal::DimensionImpl::Data] [std::vector]
 *     unitY               : ""                     [std::string]
 *     nDataValid          : 0                      [unsigned long]
 *     dataValidCompScheme : 32768                  [unsigned short]
 *     nDataValidCompBytes : 0                      [unsigned long]
 * ```
 *
 * \subsection debug_frameh FrameH Debug Output
 * ```
 * FrameCPP::Universal::FrameH (Version 9):
 *         name : ""                                [std::string]
 *          run : 1309761584                        [unsigned int]
 *        frame : 32764                             [unsigned int]
 *        GTime : 0.000000000                       [LDASTools::AL::GPSTime]
 *           dt : 6.91751e-310                      [double]
 *  dataQuality : 316527901                        [unsigned int]
 *      rawData : 0                                 [boost::shared_ptr<FrameCPP::Universal::FrRawData>]
 *         type : [0 elements of type FrameCPP::Universal::FrVect] [std::vector]
 *         user : [0 elements of type FrameCPP::Universal::FrVect] [std::vector]
 *    detectSim : [0 elements of type FrameCPP::Universal::FrDetector] [std::vector]
 *   detectProc : [0 elements of type FrameCPP::Universal::FrDetector] [std::vector]
 *      history : [0 elements of type FrameCPP::Universal::FrHistory] [std::vector]
 * ```
 *
 * \section debug_see_also See Also
 *
 * \li framecpp/OOInterface/FrameDebugPrint.hh - High-level debug printing interface
 * \li framecpp/archive/DebugArchive/DebugArchive.hh - Core custom serialization archive implementation
 * \li Frame serialization documentation for understanding the boost::serialization integration
 * \li Frame specification documentation for version-specific field information
 */

//-----------------------------------------------------------------------
