LMU/musrfit
5
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases 4 Activity

improve doxygen documentation of PFunction.* and PFunctionGrammar.h
All checks were successful
Build and Deploy Documentation / build-and-deploy (push) Successful in 18s
Details

Browse Source
This commit is contained in:
suter_a
2025-11-14 07:50:50 +01:00
parent f8a2d646dc
commit 40a797c0da
3 changed files with 463 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
src/include/PFunctionGrammar.h
View File

@@ -44,35 +44,91 @@
using namespace boost::spirit;
#endif
//--------------------------------------------------------------------------
/**
* \brief Iterator type for parsing characters.
*/
typedef char const* iterator_t;
//--------------------------------------------------------------------------
/**
* \brief Type for parse tree matching results.
*/
typedef tree_match<iterator_t> parse_tree_match_t;
//--------------------------------------------------------------------------
/**
* \brief Iterator type for traversing the parse tree.
*/
typedef parse_tree_match_t::tree_iterator iter_t;
//--------------------------------------------------------------------------
/**
* <p>EBNF like grammar definition of a function entry in the msr-file FUNCTION block.
* \brief EBNF-like grammar definition for parsing function entries in msr-file FUNCTION blocks.
*
* This grammar defines the syntax for parsing mathematical function expressions in msr-files.
* It supports:
* - Basic arithmetic operations (+, -, *, /)
* - Mathematical functions (trigonometric, hyperbolic, logarithmic, exponential, etc.)
* - Constants (PI, GAMMA_MU, field B, energy EN, temperature T)
* - Parameters (PAR) and maps (MAP)
* - Function references (FUN)
*
* The grammar follows an EBNF-like structure with the following hierarchy:
* \verbatim
* assignment = fun_label '=' expression
* expression = term { ('+' | '-') term }
* term = factor { ('*' | '/') factor }
* factor = real | constant | parameter | map | function | power | '(' expression ')'
* \endverbatim
*
* \see PFunction for the class that uses this grammar to evaluate parsed expressions
*/
struct PFunctionGrammar : public grammar<PFunctionGrammar>
{
static const int realID = 1;
static const int constPiID = 2;
static const int constGammaMuID = 3;
static const int constFieldID = 4;
static const int constEnergyID = 5;
static const int constTempID = 6;
static const int funLabelID = 7;
static const int parameterID = 8;
static const int mapID = 9;
static const int functionID = 10;
static const int powerID = 11;
static const int factorID = 12;
static const int termID = 13;
static const int expressionID = 14;
static const int assignmentID = 15;
static const int realID = 1; ///< Identifier for real number literals
static const int constPiID = 2; ///< Identifier for PI constant
static const int constGammaMuID = 3; ///< Identifier for GAMMA_MU constant (muon gyromagnetic ratio)
static const int constFieldID = 4; ///< Identifier for magnetic field constant (B or -B)
static const int constEnergyID = 5; ///< Identifier for energy constant (EN or -EN)
static const int constTempID = 6; ///< Identifier for temperature constant (T# or -T#)
static const int funLabelID = 7; ///< Identifier for function label (FUN#)
static const int parameterID = 8; ///< Identifier for parameter reference (PAR# or -PAR#)
static const int mapID = 9; ///< Identifier for map reference (MAP#)
static const int functionID = 10; ///< Identifier for mathematical functions (cos, sin, exp, etc.)
static const int powerID = 11; ///< Identifier for power function (POW)
static const int factorID = 12; ///< Identifier for factor in expression
static const int termID = 13; ///< Identifier for term in expression
static const int expressionID = 14; ///< Identifier for expression
static const int assignmentID = 15; ///< Identifier for assignment statement
//------------------------------------------------------------------------
/**
* \brief Inner template structure defining the grammar rules.
*
* This template structure contains the actual grammar rule definitions
* using Boost.Spirit syntax. It defines how the parser should recognize
* and build an abstract syntax tree (AST) for function expressions.
*
* \tparam ScannerT Scanner type used by Boost.Spirit for parsing
*/
template <typename ScannerT>
struct definition
{
//--------------------------------------------------------------------
/**
* \brief Constructor that defines all grammar rules.
*
* Sets up the complete grammar hierarchy for parsing function expressions:
* - Terminals: real numbers, constants (PI, GAMMA_MU, B, EN, T), parameters (PAR), maps (MAP)
* - Functions: trigonometric (cos, sin, tan), hyperbolic (cosh, sinh, tanh),
* inverse trigonometric (acos, asin, atan), inverse hyperbolic (acosh, asinh, atanh),
* logarithmic (log, ln), exponential (exp), square root (sqrt), power (pow)
* - Operators: addition (+), subtraction (-), multiplication (*), division (/)
* - Expressions: Hierarchical structure following operator precedence
*
* \param self Reference to the enclosing PFunctionGrammar (unused but required by Boost.Spirit)
*/
definition(PFunctionGrammar const& /*self*/)
{
// Start grammar definition
@@ -163,22 +219,31 @@ struct PFunctionGrammar : public grammar<PFunctionGrammar>
BOOST_SPIRIT_DEBUG_RULE(assignment);
}
rule<ScannerT, parser_context<>, parser_tag<assignmentID> > assignment;
rule<ScannerT, parser_context<>, parser_tag<expressionID> > expression;
rule<ScannerT, parser_context<>, parser_tag<termID> > term;
rule<ScannerT, parser_context<>, parser_tag<factorID> > factor;
rule<ScannerT, parser_context<>, parser_tag<functionID> > function;
rule<ScannerT, parser_context<>, parser_tag<powerID> > power;
rule<ScannerT, parser_context<>, parser_tag<mapID> > map;
rule<ScannerT, parser_context<>, parser_tag<parameterID> > parameter;
rule<ScannerT, parser_context<>, parser_tag<funLabelID> > fun_label;
rule<ScannerT, parser_context<>, parser_tag<constTempID> > const_temp;
rule<ScannerT, parser_context<>, parser_tag<constEnergyID> > const_energy;
rule<ScannerT, parser_context<>, parser_tag<constFieldID> > const_field;
rule<ScannerT, parser_context<>, parser_tag<constGammaMuID> > const_gamma_mu;
rule<ScannerT, parser_context<>, parser_tag<constPiID> > const_pi;
rule<ScannerT, parser_context<>, parser_tag<realID> > real;
rule<ScannerT, parser_context<>, parser_tag<assignmentID> > assignment; ///< Rule for assignment: FUN# = expression
rule<ScannerT, parser_context<>, parser_tag<expressionID> > expression; ///< Rule for expression: term { ('+' | '-') term }
rule<ScannerT, parser_context<>, parser_tag<termID> > term; ///< Rule for term: factor { ('*' | '/') factor }
rule<ScannerT, parser_context<>, parser_tag<factorID> > factor; ///< Rule for factor: operand or parenthesized expression
rule<ScannerT, parser_context<>, parser_tag<functionID> > function; ///< Rule for mathematical functions
rule<ScannerT, parser_context<>, parser_tag<powerID> > power; ///< Rule for power function POW(base, exponent)
rule<ScannerT, parser_context<>, parser_tag<mapID> > map; ///< Rule for map reference MAP#
rule<ScannerT, parser_context<>, parser_tag<parameterID> > parameter; ///< Rule for parameter reference PAR# or -PAR#
rule<ScannerT, parser_context<>, parser_tag<funLabelID> > fun_label; ///< Rule for function label FUN#
rule<ScannerT, parser_context<>, parser_tag<constTempID> > const_temp; ///< Rule for temperature constant T# or -T#
rule<ScannerT, parser_context<>, parser_tag<constEnergyID> > const_energy; ///< Rule for energy constant EN or -EN
rule<ScannerT, parser_context<>, parser_tag<constFieldID> > const_field; ///< Rule for field constant B or -B
rule<ScannerT, parser_context<>, parser_tag<constGammaMuID> > const_gamma_mu;///< Rule for muon gyromagnetic ratio constant
rule<ScannerT, parser_context<>, parser_tag<constPiID> > const_pi; ///< Rule for PI constant
rule<ScannerT, parser_context<>, parser_tag<realID> > real; ///< Rule for real number literals
//--------------------------------------------------------------------
/**
* \brief Returns the starting rule for the grammar.
*
* The parser begins by matching the assignment rule, which represents
* a complete function definition (e.g., FUN1 = PAR1 * cos(PAR2 * PI)).
*
* \return Reference to the assignment rule as the grammar entry point
*/
rule<ScannerT, parser_context<>, parser_tag<assignmentID> > const&
start() const { return assignment; }
};