compiler.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 #"mainpage_license".
//==================================================================================================
 
ALIB_EXPORT namespace alib {  namespace expressions {
 
// forwards
namespace detail { struct Parser; }
struct  CompilerPlugin;
 
//==================================================================================================
/// An implementation of this abstract interface class may be attached to field
/// #"Compiler::Repository;*" to enable an \e automated definition and retrieval
/// of expression strings of nested expressions.
///
/// A default implementation, which uses typical \alib mechanics to define expression
/// strings, is given with class #"StandardRepository".
///
/// More information about automated nested expressions and the use of this interface class is
/// provided with manual chapter #"alib_expressions_nested_config".
//==================================================================================================
class ExpressionRepository
{
  public:
    /// Virtual destructor.
    virtual ~ExpressionRepository()                                                               {}
 
    /// This method is called during compilation of expressions in the case a named expression
    /// is not found by method #"Compiler::GetNamed;*".
    ///
    /// @param      identifier  The name of the required expression.
    /// @param[out] target      The target to write the requested expression string to.
    /// @return \c true, if the expression string could be retrieved, \c false otherwise.
    ///         If \c true is returned and \p{target} is still empty, then the string is defined
    ///         to be empty, which throws an exception on compilation.
    virtual bool        Get( const String& identifier, AString& target )                         =0;
};
 
//==================================================================================================
/// This is a central class of library module \alib_expressions_nl used to compile
/// expression strings.
///
/// For information about general use and features of this class consult the
/// #"alib::expressions;ALib Expressions User Manual".
///
/// ## Friends ##
/// class #"ExpressionVal"
//==================================================================================================
class Compiler  : public lang::PluginContainer<CompilerPlugin, CompilePriorities>
{
    #if !DOXYGEN
        friend class  ExpressionVal;
        friend struct detail::Parser;
        friend class  detail::ProgramBase;
    #endif
 
  public:
       /// Alias shortcut to the type of the plug-in vector inherited from \b %PluginContainer.
       using Plugins= std::vector<lang::PluginContainer<CompilerPlugin, CompilePriorities>::Slot>;
 
  //################################################################################################
  // internal fields
  //################################################################################################
  protected:
    /// Memory for used for permanent allocations during the set-up phase.
    /// Later it is also used for temporary allocations during compilation and reset to its
    /// state after setup.
    MonoAllocator                       allocator;
 
    /// The expression parser.
    detail::Parser*                     parser                                             =nullptr;
 
    /// The map of Type names and bit flag values.
    HashMap< MonoAllocator,
             lang::TypeFunctors::Key, NAString,
             lang::TypeFunctors::Hash,
             lang::TypeFunctors::EqualTo  >   typeMap;
 
    /// The map of 'named' expressions.
    HashMap< MonoAllocator,
             AString, Expression,
             std::hash    <String>,
             std::equal_to<String>  >   namedExpressions;
 
 
  //################################################################################################
  // Public fields
  //################################################################################################
  public:
 
    /// The list of unary operators.
    /// To define a new unary operator, method #"AddUnaryOperator" should be used.
    /// In debug-builds, the methods asserts that no double insertions are performed.
    ///
    /// Custom insertions may be performed before or after invoking #"SetupDefaults",
    /// but before a first expression is compiled.
    ///
    ///
    /// Flag #"Compilation::DefaultUnaryOperators;*" controls if method
    /// \b %SetupDefaults adds operators resourced with enumeration
    /// #"expressions::DefaultUnaryOperators".
    ListMA<String>         UnaryOperators;
 
    /// This public map allows defining alias names for unary operators. Such names
    /// must consist only of alphabetic characters.
    ///
    /// Flag #"Compilation::DefaultAlphabeticOperatorAliases;*" controls if method
    /// #"SetupDefaults" adds the aliases defined with resourced data records of enumeration
    /// #"DefaultAlphabeticUnaryOperatorAliases" to this map.
    HashMap<MonoAllocator,
            String, String,
            alib::hash_string_ignore_case<character>,
            alib::equal_to_string_ignore_case<character> > AlphabeticUnaryOperatorAliases;
 
    /// This public map allows defining alias names for binary operators. Such names
    /// must consist only of alphabetic characters.
    ///
    /// Flag #"Compilation::DefaultAlphabeticOperatorAliases;*" controls if method
    /// #"SetupDefaults" adds the aliases defined with resourced data records of enumeration
    /// #"DefaultAlphabeticBinaryOperatorAliases" to this map.
    HashMap<MonoAllocator, String, String,
            alib::hash_string_ignore_case<character>,
            alib::equal_to_string_ignore_case<character> > AlphabeticBinaryOperatorAliases;
 
    /// Adds an unary operator to this expression compiler.
    /// This method should be invoked before invoking #"SetupDefaults".
    ///
    /// Operator symbols must be added only once.
    ///
    /// @param symbol The operator symbol.
    void AddUnaryOperator( const String& symbol  ) {
        #if ALIB_DEBUG
            for( auto& op : UnaryOperators )
                if( op.Equals<NC>( symbol ) )
                    ALIB_ASSERT_ERROR( false, "EXPR", "Unary operator '{}' already defined.",
                                                      symbol )
        #endif
        UnaryOperators.emplace_back(symbol);
    }
 
 
    /// The list of binary operators. The map stores the precedences.
    ///
    /// To define a new binary operator, entry may be added before invoking #"SetupDefaults"
    /// using method #"AddBinaryOperator".
    ///
    /// Flag #"Compilation::DefaultUnaryOperators;*" controls if method
    /// \b %SetupDefaults adds operators resourced with enumeration
    /// #"expressions::DefaultBinaryOperators".
    HashMap<MonoAllocator, String, int>  BinaryOperators;
 
    /// Adds a binary operator to this expression compiler.
    /// This method should be invoked before invoking #"SetupDefaults".
    ///
    /// Operator symbols must be added only once.
    ///
    /// @param symbol        The operator symbol.
    /// @param precedence    The precedence of the operator.
    void AddBinaryOperator( const String& symbol, int precedence ) {
        ALIB_DBG( auto result= )
        BinaryOperators.EmplaceOrAssign(symbol, precedence);
        ALIB_ASSERT_ERROR( result.second == true, "EXPR", // was inserted
                           "Binary operator '{}' already defined.", symbol )
    }
 
    /// Returns the precedence of given operator \b symbol.
    ///
    /// @param symbol        The operator symbol.
    /// @return The precedence of the operator as defined with #"AddBinaryOperator".
    int GetBinaryOperatorPrecedence( const String& symbol ) {
        // search in operator table first
        auto it= BinaryOperators.Find( symbol );
        if( it != BinaryOperators.end() )
            return it.Mapped();
 
        // have an alias?
        auto aliasOp= AlphabeticBinaryOperatorAliases.Find( symbol );
        ALIB_ASSERT_ERROR( aliasOp != AlphabeticBinaryOperatorAliases.end(), "EXPR",
                           "Unknown binary operator '{}'.", symbol       )
 
        it= BinaryOperators.Find( aliasOp.Mapped() );
        ALIB_ASSERT_ERROR( it != BinaryOperators.end(), "EXPR",
                           "Unknown binary operator '{}' which was aliased by '{}'.",
                           aliasOp->second, symbol       )
        return it.Mapped();
    }
 
 
        /// #"BitwiseTraits;Bitwise enum class" that lists the plug-ins built-into
        /// \alib expression library. This bitfield is used with method #"SetupDefaults", which
        /// reads the flags set in #CfgBuiltInPlugins and installs the plug-ins accordingly.
        enum class BuiltInPlugins
        {
            NONE               =  0,         ///< Installs no plug-in.
            ALL                = -1,         ///< Installs all plug-ins.
            ElvisOperator      = (1 << 1),   ///< Installs #"plugins::ElvisOperator;*".
            AutoCast           = (1 << 2),   ///< Installs #"plugins::AutoCast;*".
            Arithmetics        = (1 << 3),   ///< Installs #"plugins::Arithmetics;*".
            Math               = (1 << 4),   ///< Installs #"plugins::Math;*".
            Strings            = (1 << 5),   ///< Installs #"plugins::Strings;*".
    #if ALIB_CAMP
            DateAndTime        = (1 << 6),   ///< Installs #"plugins::DateAndTime;*". )
    #endif
        };
 
 
    /// Bitfield that defines the built-in compiler plug-ins that are created and inserted
    /// by method #SetupDefaults.
    ///
    /// Defaults to #"BuiltInPlugins::ALL"
    ///
    /// \note
    ///   The built-in plug-ins are allowed to be shared by different compiler instances.
    ///   To reach that, they must not be disabled here (or method #SetupDefaults must be
    ///   omitted) and instead created once and registered with the compiler using the
    ///   inherited method #"InsertPlugin". In that case, the value
    ///   \c "Responsibility::KeepWithSender" has to be provided as parameter \p{responsibility}.
    BuiltInPlugins              CfgBuiltInPlugins                              =BuiltInPlugins::ALL;
 
    /// The operator defined in this public field is used to address nested expressions.
    /// The operator used can be customized to any defined (!) unary operator.
    ///
    /// To disable nested expression parsing, change to empty or \e nulled string.
    ///
    /// \note
    ///   If changed, the change hast to be made \b before invoking #SetupDefaults. Otherwise,
    ///   the default configuration for
    ///   #"alib_expressions_operators_verbal;verbal operator aliases" would be set in
    ///   effect to a wrong (or disabled) target operator.
    ///
    /// Defaults to \c "*".
    ///
    /// \see Manual chapter #"alib_expressions_nested".
    ///
    String                      CfgNestedExpressionOperator                            =A_CHAR("*");
 
    /// Name descriptor for nested expression function.
    /// Defaults to "Expression" with a minimum abbreviation of \c 4 characters, ignoring letter
    /// case.<br>
    /// Resourced with the key \c "EF"
    ///
    /// \see Manual chapter #"alib_expressions_nested".
    strings::util::Token        CfgNestedExpressionFunction;
 
    /// Keyword used with optional third parameter of expression function.
    /// Defaults to \c "throw". Resourced with key \c "EF"
    ///
    /// \see Manual chapter #"alib_expressions_nested".
    String                      CfgNestedExpressionThrowIdentifier;
 
    /// Compilation flags.
    Compilation                 CfgCompilation                                =Compilation::DEFAULT;
 
    /// Flags that allow to tweak the result of the normalization of the originally parsed
    /// expression string.
    Normalization               CfgNormalization                            =Normalization::DEFAULT;
 
    /// This list is used with the normalization of the expression string. It contains
    /// strings, which are not allowed to appear in normalized expression strings.
    ///
    /// In the current library version, such strings might occur only if flags
    /// #"Normalization::UnaryOpSpace;*",
    /// #"Normalization::UnaryOpSpaceIfUnaryFollows;*" or
    /// #"Normalization::BinaryOpSpaces;*" are not set.
    /// As a sample see expression:
    ///
    ///          1 - -2
    ///
    /// If no space is written after binary operators, this expression would be normalized
    /// to:
    ///          1--2
    ///
    /// While this just looks irritating to a homo sapiens, it would be even illegal if
    /// well known C++ operator <c>--</c> was supported. Therefore, string <c>"--"</c> is added
    /// to this map in method #SetupDefaults, which forces the normalization logic to insert
    /// a space, even if spaces are otherwise configured to be omitted.
    StringVectorMA              CfgNormalizationDisallowed;
 
    /// Formatter used throughout all phases of the life-cycle of an expression:
    /// - Used for parsing expression strings (Using the encapsulated
    ///   #"TNumberFormat;NumberFormat" object. This is also the reason, why the type
    ///   of formatter is \b %Formatter and not its more abstract base \b %Formatter.)
    /// - Used for the generation of the normalized expression strings.
    /// - Used for the generation of constant string objects during compilation.
    /// - Used for the generation of string objects during evaluation.
    ///
    /// For the latter two, a copy of the pointer is provided through field
    /// #"Scope::Formatter".
    /// It is important not to change the formatting parameters in between the creation of the
    /// compile-time scope and the creation of the evaluation-time scope. If done,
    /// the expression results could differ when optimizations during compilation are performed.
    ///
    /// In the constructor of this class, a #"Formatter::Clone;clone" of the
    /// \alib {format::Formatter;Default;default formatter} is copied here.
    SPFormatter                 CfgFormatter;
 
    /// Optional pointer to a default or custom implementation of a repository that provides
    /// expression strings for named nested expressions.
    ///
    /// \see Manual chapter #"alib_expressions_nested_config".
    ExpressionRepository*       Repository                                                 =nullptr;
 
  //################################################################################################
  // Public Interface
  //################################################################################################
  public:
    /// Constructor. Construction usually is three steps:
    /// 1. Create class instance
    /// 2. Set the various configuration options (fields prefixed <c>Cfg</c>).
    /// 3. Invoke #SetupDefaults.
    ALIB_DLL        Compiler();
 
    /// Destructor
    ALIB_DLL
    virtual         ~Compiler();
 
    /// Registers a (custom) type name with this compiler. The name will be used to
    /// display a type name to end-users, for example, when malformed expressions throw an
    /// exception.
    ///
    /// The built-in types get registered in the constructor of the compiler, where the
    /// type names are read from the #"ResourcePool" of static library object
    /// #"EXPRESSIONS".
    ///
    /// It is recommended that custom plug-ins invoke this method in their constructor.
    ///
    /// \note
    ///   There is no general need to register types for using them
    ///   with \alib_expressions_nl. Parameter  \p{name} of this method is exclusively
    ///   used to generate textual, human-readable output!
    ///
    /// @param sample    A #"alib_expressions_prereq_sb;sample value"
    ///                  of the type, which is implicitly boxed when passed.
    /// @param name      The name of the type.
    ALIB_DLL
    void            AddType(Type sample, const NString& name);
 
    /// Returns the name of the type of the boxed value.
    /// Note that custom types need to be registered with method #AddType.
    ///
    /// If given argument \p{box} is #"alib_boxing_more_void_void;a void box", the returned
    /// string is <b>"NONE"</b>.
    ///
    /// @param box  The box to receive the type name for.
    /// @return The type name as string.
    ALIB_DLL
    NString         TypeName(Type box);
 
    /// Writes the signature of a function (as, for example, found in
    /// #"Calculus::FunctionEntry") to a string buffer.
    ///
    /// @param boxArray  The start of the array of pointers.
    /// @param qty       The array's length.
    /// @param target    The string to write into.
    ALIB_DLL
    void             WriteFunctionSignature( Box** boxArray,  size_t qty,  AString& target );
 
    /// Writes the signature of an argument list to a string buffer.
    ///
    /// @param begin     Iterator to the first argument.
    /// @param end       End-iterator.
    /// @param target    The string to write into.
    ALIB_DLL
    void             WriteFunctionSignature( ArgIterator     begin,
                                             ArgIterator     end,
                                             AString&        target   );
 
    /// Completes construction according to configuration options provided with fields
    /// prefixed <c>Cfg</c>.
    /// In detail, the following actions are performed:
    /// - If flag #"Compilation::DefaultUnaryOperators;*" is set in field
    ///   #CfgCompilation, then
    ///   - the unary operators listed in the #"alib_enums_records;enum records" of
    ///     #"expressions::DefaultUnaryOperators" are added using #AddUnaryOperator.
    ///   - If flag #"Compilation::DefaultAlphabeticOperatorAliases;*" is set in
    ///     field #CfgCompilation, then the alphabetic alias names found in
    ///     the data records of enumeration
    ///     #"DefaultAlphabeticUnaryOperatorAliases"
    ///     are set in field #AlphabeticUnaryOperatorAliases. (As of the current version this
    ///     is only the token \b NOT aliasing operator <b>"!"</b>.
    /// - If flag #"Compilation::DefaultBinaryOperators;*" is set in field
    ///   #CfgCompilation, then
    ///   - the binary operators listed in the data records of enumeration
    ///     #"expressions::DefaultBinaryOperators" are added using #AddBinaryOperator.
    ///   - If flag #"Compilation::AllowSubscriptOperator;*" is not set, the
    ///     subscript operator is omitted.
    ///   - If flag #"Compilation::DefaultAlphabeticOperatorAliases;*" is set in
    ///     field #CfgCompilation, then the alphabetic alias names found in
    ///     the data records of enumeration
    ///     #"DefaultAlphabeticBinaryOperatorAliases"
    ///     are set in field #AlphabeticBinaryOperatorAliases. (As of the current version this
    ///     is only the token \b NOT aliasing operator <b>"!"</b>.
    /// - Strings <b>"++"</b> and <b>"--"</b> are added to field #CfgNormalizationDisallowed
    ///   to prevent the unintentional creation of these potential operators in normalizations.
    ///   (This way, a space character will be added between binary <b>"+"</b> and unary
    ///    <b>"+"</b>, respectively binary <b>"-"</b> and unary <b>"-"</b> operators,
    ///   even if the normalization options do not suggest to do this.
    /// - Depending on the flags set in #CfgBuiltInPlugins, the plug-ins listed in
    ///   enumeration #BuiltInPlugins are created and added.
    ALIB_DLL
    void            SetupDefaults();
 
    /// Firstly, this method parses the given expression string thereby builds an intermediate
    /// internal #"detail::AST;abstract syntax tree".
    /// This tree is then translated into a #"detail::Program;*" which evaluates
    /// the expression in respect to a #"expressions::Scope" when executed.
    ///
    /// For building the program, attached #"CompilerPlugin" instances
    /// are queried.
    ///
    /// During this process, a #"Normalization;normalized" version of the input
    /// string is always created. While the original input string can
    /// be accessed with #"ExpressionVal::GetOriginalString;*", the normalized
    /// version can be retrieved after the compilation with method
    /// #"ExpressionVal::GetNormalizedString;*". During compilation, the
    /// normalization rules (flags) stored in field #CfgNormalization are applied.
    ///
    /// For compilation, a compile-time scope object is created by calling the virtual method
    /// #createCompileTimeScope. If not overwritten, a standard scope object is used.
    /// If custom callbacks exists that are invokable at compile-time
    /// (to perform program optimization) and that at the same time rely on custom mechanics
    /// provided with a custom scope class, then a custom, derived version of this class
    /// has to be used that overrides method #createCompileTimeScope accordingly.
    ///
    /// @param expressionString  The string to parse.
    /// @return A shared pointer to the compiled expression. Contains \c nullptr on failure.
    virtual ALIB_DLL
    Expression      Compile( const String& expressionString );
 
    /// Compiles the given \p{expressionString} and adds a compiled expression to the map of
    /// named expressions.
    ///
    /// @param name              The name used to map the expression.
    /// @param expressionString  The string to parse.
    ///                          If nulled, entry \p{name} is removed (if existing).
    /// @return \c true if an expression with the same named existed and was replaced.
    ///         Otherwise, returns \c false.
    virtual ALIB_DLL
    bool            AddNamed( const String& name, const String& expressionString );
 
    /// Removes a named expression. This is just a shortcut to #AddNamed, providing
    /// a nulled string for parameter \p{expressionString}.
    ///
    /// @param name  The name of the expression to be removed.
    /// @return \c true if an expression with the given name existed and was removed.
    ///         Otherwise, returns \c false.
    bool            RemoveNamed( const String& name )      { return AddNamed( name, NULL_STRING ); }
 
    /// Returns a named expression previously defined using #AddNamed.
    /// In the case that no expression with the given \p{name} was defined and optional interface
    /// #Repository is set, then this interface is used to retrieve a corresponding expression
    /// string and compile the named expression 'on the fly'.
    ///
    /// \see
    ///   Manual chapter #"alib_expressions_nested_config".
    ///
    /// @param name  The name of the expression.
    /// @return In case of success a shared pointer to the expression.
    virtual ALIB_DLL
    Expression      GetNamed( const String& name );
 
    /// Provides access to the internal #"MonoAllocator".
    /// \note This method is deemed non-standard use of this class, and the using code needs to
    ///       knowing what to do.
    /// @return The internal monotonous allocator.
    MonoAllocator&  GetAllocator()                                             { return allocator; }
    
  //################################################################################################
  // Protected Interface
  //################################################################################################
  protected:
    /// This virtual method is called by #Compile to create the scope object used
    /// for allocations that are made for intermediate results at compile-time.
    ///
    /// Compile-time allocations occur when expression terms that use purely constant arguments
    /// are evaluated at compile-time. Such optimization consequently leads to the invocation
    /// of callback functions at compile-time.
    ///
    /// If now, custom callback functions rely on custom allocation mechanics, provided with
    /// custom scope types, then this method has to be overridden to return such a custom
    /// scope object.
    ///
    /// @param expressionAllocator The allocator of the expression used to allocate the
    ///                            compile-time scope.
    /// @return The default implementation returns the standard scope object.
    ///         For its construction, the field #CfgFormatter is provided.<br>
    ///         Derived compilers may need to return a scope object of a derived type.
    virtual  ALIB_DLL
    Scope*          createCompileTimeScope(MonoAllocator& expressionAllocator);
 
    /// Implements #"ExpressionVal::GetOptimizedString;*".
    ///
    /// @param expression the expression to generate an optimized string for.
    ALIB_DLL
    void            getOptimizedExpressionString( ExpressionVal& expression );
};
 
 
 
namespace detail {
/// Base class exported by the main module #"F;ALib.Expressions.H" for technical reasons.
class  ProgramBase {
  protected:
    /// Friendship-access method used by derived implementation.
    /// @param ev The expression to receive protected data from.
    /// @return The expression's allocotor.
    MonoAllocator&          getExpressionAllocator(ExpressionVal& ev)       { return ev.allocator; }
 
    /// Friendship-access method used by derived implementation.
    /// @param ev The expression to receive protected data from.
    /// @return The expression's compile-time scope.
    Scope*                  getExpressionCTScope  (ExpressionVal& ev)         { return ev.ctScope; }
 
    /// Friendship-access method used by derived implementation.
    /// @param cmp The compiler to receive protected data from.
    /// @return The compiler's plugins.
    Compiler::PluginList&   getCompilerPlugins    (Compiler& cmp)            { return cmp.plugins; }
};
 
/// Base class exported by the main module #"F;ALib.Expressions.H" for technical reasons.
struct VirtualMachineBase {
  protected:
    /// Friendship-access method used by derived implementation.
    /// @param ev The expression to receive protected data from.
    /// @return The expression's compile-time scope.
    static Scope*           getExpressionCTScope  (ExpressionVal& ev)         { return ev.ctScope; }
};
 
 
}
 
} // namespace alib[::expressions]
 
DOX_MARKER([DOX_MANUAL_ALIASES_COMPILER])
/// Type alias in namespace \b alib.
using     Compiler=           expressions::Compiler;
 
} // namespace [alib]
DOX_MARKER([DOX_MANUAL_ALIASES_COMPILER])
 
ALIB_ENUMS_MAKE_BITWISE(alib::expressions::Compiler::BuiltInPlugins)