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
icu::LocalPointerBase
"Smart pointer" base class; do not use directly: use LocalPointer etc.
Definition localpointer.h:68
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition locid.h:195
icu::UObject
UObject is the common ICU "boilerplate" class.
Definition uobject.h:223
icu::UnicodeString
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition unistr.h:296
icu::message2::FormattedMessage
Not yet implemented: The result of a message formatting operation.
Definition messageformat2_formattable.h:881
icu::message2::FormattedPlaceholder
A FormattablePlaceholder encapsulates an input value (a message2::Formattable) together with an optio...
Definition messageformat2_formattable.h:686
icu::message2::FunctionOptions
Structure encapsulating named options passed to a custom selector or formatter.
Definition messageformat2_formattable.h:488
icu::message2::MFFunctionRegistry
Defines mappings from names of formatters and selectors to functions implementing them.
Definition messageformat2_function_registry.h:117
icu::message2::MessageArguments
The MessageArguments class represents the named arguments to a message.
Definition messageformat2_arguments.h:59
icu::message2::MessageFormatter::Builder
The mutable Builder class allows each part of the MessageFormatter to be initialized separately; call...
Definition messageformat2.h:173
icu::message2::MessageFormatter::Builder::~Builder
virtual ~Builder()
Destructor.
icu::message2::MessageFormatter::Builder::setFunctionRegistry
Builder & setFunctionRegistry(const MFFunctionRegistry &functionRegistry)
Sets a custom function registry.
icu::message2::MessageFormatter::Builder::build
MessageFormatter build(UErrorCode &status) const
Constructs a new immutable MessageFormatter using the pattern or data model that was previously set,...
icu::message2::MessageFormatter::Builder::setLocale
Builder & setLocale(const Locale &locale)
Sets the locale to use for formatting.
icu::message2::MessageFormatter::Builder::Builder
Builder(UErrorCode &status)
Default constructor.
icu::message2::MessageFormatter::Builder::setErrorHandlingBehavior
Builder & setErrorHandlingBehavior(UMFErrorHandlingBehavior type)
Set the error handling behavior for this formatter.
icu::message2::MessageFormatter::Builder::setPattern
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
Builder & setDataModel(MFDataModel &&dataModel)
Sets a data model.
icu::message2::MessageFormatter
Definition messageformat2.h:51
icu::message2::MessageFormatter::getLocale
const Locale & getLocale() const
Accesses the locale that this MessageFormatter object was created with.
Definition messageformat2.h:118
icu::message2::MessageFormatter::getNormalizedPattern
const UnicodeString & getNormalizedPattern() const
Returns a string consisting of the input with optional spaces removed.
Definition messageformat2.h:324
icu::message2::MessageFormatter::getPattern
UnicodeString getPattern() const
Serializes the data model as a string in MessageFormat 2.0 syntax.
icu::message2::MessageFormatter::operator=
MessageFormatter & operator=(MessageFormatter &&) noexcept
Move assignment operator: The source MessageFormatter will be left in a valid but undefined state.
icu::message2::MessageFormatter::UMFErrorHandlingBehavior
UMFErrorHandlingBehavior
Used in conjunction with the MessageFormatter::Builder::setErrorHandlingBehavior() method.
Definition messageformat2.h:149
icu::message2::MessageFormatter::getDataModel
const MFDataModel & getDataModel() const
Accesses the data model referred to by this MessageFormatter object.
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:1265
icu::message2::data_model::Literal
The Literal class corresponds to the literal nonterminal in the MessageFormat 2 grammar,...
Definition messageformat2_data_model.h:76
messageformat2_arguments.h
C++ API: Formats messages using the draft MessageFormat 2.0.
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:430
U_UNSUPPORTED_ERROR
@ U_UNSUPPORTED_ERROR
Requested operation not supported in current context.
Definition utypes.h:482
U_SUCCESS
#define U_SUCCESS(x)
Does the error code indicate success?
Definition utypes.h:742
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