Loading...
Searching...
No Matches
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_NORMALIZATION
#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/normalizer2.h"
#include "unicode/unistr.h"
#ifndef U_HIDE_DEPRECATED_API
U_NAMESPACE_BEGIN
namespace message2 {
class Environment;
class MessageContext;
class StaticErrors;
class InternalValue;
class U_I18N_API_CLASS MessageFormatter : public UObject {
// Note: This class does not currently inherit from the existing
// `Format` class.
public:
U_I18N_API MessageFormatter& operator=(MessageFormatter&&) noexcept;
U_I18N_API virtual ~MessageFormatter();
U_I18N_API UnicodeString formatToString(const MessageArguments& arguments, UErrorCode& status);
U_I18N_API FormattedMessage format(const MessageArguments& arguments, UErrorCode& status) const {
(void) arguments;
if (U_SUCCESS(status)) {
status = U_UNSUPPORTED_ERROR;
}
return FormattedMessage(status);
}
U_I18N_API const Locale& getLocale() const { return locale; }
U_I18N_API UnicodeString getPattern() const;
U_I18N_API const MFDataModel& getDataModel() const;
typedef enum UMFErrorHandlingBehavior {
U_MF_BEST_EFFORT = 0,
U_MF_STRICT
} UMFErrorHandlingBehavior;
class U_I18N_API_CLASS 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:
U_I18N_API Builder& setLocale(const Locale& locale);
U_I18N_API Builder& setPattern(const UnicodeString& pattern,
UParseError& parseError,
UErrorCode& status);
U_I18N_API Builder& setFunctionRegistry(const MFFunctionRegistry& functionRegistry);
U_I18N_API Builder& setDataModel(MFDataModel&& dataModel);
U_I18N_API Builder& setErrorHandlingBehavior(UMFErrorHandlingBehavior type);
U_I18N_API MessageFormatter build(UErrorCode& status) const;
U_I18N_API Builder(UErrorCode& status);
U_I18N_API virtual ~Builder();
}; // class MessageFormatter::Builder
// TODO: Shouldn't be public; only used for testing
U_I18N_API const UnicodeString& getNormalizedPattern() const { return normalizedInput; }
private:
friend class Builder;
friend class Checker;
friend class MessageArguments;
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;
// 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&, InternalValue* 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 UnicodeString&, const data_model::Literal&) const;
void formatPattern(MessageContext&, const Environment&, const data_model::Pattern&, UErrorCode&, UnicodeString&) const;
// Evaluates a function call
// Dispatches on argument type
[[nodiscard]] InternalValue* evalFunctionCall(FormattedPlaceholder&& argument,
MessageContext& context,
UErrorCode& status) const;
// Dispatches on function name
[[nodiscard]] InternalValue* evalFunctionCall(const FunctionName& functionName,
InternalValue* argument,
FunctionOptions&& options,
MessageContext& context,
UErrorCode& status) const;
// Formats an expression that appears in a pattern or as the definition of a local variable
[[nodiscard]] InternalValue* formatExpression(const UnicodeString&,
const Environment&,
const data_model::Expression&,
MessageContext&,
UErrorCode&) const;
[[nodiscard]] FunctionOptions resolveOptions(const Environment& env, const OptionMap&, MessageContext&, UErrorCode&) const;
[[nodiscard]] InternalValue* formatOperand(const UnicodeString&,
const Environment&,
const data_model::Operand&,
MessageContext&,
UErrorCode&) const;
[[nodiscard]] FormattedPlaceholder evalArgument(const UnicodeString&,
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 /* #if !UCONFIG_NO_NORMALIZATION */
#endif /* U_SHOW_CPLUSPLUS_API */
#endif // MESSAGEFORMAT2_H
// eof
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition locid.h:198
icu::UObject
UObject is the common ICU "boilerplate" class.
Definition uobject.h:222
icu::UnicodeString
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition unistr.h:303
icu::message2::FormattedMessage
Not yet implemented: The result of a message formatting operation.
Definition messageformat2_formattable.h:885
icu::message2::FormattedPlaceholder
A FormattablePlaceholder encapsulates an input value (a message2::Formattable) together with an optio...
Definition messageformat2_formattable.h:691
icu::message2::FunctionOptions
Structure encapsulating named options passed to a custom selector or formatter.
Definition messageformat2_formattable.h:490
icu::message2::MFFunctionRegistry
Defines mappings from names of formatters and selectors to functions implementing them.
Definition messageformat2_function_registry.h:119
icu::message2::MessageArguments
The MessageArguments class represents the named arguments to a message.
Definition messageformat2_arguments.h:47
icu::message2::MessageFormatter::Builder
The mutable Builder class allows each part of the MessageFormatter to be initialized separately; call...
Definition messageformat2.h:176
icu::message2::MessageFormatter::Builder::setErrorHandlingBehavior
U_I18N_API Builder & setErrorHandlingBehavior(UMFErrorHandlingBehavior type)
Set the error handling behavior for this formatter.
icu::message2::MessageFormatter::Builder::setPattern
U_I18N_API Builder & setPattern(const UnicodeString &pattern, UParseError &parseError, UErrorCode &status)
Sets the pattern (contents of the message) and parses it into a data model.
icu::message2::MessageFormatter::Builder::setDataModel
U_I18N_API Builder & setDataModel(MFDataModel &&dataModel)
Sets a data model.
icu::message2::MessageFormatter::Builder::setLocale
U_I18N_API Builder & setLocale(const Locale &locale)
Sets the locale to use for formatting.
icu::message2::MessageFormatter::Builder::setFunctionRegistry
U_I18N_API Builder & setFunctionRegistry(const MFFunctionRegistry &functionRegistry)
Sets a custom function registry.
icu::message2::MessageFormatter::Builder::~Builder
virtual U_I18N_API ~Builder()
Destructor.
icu::message2::MessageFormatter::Builder::Builder
U_I18N_API Builder(UErrorCode &status)
Default constructor.
icu::message2::MessageFormatter::Builder::build
U_I18N_API MessageFormatter build(UErrorCode &status) const
Constructs a new immutable MessageFormatter using the pattern or data model that was previously set,...
icu::message2::MessageFormatter
Definition messageformat2.h:54
icu::message2::MessageFormatter::formatToString
U_I18N_API UnicodeString formatToString(const MessageArguments &arguments, UErrorCode &status)
Formats the message to a string, using the data model that was previously set or parsed,...
icu::message2::MessageFormatter::format
U_I18N_API FormattedMessage format(const MessageArguments &arguments, UErrorCode &status) const
Not yet implemented; formats the message to a FormattedMessage object, using the data model that was ...
Definition messageformat2.h:105
icu::message2::MessageFormatter::getNormalizedPattern
U_I18N_API const UnicodeString & getNormalizedPattern() const
Returns a string consisting of the input with optional spaces removed.
Definition messageformat2.h:329
icu::message2::MessageFormatter::getLocale
U_I18N_API const Locale & getLocale() const
Accesses the locale that this MessageFormatter object was created with.
Definition messageformat2.h:121
icu::message2::MessageFormatter::getDataModel
U_I18N_API const MFDataModel & getDataModel() const
Accesses the data model referred to by this MessageFormatter object.
icu::message2::MessageFormatter::getPattern
U_I18N_API UnicodeString getPattern() const
Serializes the data model as a string in MessageFormat 2.0 syntax.
icu::message2::MessageFormatter::UMFErrorHandlingBehavior
UMFErrorHandlingBehavior
Used in conjunction with the MessageFormatter::Builder::setErrorHandlingBehavior() method.
Definition messageformat2.h:152
icu::message2::MessageFormatter::U_MF_BEST_EFFORT
@ U_MF_BEST_EFFORT
Suppress errors and return best-effort output.
Definition messageformat2.h:159
icu::message2::MessageFormatter::U_MF_STRICT
@ U_MF_STRICT
Signal all MessageFormat errors using the UErrorCode argument.
Definition messageformat2.h:167
icu::message2::MessageFormatter::operator=
U_I18N_API MessageFormatter & operator=(MessageFormatter &&) noexcept
Move assignment operator: The source MessageFormatter will be left in a valid but undefined state.
icu::message2::data_model::Expression
The Expression class corresponds to the expression nonterminal in the MessageFormat 2 grammar and the...
Definition messageformat2_data_model.h:1161
icu::message2::data_model::Literal
The Literal class corresponds to the literal nonterminal in the MessageFormat 2 grammar,...
Definition messageformat2_data_model.h:78
icu::message2::data_model::MFDataModel
The MFDataModel class describes a parsed representation of the text of a message.
Definition messageformat2_data_model.h:2095
icu::message2::data_model::Operand
The Operand class corresponds to the operand nonterminal in the MessageFormat 2 grammar,...
Definition messageformat2_data_model.h:215
icu::message2::data_model::Pattern
A Pattern is a sequence of formattable parts.
Definition messageformat2_data_model.h:1539
messageformat2_arguments.h
C++ API: Formats messages using the draft MessageFormat 2.0.
normalizer2.h
C++ API: New API for Unicode Normalization.
UParseError
A UParseError struct is used to returned detailed information about parsing errors.
Definition parseerr.h:58
unistr.h
C++ API: Unicode String.
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition utypes.h:509
U_UNSUPPORTED_ERROR
@ U_UNSUPPORTED_ERROR
Requested operation not supported in current context.
Definition utypes.h:561
U_SUCCESS
#define U_SUCCESS(x)
Does the error code indicate success?
Definition utypes.h:822
U_I18N_API_CLASS
#define U_I18N_API_CLASS
Set to export library symbols from inside the i18n library, and to import them from outside,...
Definition utypes.h:457
U_I18N_API
#define U_I18N_API
Set to export library symbols from inside the i18n library, and to import them from outside.
Definition utypes.h:316