messageformat2.h

Go to the documentation of this file.

// © 2024 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
 
#include "unicode/utypes.h"
 
#ifndef MESSAGEFORMAT2_H
#define MESSAGEFORMAT2_H
 
#if U_SHOW_CPLUSPLUS_API
 
#if !UCONFIG_NO_FORMATTING
 
#if !UCONFIG_NO_MF2
 
#include "unicode/messageformat2_arguments.h"
#include "unicode/messageformat2_data_model.h"
#include "unicode/messageformat2_function_registry.h"
#include "unicode/unistr.h"
 
#ifndef U_HIDE_DEPRECATED_API
 
U_NAMESPACE_BEGIN
 
namespace message2 {
 
    class Environment;
    class MessageContext;
    class ResolvedSelector;
    class StaticErrors;
 
    class U_I18N_API MessageFormatter : public UObject {
        // Note: This class does not currently inherit from the existing
        // `Format` class.
    public:
        MessageFormatter& operator=(MessageFormatter&&) noexcept;
        virtual ~MessageFormatter();
 
        UnicodeString formatToString(const MessageArguments& arguments, UErrorCode &status);
 
        FormattedMessage format(const MessageArguments& arguments, UErrorCode &status) const {
            (void) arguments;
            if (U_SUCCESS(status)) {
                status = U_UNSUPPORTED_ERROR;
            }
            return FormattedMessage(status);
        }
 
        const Locale& getLocale() const { return locale; }
 
        UnicodeString getPattern() const;
 
        const MFDataModel& getDataModel() const;
 
        typedef enum UMFErrorHandlingBehavior {
            U_MF_BEST_EFFORT = 0,
            U_MF_STRICT
        } UMFErrorHandlingBehavior;
 
        class U_I18N_API Builder : public UObject {
        private:
            friend class MessageFormatter;
 
            // The pattern to be parsed to generate the formatted message
            UnicodeString pattern;
            bool hasPattern = false;
            bool hasDataModel = false;
            // The data model to be used to generate the formatted message
            // Initialized either by `setDataModel()`, or by the parser
            // through a call to `setPattern()`
            MFDataModel dataModel;
            // Normalized representation of the pattern;
            // ignored if `setPattern()` wasn't called
            UnicodeString normalizedInput;
            // Errors (internal representation of parse errors)
            // Ignored if `setPattern()` wasn't called
            StaticErrors* errors;
            Locale locale;
            // Not owned
            const MFFunctionRegistry* customMFFunctionRegistry;
            // Error behavior; see comment in `MessageFormatter` class
            bool signalErrors = false;
 
            void clearState();
        public:
            Builder& setLocale(const Locale& locale);
            Builder& setPattern(const UnicodeString& pattern, UParseError& parseError, UErrorCode& status);
            Builder& setFunctionRegistry(const MFFunctionRegistry& functionRegistry);
            Builder& setDataModel(MFDataModel&& dataModel);
            Builder& setErrorHandlingBehavior(UMFErrorHandlingBehavior type);
            MessageFormatter build(UErrorCode& status) const;
            Builder(UErrorCode& status);
            virtual ~Builder();
        }; // class MessageFormatter::Builder
 
        // TODO: Shouldn't be public; only used for testing
        const UnicodeString& getNormalizedPattern() const { return normalizedInput; }
 
    private:
        friend class Builder;
        friend class MessageContext;
 
        MessageFormatter(const MessageFormatter::Builder& builder, UErrorCode &status);
 
        MessageFormatter() = delete; // default constructor not implemented
 
        // Do not define default assignment operator
        const MessageFormatter &operator=(const MessageFormatter &) = delete;
 
        ResolvedSelector resolveVariables(const Environment& env, const data_model::Operand&, MessageContext&, UErrorCode &) const;
        ResolvedSelector resolveVariables(const Environment& env, const data_model::Expression&, MessageContext&, UErrorCode &) const;
 
        // Selection methods
 
        // Takes a vector of FormattedPlaceholders
        void resolveSelectors(MessageContext&, const Environment& env, UErrorCode&, UVector&) const;
        // Takes a vector of vectors of strings (input) and a vector of PrioritizedVariants (output)
        void filterVariants(const UVector&, UVector&, UErrorCode&) const;
        // Takes a vector of vectors of strings (input) and a vector of PrioritizedVariants (input/output)
        void sortVariants(const UVector&, UVector&, UErrorCode&) const;
        // Takes a vector of strings (input) and a vector of strings (output)
        void matchSelectorKeys(const UVector&, MessageContext&, ResolvedSelector&& rv, UVector&, UErrorCode&) const;
        // Takes a vector of FormattedPlaceholders (input),
        // and a vector of vectors of strings (output)
        void resolvePreferences(MessageContext&, UVector&, UVector&, UErrorCode&) const;
 
        // Formatting methods
        [[nodiscard]] FormattedPlaceholder formatLiteral(const data_model::Literal&) const;
        void formatPattern(MessageContext&, const Environment&, const data_model::Pattern&, UErrorCode&, UnicodeString&) const;
        // Formats a call to a formatting function
        // Dispatches on argument type
        [[nodiscard]] FormattedPlaceholder evalFormatterCall(FormattedPlaceholder&& argument,
                                                       MessageContext& context,
                                                       UErrorCode& status) const;
        // Dispatches on function name
        [[nodiscard]] FormattedPlaceholder evalFormatterCall(const FunctionName& functionName,
                                                       FormattedPlaceholder&& argument,
                                                       FunctionOptions&& options,
                                                       MessageContext& context,
                                                       UErrorCode& status) const;
        // Formats an expression that appears as a selector
        ResolvedSelector formatSelectorExpression(const Environment& env, const data_model::Expression&, MessageContext&, UErrorCode&) const;
        // Formats an expression that appears in a pattern or as the definition of a local variable
        [[nodiscard]] FormattedPlaceholder formatExpression(const Environment&, const data_model::Expression&, MessageContext&, UErrorCode&) const;
        [[nodiscard]] FunctionOptions resolveOptions(const Environment& env, const OptionMap&, MessageContext&, UErrorCode&) const;
        [[nodiscard]] FormattedPlaceholder formatOperand(const Environment&, const data_model::Operand&, MessageContext&, UErrorCode&) const;
        [[nodiscard]] FormattedPlaceholder evalArgument(const data_model::VariableName&, MessageContext&, UErrorCode&) const;
        void formatSelectors(MessageContext& context, const Environment& env, UErrorCode &status, UnicodeString& result) const;
 
        // Function registry methods
        bool hasCustomMFFunctionRegistry() const {
            return (customMFFunctionRegistry != nullptr);
        }
 
        // Precondition: custom function registry exists
        // Note: this is non-const because the values in the MFFunctionRegistry are mutable
        // (a FormatterFactory can have mutable state)
        const MFFunctionRegistry& getCustomMFFunctionRegistry() const;
 
        bool isCustomFormatter(const FunctionName&) const;
        FormatterFactory* lookupFormatterFactory(const FunctionName&, UErrorCode& status) const;
        bool isBuiltInSelector(const FunctionName&) const;
        bool isBuiltInFormatter(const FunctionName&) const;
        bool isCustomSelector(const FunctionName&) const;
        const SelectorFactory* lookupSelectorFactory(MessageContext&, const FunctionName&, UErrorCode&) const;
        bool isSelector(const FunctionName& fn) const { return isBuiltInSelector(fn) || isCustomSelector(fn); }
        bool isFormatter(const FunctionName& fn) const { return isBuiltInFormatter(fn) || isCustomFormatter(fn); }
        const Formatter* lookupFormatter(const FunctionName&, UErrorCode&) const;
 
        Selector* getSelector(MessageContext&, const FunctionName&, UErrorCode&) const;
        Formatter* getFormatter(const FunctionName&, UErrorCode&) const;
        bool getDefaultFormatterNameByType(const UnicodeString&, FunctionName&) const;
 
        // Checking for resolution errors
        void checkDeclarations(MessageContext&, Environment*&, UErrorCode&) const;
        void check(MessageContext&, const Environment&, const data_model::Expression&, UErrorCode&) const;
        void check(MessageContext&, const Environment&, const data_model::Operand&, UErrorCode&) const;
        void check(MessageContext&, const Environment&, const OptionMap&, UErrorCode&) const;
 
        void initErrors(UErrorCode&);
        void clearErrors() const;
        void cleanup() noexcept;
 
        // The locale this MessageFormatter was created with
        /* const */ Locale locale;
 
        // Registry for built-in functions
        MFFunctionRegistry standardMFFunctionRegistry;
        // Registry for custom functions; may be null if no custom registry supplied
        // Note: this is *not* owned by the MessageFormatter object
        // The reason for this choice is to have a non-destructive MessageFormatter::Builder,
        // while also not requiring the function registry to be deeply-copyable. Making the
        // function registry copyable would impose a requirement on any implementations
        // of the FormatterFactory and SelectorFactory interfaces to implement a custom
        // clone() method, which is necessary to avoid sharing between copies of the
        // function registry (and thus double-frees)
        // Not deeply immutable (the values in the function registry are mutable,
        // as a FormatterFactory can have mutable state
        const MFFunctionRegistry* customMFFunctionRegistry;
 
        // Data model, representing the parsed message
        MFDataModel dataModel;
 
        // Normalized version of the input string (optional whitespace removed)
        UnicodeString normalizedInput;
 
        // Errors -- only used while parsing and checking for data model errors; then
        // the MessageContext keeps track of errors
        // Must be a raw pointer to avoid including the internal header file
        // defining StaticErrors
        // Owned by `this`
        StaticErrors* errors = nullptr;
 
        // Error handling behavior.
        // If true, then formatting methods set their UErrorCode arguments
        // to signal MessageFormat errors, and no useful output is returned.
        // If false, then MessageFormat errors are not signaled and the
        // formatting methods return best-effort output.
        // The default is false.
        bool signalErrors = false;
    }; // class MessageFormatter
 
} // namespace message2
 
U_NAMESPACE_END
 
#endif // U_HIDE_DEPRECATED_API
 
#endif /* #if !UCONFIG_NO_MF2 */
 
#endif /* #if !UCONFIG_NO_FORMATTING */
 
#endif /* U_SHOW_CPLUSPLUS_API */
 
#endif // MESSAGEFORMAT2_H
 
// eof