parser_impl.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_expressions of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
ALIB_EXPORT namespace alib {  namespace expressions { namespace detail {
 
//==================================================================================================
/// Implementation of the default parser of module \alib_expressions_nl.
///
/// This internal class is not too well documented. Nevertheless, it is designed to be able
/// to tweak its behavior slightly and in case of need, even derive and use a custom parser
/// class. For doing so, please consult the source code of this class.
/// A custom parser might be set to protected field \alib{expressions;Compiler::parser}by a derived
/// compiler type before compiling a first expression.
///
/// It is possible to define scannable custom unary and binary operators. Definitions of binary
/// operators include a "precedence value" that allows aligning them with the built-in types.
/// Also, built-in operators can be \em removed if wanted.
//==================================================================================================
class ParserImpl  : public Parser
{
    protected:
        /// Types of tokens.
        enum class Tokens : char
        {
            EOT             = '\0', ///< End of tokens. (No next token available.)
            SymbolicOp      = 'O' , ///< A symbolic operator. Can be unary or binary.
            AlphaUnOp       = 'U' , ///< An alphabetic unary operator.
            AlphaBinOp      = 'B' , ///< An alphabetic binary operator.
 
            LitString       = 'S' , ///< a string literal.
            LitInteger      = 'I' , ///< a integer literal.
            LitFloat        = 'F' , ///< a float literal.
 
            Identifier      = 'A' , ///< An identifier.
 
            BraceOpen       = '(' , ///< An opening brace.
            BraceClose      = ')' , ///< A closing brace.
            Comma           = ',' , ///< A comma.
                                    
            SubscriptOpen   = '[' , ///< An opening subscript brace.
            SubscriptClose  = ']' , ///< A closing subscript brace.
        };
 
        /// Memory for temporary allocations, like AST objects or literal strings with converted
        /// escape sequences. Provided by the compiler with the method #Parse.
        MonoAllocator&              compileTimeAllocator;
 
        /// The actual token type.
        Tokens                      token;
 
        /// The actual token type.
        ASTLiteral::NFHint          tokLiteralHint;
 
        /// Integer value of token (if applicable).
        integer                     tokInteger;
 
        /// Float value of token (if applicable).
        double                      tokFloat;
 
        /// String value of token (if applicable).
        String                      tokString;
 
        /// The position of the token in #expression.
        integer                     tokPosition;
 
        /// The compiler that this parser works for.
        Compiler&                   compiler;
 
        /// Used for scanning literals. Provided to this class with each parse request.
        NumberFormat*               numberFormat;
 
 
        /// The given expression to parse.
        String                      expression;
 
        /// The rest of #expression.
        Substring                   scanner;
 
        /// Lists single characters that get directly converted into tokens of corresponding type
        /// when found in the expression string. Tokens are <c>"()[],"</c>.
        BitSet<256>                 syntaxTokens;
 
        /// Lists single characters that got found in operator strings which have been registered
        /// with
        /// \alib{expressions;Compiler::AddUnaryOperator} and
        /// \alib{expressions;Compiler::AddBinaryOperator}.
        ///
        /// Used by the internal token scanner (lexer) and by default will become something like
        /// <c>"=+-*%/?:~!|&^!<>/%"</c>.
        /// when found in the expression string.
        BitSet<256>                 operatorChars;
 
        /// Hash set of unary operators. The key of the table is the operator string, which usually
        /// consists of one character, like <c>'-'</c> or <c>'!'</c>.
        ///
        /// This table is filled in the constructor of the class with the values stored in
        /// \alib{expressions;Compiler::UnaryOperators} and used for testing of existence.
        HashSet< MonoAllocator,
                 String,
                 alib::hash_string_ignore_case    <character>,
                 alib::equal_to_string_ignore_case<character>  >  unaryOperators;
 
        /// Hash set of binary operators. The key of the table is the operator string, which usually
        /// consists of one to three characters, like <c>'+'</c> or <c>'<<='</c>.
        ///
        /// This table is filled in the constructor of the class with the values stored in
        /// \alib{expressions;Compiler::BinaryOperators} and used for testing of existence.
        HashSet< MonoAllocator,
                 String,
                 alib::hash_string_ignore_case    <character>,
                 alib::equal_to_string_ignore_case<character>  >  binaryOperators;
 
        /// List of ASTs currently created in recursion.
        /// \note
        ///   This vector is created in the monotonic allocator and never even deleted, as all
        ///   inserted \b AST elements, exclusively allocate from the same temporary allocator.
        StdVectorMono<AST*>*                                      ASTs;
 
    // #############################################################################################
    // Constructor/destructor, interface
    // #############################################################################################
    public:
        /// Constructor.
        /// @param compiler   The compiler that this parser works for.
        /// @param allocator  A monotonic allocator for permanent allocations.
        ParserImpl( Compiler& compiler, MonoAllocator& allocator );
 
        /// Virtual destructor.
        virtual    ~ParserImpl()                                                            override
        {}
 
        /// Parses the given expression string.
        /// \note
        ///   The return value is hidden by using <c>void*</c>. This is to allow avoid flooding
        ///   of \c boost header includes files to the code entities using module \alib_expressions_nl.
        ///
        /// @param exprString The string to parse.
        /// @param nf         Used to scan number literals.
        /// @return  The abstract syntax tree representing the expression.
        ALIB_DLL virtual
        detail::AST* Parse( const String&   exprString, NumberFormat* nf )                 override;
 
 
    protected:
    // #############################################################################################
    // Lexer
    // #############################################################################################
        /// This is the "scanner" or "lexer" method.
        void        NextToken();
 
 
    // #############################################################################################
    // Parser
    // #############################################################################################
 
        /// Tests if the actual token represents a known unary operator.
        /// @return  Returns the binary operator symbol, respectively a \e nulled string on failure.
        ALIB_DLL
        String      getUnaryOp();
 
        /// Tests if the actual token represents a known binary operator.
        /// @return  Returns the binary operator symbol, respectively a \e nulled string on failure.
        ALIB_DLL
        String      getBinaryOp();
 
        /// Internal method that optionally parses a conditional operator (<c>Q ? T : F</c> )
        ///
        /// @return  T.
        AST*        parseConditional();
 
        /// Internal method that optionally parses a binary operator and levels (recursively)
        /// trees of such according to operator precedence and brackets given.
        /// @return  T.
        AST*        parseBinary();
 
        /// Parses unary ops, literals, identifiers, functions and expressions surrounded by
        /// brackets.
        /// @return  The abstract syntax tree node parsed.
        AST*        parseSimple();
 
        /// Invoked after an identifier or function was parsed. Tests for subscript
        /// operator, otherwise returns the given ast as is.
        /// @param  function The identifier or function parsed.
        /// @return  Either the given node or a node of type \alib{expressions::detail;ASTBinaryOp}
        ///          with \c lhs set to \p{function}, \c rhs to the parsed subscript arg and
        ///          and operator set to <c>'[]'</c>.
        AST*        parseSubscript( AST* function );
 
 
 
        /// Simple shortcut popping and returning last ast from the current list.
        /// @return Popped AST object.
        AST* pop()
        {
            AST* ast= ASTs->back();
            ASTs->pop_back();
            return ast;
        }
 
        /// Simple shortcut pushing an ast to current list and returning it.
        /// @param  ast The AST node to push.
        /// @return Popped AST object.
        AST* push( AST* ast )
        {
            ASTs->emplace_back(ast);
            return ast;
        }
 
        /// Simple shortcut to the topmost AST.
        /// @return The topmost AST object.
        AST* top()
        {
            return ASTs->back();
        }
 
        /// Simple shortcut replacing the topmost ast.
        /// @param  ast The new AST node to replace the existing one with.
        /// @return The given object.
        AST* replace( AST* ast )
        {
            ASTs->back()= ast;
            return ast;
        }
};  // class ParserImpl
 
 
}}} // namespace [alib::expressions::detail]