diff --git a/spec/appendices.md b/spec/appendices.md index 364fc29c98..37c610c094 100644 --- a/spec/appendices.md +++ b/spec/appendices.md @@ -1,8 +1,8 @@ -# Appendices +## Appendices -## Security Considerations +### Security Considerations -MessageFormat 2.0 _patterns_ are meant to allow a _message_ to include any string value +MessageFormat _patterns_ are meant to allow a _message_ to include any string value which users might normally wish to use in their environment. Programming languages and other environments vary in what characters are permitted to appear in a valid string. @@ -25,7 +25,7 @@ but do not generate errors from MessageFormat parsers or processing APIs. Bidirectional text containing right-to-left characters (such as used for Arabic or Hebrew) also poses a potential source of confusion for users. -Since MessageFormat 2.0's syntax makes use of +Since MessageFormat's syntax makes use of keywords and symbols that are left-to-right or consist of neutral characters (including characters subject to mirroring under the Unicode Bidirectional Algorithm), it is possible to create messages that, @@ -35,7 +35,7 @@ have a misleading appearance or are difficult to parse visually. For more information, see \[[UTS#55](https://unicode.org/reports/tr55/)\] Unicode Source Code Handling. -MessageFormat 2.0 implementations might allow end-users to install +MessageFormat implementations might allow end-users to install _selectors_, _functions_, or _markup_ from third-party sources. Such functionality can be a vector for various exploits, including buffer overflow, code injection, user tracking, @@ -43,9 +43,9 @@ fingerprinting, and other types of bad behavior. Any installed code needs to be appropriately sandboxed. In addition, end-users need to be aware of the risks involved. -## Acknowledgements +### Acknowledgements -Special thanks to the following people for their contributions to making MessageFormat v2. +Special thanks to the following people for their contributions to making MessageFormat 2.0. The following people contributed to our github repo and are listed in order by contribution size: Addison Phillips, diff --git a/spec/data-model/README.md b/spec/data-model/README.md index 4058894b56..20ab3b3829 100644 --- a/spec/data-model/README.md +++ b/spec/data-model/README.md @@ -1,4 +1,4 @@ -# Interchange Data Model +## Interchange Data Model This section defines a data model representation of MessageFormat 2 _messages_. @@ -47,7 +47,7 @@ declarations, options, and attributes to be optional rather than required proper > sometimes uses the production `identifier`. > This happens when the named item, such as a _function_, supports namespacing. -## Messages +### Message Model A `SelectMessage` corresponds to a syntax message that includes _selectors_. A message without _selectors_ and with a single _pattern_ is represented by a `PatternMessage`. @@ -114,7 +114,7 @@ interface CatchallKey { } ``` -## Patterns +### Pattern Model Each `Pattern` contains a linear sequence of text and placeholders corresponding to potential output of a message. @@ -160,7 +160,7 @@ interface FunctionExpression { } ``` -## Expressions +### Expression Model The `Literal` and `VariableRef` correspond to the the _literal_ and _variable_ syntax rules. When they are used as the `body` of an `Expression`, @@ -200,7 +200,7 @@ interface FunctionRef { type Options = Map; ``` -## Markup +### Markup Model A `Markup` object has a `kind` of either `"open"`, `"standalone"`, or `"close"`, each corresponding to _open_, _standalone_, and _close_ _markup_. @@ -218,7 +218,7 @@ interface Markup { } ``` -## Attributes +### Attribute Model `Attributes` is a key-value mapping used to represent the _expression_ and _markup_ _attributes_. @@ -229,7 +229,7 @@ _Attributes_ with no value are represented by `true` here. type Attributes = Map; ``` -## Extensions +### Model Extensions Implementations MAY extend this data model with additional interfaces, as well as adding new fields to existing interfaces. diff --git a/spec/errors.md b/spec/errors.md index 7544e97faa..bf20700799 100644 --- a/spec/errors.md +++ b/spec/errors.md @@ -1,4 +1,4 @@ -# Errors +## Errors Errors can occur during the processing of a _message_. Some errors can be detected statically, @@ -9,7 +9,7 @@ Other errors might be detected during selection or formatting of a given _messag Where available, the use of validation tools is recommended, as early detection of errors makes their correction easier. -## Error Handling +### Error Handling _Syntax Errors_ and _Data Model Errors_ apply to all message processors, and MUST be emitted as soon as possible. @@ -51,7 +51,7 @@ or calling MatchSelectorKeys with its resolved value, the _selector_ MUST NOT match any _variant_ _key_ other than the catch-all `*` and a _Bad Selector_ error MUST be emitted. -## Syntax Errors +### Syntax Errors **_Syntax Errors_** occur when the syntax representation of a message is not _well-formed_. @@ -73,12 +73,12 @@ and a _Bad Selector_ error MUST be emitted. > .local $var = {|no message body|} > ``` -## Data Model Errors +### Data Model Errors **_Data Model Errors_** occur when a message is not _valid_ due to violating one of the semantic requirements on its structure. -### Variant Key Mismatch +#### Variant Key Mismatch A **_Variant Key Mismatch_** occurs when the number of keys on a _variant_ does not equal the number of _selectors_. @@ -101,7 +101,7 @@ does not equal the number of _selectors_. > * * {{Otherwise}} > ``` -### Missing Fallback Variant +#### Missing Fallback Variant A **_Missing Fallback Variant_** error occurs when the message does not include a _variant_ with only catch-all keys. @@ -123,7 +123,7 @@ does not include a _variant_ with only catch-all keys. > * 1 {{Second is one}} > ``` -### Missing Selector Annotation +#### Missing Selector Annotation A **_Missing Selector Annotation_** error occurs when the _message_ contains a _selector_ that does not @@ -151,7 +151,7 @@ directly or indirectly reference a _declaration_ with a _function_. > * {{Value is not one}} > ``` -### Duplicate Declaration +#### Duplicate Declaration A **_Duplicate Declaration_** error occurs when a _variable_ is declared more than once. Note that an input _variable_ is implicitly declared when it is first used, @@ -182,7 +182,7 @@ so explicitly declaring it after such use is also an error. > {{{$var} cannot be redefined. {$var2} cannot refer to itself}} > ``` -### Duplicate Option Name +#### Duplicate Option Name A **_Duplicate Option Name_** error occurs when the same _identifier_ appears on the left-hand side of more than one _option_ in the same _expression_. @@ -198,7 +198,7 @@ appears on the left-hand side of more than one _option_ in the same _expression_ > {{This is {$foo}}} > ``` -### Duplicate Variant +#### Duplicate Variant A **_Duplicate Variant_** error occurs when the same list of _keys_ is used for more than one _variant_. @@ -222,12 +222,12 @@ same list of _keys_ is used for more than one _variant_. > * * {{The default variant}} > ``` -## Resolution Errors +### Resolution Errors **_Resolution Errors_** occur when the runtime value of a part of a message cannot be determined. -### Unresolved Variable +#### Unresolved Variable An **_Unresolved Variable_** error occurs when a variable reference cannot be resolved. @@ -246,7 +246,7 @@ An **_Unresolved Variable_** error occurs when a variable reference c > * {{The value is not one.}} > ``` -### Unknown Function +#### Unknown Function An **_Unknown Function_** error occurs when an _expression_ includes a reference to a function which cannot be resolved. @@ -266,7 +266,7 @@ a reference to a function which cannot be resolved. > * {{The value is not one.}} > ``` -### Bad Selector +#### Bad Selector A **_Bad Selector_** error occurs when a message includes a _selector_ with a _resolved value_ which does not support selection. @@ -280,7 +280,7 @@ with a _resolved value_ which does not support selection. > * {{The due date is {$day}}} > ``` -## Message Function Errors +### Message Function Errors A **_Message Function Error_** is any error that occurs when calling a _function handler_ @@ -319,7 +319,7 @@ Implementations MAY also provide implementation-defined _Message Function Error_ > Your {$field} is {$id :ns:get field=$field} > ``` -### Bad Operand +#### Bad Operand A **_Bad Operand_** error is any error that occurs due to the content or format of the _operand_, such as when the _operand_ provided to a _function_ during _function resolution_ does not match one of the @@ -344,7 +344,7 @@ for that specific _function_. > * {{The value is not one.}} > ``` -### Bad Option +#### Bad Option A **_Bad Option_** error is an error that occurs when there is an implementation-defined error with an _option_ or its value. @@ -365,7 +365,7 @@ These might include: > The answer is {42 :number minimumFractionDigits=foo}. > ``` -### Bad Variant Key +#### Bad Variant Key A **_Bad Variant Key_** error is an error that occurs when a _variant_ _key_ does not match the expected implementation-defined format. @@ -383,7 +383,7 @@ does not match the expected implementation-defined format. > * {{The value is not one.}} > ``` -### Unsupported Operation +#### Unsupported Operation A **_Unsupported Operation_** error is an implementation-specific error that occurs when a given _option_, _option_ value, _operand_ value, or some combination diff --git a/spec/formatting.md b/spec/formatting.md index b6f8043815..cbd3eb23f5 100644 --- a/spec/formatting.md +++ b/spec/formatting.md @@ -1,8 +1,6 @@ -# Formatting - -## Introduction +## Formatting -This section defines the behavior of a MessageFormat 2.0 implementation +This section defines the behavior of a MessageFormat implementation when formatting a _message_ for display in a user interface, or for some later processing. To start, we presume that a _message_ has either been parsed from its syntax @@ -78,7 +76,7 @@ nor be made available to _function handlers_. > particularly since such a _function handler_ can present a remote execution hazard. > -## Formatting Context +### Formatting Context A _message_'s **_formatting context_** represents the data and procedures that are required for the _message_'s _expression resolution_, _pattern selection_ and _formatting_. @@ -104,7 +102,7 @@ At a minimum, it includes: Implementations MAY include additional fields in their _formatting context_. -## Resolved Values +### Resolved Values A **_resolved value_** is the result of resolving a _text_, _literal_, _variable_, _expression_, or _markup_. The _resolved value_ is determined using the _formatting context_. @@ -180,7 +178,7 @@ and different implementations MAY choose to perform different levels of resoluti > or automatically wrap each variable as a `MessageValue` to provide a uniform interface > for custom functions. -## Expression and Markup Resolution +### Expression and Markup Resolution _Expressions_ are used in _declarations_ and _patterns_. _Markup_ is only used in _patterns_. @@ -226,7 +224,7 @@ Its _resolved value_ is defined by _literal resolution_. > {{You have {42 :number}}} > ``` -### Literal Resolution +#### Literal Resolution The _resolved value_ of a _text_ or a _literal_ contains the character sequence of the _text_ or _literal_ @@ -256,7 +254,7 @@ whether its value was originally a _quoted literal_ or an _unquoted literal_. > } > ``` -### Variable Resolution +#### Variable Resolution To resolve the value of a _variable_, its _name_ is used to identify either a local variable or an input variable. @@ -274,7 +272,7 @@ a _fallback value_ is used as the _resolved value_ of the _variable_. The _fallback value_ representation of a _variable_ has a string representation consisting of the U+0024 DOLLAR SIGN `$` followed by the _name_ of the _variable_. -### Function Resolution +#### Function Resolution To resolve an _expression_ with a _function_, the following steps are taken: @@ -335,7 +333,7 @@ the following steps are taken: In all failure cases, return a _fallback value_ as the _resolved value_ of the _expression_. -#### Function Handler +##### Function Handler A **_function handler_** is an implementation-defined process such as a function or method @@ -367,7 +365,7 @@ and execution time SHOULD be limited. Implementation-defined _functions_ SHOULD use an implementation-defined _namespace_. -#### Option Resolution +##### Option Resolution **_Option resolution_** is the process of computing the _options_ for a given _expression_. @@ -402,7 +400,7 @@ This mapping can be empty. > These are not included in the _option resolution_ result, > and need to be processed separately by a _function handler_. -### Markup Resolution +#### Markup Resolution Unlike _functions_, the resolution of _markup_ is not customizable. @@ -418,7 +416,7 @@ Such `u:` options MAY be removed from the resolved mapping of _options_. The resolution of _markup_ MUST always succeed. -### Fallback Resolution +#### Fallback Resolution A **_fallback value_** is the _resolved value_ for an _expression_ or _variable_ when that _expression_ or _variable_ fails to resolve. @@ -505,7 +503,7 @@ _Pattern selection_ is not supported for _fallback values_. > } > ``` -## Pattern Selection +### Pattern Selection If the _message_ being formatted is not _well-formed_ and _valid_, the result of pattern selection is a _pattern_ consisting of a single _fallback value_ @@ -579,7 +577,7 @@ This selection method is defined in more detail below. An implementation MAY use any pattern selection method, as long as its observable behavior matches the results of the method defined here. -### Resolve Selectors +#### Resolve Selectors First, resolve the values of each _selector_: @@ -596,7 +594,7 @@ First, resolve the values of each _selector_: The form of the _resolved values_ is determined by each implementation, along with the manner of determining their support for selection. -### Resolve Preferences +#### Resolve Preferences Next, using `res`, resolve the preferential order for all message keys: @@ -628,7 +626,7 @@ If calling MatchSelectorKeys encounters any error, a _Bad Selector_ error is emitted and an empty list is returned. -### Filter Variants +#### Filter Variants Then, using the preferential key orders `pref`, filter the list of _variants_ to the ones that match with some preference: @@ -648,7 +646,7 @@ filter the list of _variants_ to the ones that match with some preference: 1. Continue the outer loop on message _variants_. 1. Append `var` as the last element of the list `vars`. -### Sort Variants +#### Sort Variants Finally, sort the list of variants `vars` and select the _pattern_: @@ -687,11 +685,11 @@ as long as it satisfies the following requirements: 1. The sort is stable (pairs of tuples from `sortable` that are equal in their first element have the same relative order in `sorted`). -### Examples +#### Pattern Selection Examples _This section is non-normative._ -#### Example 1 +##### Selection Example 1 Presuming a minimal implementation which only supports `:string` _function_ which matches keys by using string comparison, @@ -728,7 +726,7 @@ foo foo {{All foo}} 4. As the list `vars` only has one entry, it does not need to be sorted.
The pattern `Otherwise` of the third variant is selected. -#### Example 2 +##### Selection Example 2 Alternatively, with the same implementation and formatting context as in Example 1, pattern selection would proceed as follows for this message: @@ -770,7 +768,7 @@ foo bar {{Foo and bar}} 5. The pattern `Foo and bar` of the most preferred `foo bar` variant is selected. -#### Example 3 +##### Selection Example 3 A more-complex example is the matching found in selection APIs such as ICU's `PluralFormat`. @@ -811,7 +809,7 @@ one {{Category match for {$count}}} 4. The pattern `Exact match for {$count}` of the most preferred `1` variant is selected. -## Formatting +### Formatting of the Selected Pattern After _pattern selection_, each _text_ and _placeholder_ part of the selected _pattern_ is resolved and formatted. @@ -840,7 +838,7 @@ MUST be an empty string. Implementations MAY offer functionality for customizing this, such as by emitting XML-ish tags for each _markup_. -### Examples +#### Formatting Examples _This section is non-normative._ @@ -854,7 +852,7 @@ _This section is non-normative._ 2. A formatter in a web browser could format a message as a DOM fragment rather than as a representation of its HTML source. -### Formatting Fallback Values +#### Formatting Fallback Values If the resolved _pattern_ includes any _fallback values_ and the formatting result is a concatenated string or a sequence of strings, @@ -868,7 +866,7 @@ and a U+007D RIGHT CURLY BRACKET `}`. > unless a fallback string is defined in the _formatting context_, > in which case that string would be used instead. -### Handling Bidirectional Text +#### Handling Bidirectional Text _Messages_ contain text. Any text can be [bidirectional text](https://www.w3.org/TR/i18n-glossary/#dfn-bidirectional-text). diff --git a/spec/functions/README.md b/spec/functions/README.md index f828e2969c..6163c2429a 100644 --- a/spec/functions/README.md +++ b/spec/functions/README.md @@ -1,8 +1,7 @@ -# MessageFormat 2.0 Default Functions +## Default Functions -## Table of Contents +### Table of Contents -1. [Introduction](#introduction) 1. [String Value Selection and Formatting](string.md) 1. [`:string`](string.md#the-string-function) 1. [Numeric Value Selection and Formatting](number.md) @@ -16,13 +15,19 @@ 1. [`:date`](datetime.md#the-date-function) 1. [`:time`](datetime.md#the-time-function) -## Introduction - This section defines the **_default functions_** which are REQUIRED for conformance with this specification, along with _default functions_ that SHOULD be implemented to support additional functionality. +> [!IMPORTANT] +> _Functions_ that are not marked **Draft** are **Stable** and subject to +> the provisions of the [stability policy](../intro.md#stability-policy). +> +> _Functions_ or _options_ marked as **Draft** are not stable. +> Their name, _operands_, and _options_/_values_, and other requirements +> might change or be removed before being declared **Stable** in a future release. + To **_accept_** a function means that an implementation MUST NOT emit an _Unknown Function_ error for that _function_'s _identifier_. To _accept_ an _option_ means that a _function handler_ MUST NOT diff --git a/spec/functions/datetime.md b/spec/functions/datetime.md index 1bf33e9f69..bb7017627a 100644 --- a/spec/functions/datetime.md +++ b/spec/functions/datetime.md @@ -1,13 +1,16 @@ ## Date and Time Value Formatting -This subsection describes the functions and options for date/time formatting. -Selection based on date and time values is NOT REQUIRED in this release. +This subsection describes the _functions_ and _options_ for date/time formatting. + +> [!IMPORTANT] +> The _functions_ in this section have a status of **Draft**. +> They are proposed for inclusion in a future release and are not Stable. > [!NOTE] -> Selection based on date/time types is not required by MF2. -> Implementations should use care when defining selectors based on date/time types. +> Selection based on date/time types is not required by this release of MessageFormat. +> Use care when defining implementation-specific _selectors_ based on date/time types. > The types of queries found in implementations such as `java.time.TemporalAccessor` -> are complex and user expectations may be inconsistent with good I18N practices. +> are complex and user expectations might be inconsistent with good I18N practices. ### The `:datetime` function @@ -278,11 +281,8 @@ the functions `:datetime`, `:date`, and `:time`. - `calendar` - valid [Unicode Calendar Identifier](https://unicode.org/reports/tr35/tr35.html#UnicodeCalendarIdentifier) -The following _option_ and its values are **Proposed** for -inclusion in the next release of this specification but have not yet been -finalized. -If accepted, implementations could be REQUIRED to make this _option_ -available in the functions `:datetime`, `:date`, and `:time`. +The following _option_ and its values are REQUIRED to be available on +the functions `:datetime`, `:date`, and `:time`. - `timeZone` - A valid time zone identifier diff --git a/spec/functions/number.md b/spec/functions/number.md index 4fbc66484d..d739418e37 100644 --- a/spec/functions/number.md +++ b/spec/functions/number.md @@ -161,7 +161,11 @@ The _function_ `:integer` performs selection as described in [Number Selection]( ### The `:math` function -The function `:math` is a selector and formatter for matching or formatting +> [!IMPORTANT] +> The _function_ `:math` has a status of **Draft**. +> It is proposed for inclusion in a future release of this specification and is not Stable. + +The _function_ `:math` is proposed as a _selector_ and _formatter_ for matching or formatting numeric values to which a mathematical operation has been applied. > This function is useful for selection and formatting of values that @@ -233,7 +237,11 @@ The _function_ `:math` performs selection as described in [Number Selection](#nu ### The `:currency` function -The function `:currency` is a formatter for currency values, +> [!IMPORTANT] +> The _function_ `:currency` has a status of **Draft**. +> It is proposed for inclusion in a future release of this specification and is not Stable. + +The _function_ `:currency` is a _formatter_ for currency values, which are a specialized form of numeric formatting. #### Operands @@ -407,7 +415,10 @@ together with the resolved options' values. ### The `:unit` function -The _function_ `:unit` is **Proposed** for inclusion in the next release of this specification but has not yet been finalized. +> [!IMPORTANT] +> The _function_ `:unit` has a status of **Draft**. +> It is proposed for inclusion in a future release of this specification and is not Stable. + The _function_ `:unit` is proposed to be a RECOMMENDED formatter for unitized values, that is, for numeric values associated with a unit of measurement. This is a specialized form of numeric formatting. @@ -606,7 +617,7 @@ such as the number of fraction, integer, or significant digits. A "digit size option" is an _option_ value that the _function_ interprets as a small integer value greater than or equal to zero. Implementations MAY define an upper limit on the _resolved value_ -of a digit size option option consistent with that implementation's practical limits. +of a digit size option consistent with that implementation's practical limits. In most cases, the value of a digit size option will be a string that encodes the value as a non-negative integer. diff --git a/spec/intro.md b/spec/intro.md index 8d9ae6842a..9b318be4b8 100644 --- a/spec/intro.md +++ b/spec/intro.md @@ -78,14 +78,8 @@ A reference to a _term_ looks like this. ### Stability Policy -> [!IMPORTANT] -> The provisions of the stability policy are not in effect until -> the conclusion of the technical preview and adoption of this specification. - Updates to this specification will not make any valid _message_ invalid. -Updates to this specification will not remove any syntax provided in this version. - Updates to this specification will not specify an _error_ for any _message_ that previously did not specify an _error_. diff --git a/spec/syntax.md b/spec/syntax.md index bb5ea94370..a0d0650432 100644 --- a/spec/syntax.md +++ b/spec/syntax.md @@ -1,6 +1,4 @@ -# Syntax - -### Introduction +## Syntax This section defines the formal grammar describing the syntax of a single message. @@ -23,7 +21,7 @@ The design goals of the syntax specification are as follows: as well as making the selection logic predictable and easy to reason about. - _Non-Goal_: Make the syntax intuitive enough for non-technical translators to hand-edit. - Instead, we assume that most translators will work with MessageFormat 2 + Instead, we assume that most translators will work with MessageFormat by means of GUI tooling, CAT workbenches etc. 1. The syntax surrounding translatable content should be easy to write and edit @@ -59,7 +57,7 @@ The syntax specification takes into account the following design restrictions: U+100000 through U+10FFFD), unassigned code points, unpaired surrogates (U+D800 through U+DFFF), and other potentially confusing content. -## Messages and their Syntax +### Messages and their Syntax The purpose of MessageFormat is to allow content to vary at runtime. This variation might be due to placing a value into the content @@ -79,7 +77,7 @@ during the [formatting](./formatting.md) of a _message_ at runtime. The complete formal syntax of a _message_ is described by the [ABNF](./message.abnf). -### Well-formed vs. Valid Messages +#### Well-formed vs. Valid Messages A _message_ is **_well-formed_** if it satisfies all the rules of the grammar. Attempting to parse a _message_ that is not _well-formed_ will result in a _Syntax Error_. @@ -90,7 +88,7 @@ and semantic requirements about its structure defined below for _declarations_, _matcher_, and _options_. Attempting to parse a _message_ that is not _valid_ will result in a _Data Model Error_. -## The Message +### The Message A **_message_** is the complete template for a specific message formatting request. @@ -146,7 +144,7 @@ A **_local variable_** is a _variable_ created as the result of a _lo > > An exception to this is: whitespace inside a _pattern_ is **always** significant. > [!NOTE] -> The MessageFormat 2 syntax assumes that each _message_ will be displayed +> The MessageFormat syntax assumes that each _message_ will be displayed > with a left-to-right display order > and be processed in the logical character order. > The syntax permits the use of right-to-left characters in _identifiers_, @@ -194,7 +192,7 @@ and does not affect the processing of the _message_. complex-message = o *(declaration o) complex-body o ``` -### Declarations +#### Declarations A **_declaration_** binds a _variable_ identifier to a value within the scope of a _message_. This _variable_ can then be used in other _expressions_ within the same _message_. @@ -238,7 +236,7 @@ external input value does not appear in a previous _declaration_. > ``` > (See the [Errors](./errors.md) section for examples of invalid messages) -### Complex Body +#### Complex Body The **_complex body_** of a _complex message_ is the part that will be formatted. The _complex body_ consists of either a _quoted pattern_ or a _matcher_. @@ -247,7 +245,7 @@ The _complex body_ consists of either a _quoted pattern_ or a _matcher_. complex-body = quoted-pattern / matcher ``` -## Pattern +### Pattern A **_pattern_** contains a sequence of _text_ and _placeholders_ to be formatted as a unit. Unless there is an error, resolving a _message_ always results in the formatting @@ -261,7 +259,7 @@ A _pattern_ MAY be empty. A _pattern_ MAY contain an arbitrary number of _placeholders_ to be evaluated during the formatting process. -### Quoted Pattern +#### Quoted Pattern A **_quoted pattern_** is a _pattern_ that is "quoted" to prevent interference with other parts of the _message_. @@ -280,7 +278,7 @@ A _quoted pattern_ MAY be empty. > {{}} > ``` -### Text +#### Text **_text_** is the translateable content of a _pattern_. Any Unicode code point is allowed, except for U+0000 NULL. @@ -336,7 +334,7 @@ Otherwise, care must be taken to ensure that pattern-significant whitespace is p > hello2=\ Hello \ > ``` -### Placeholder +#### Placeholder A **_placeholder_** is an _expression_ or _markup_ that appears inside of a _pattern_ and which will be replaced during the formatting of a _message_. @@ -345,7 +343,7 @@ and which will be replaced during the formatting of a _message_. placeholder = expression / markup ``` -## Matcher +### Matcher A **_matcher_** is the _complex body_ of a _message_ that allows runtime selection of the _pattern_ to use for formatting. @@ -393,7 +391,7 @@ match-statement = match 1*(s selector) > .local $os = {:platform} .match $os windows {{Settings}} * {{Preferences}} > ``` -### Selector +#### Selector A **_selector_** is a _variable_ whose _resolved value_ ranks or excludes the _variants_ based on the value of the corresponding _key_ in each _variant_. @@ -436,7 +434,7 @@ There MAY be any number of additional _selectors_. > * * {{Your item has {$numLikes} likes and has been shared {$numShares} times.}} > ``` -### Variant +#### Variant A **_variant_** is a _quoted pattern_ associated with a list of _keys_ in a _matcher_. Each _variant_ MUST begin with a sequence of _keys_, @@ -451,7 +449,7 @@ variant = key *(s key) o quoted-pattern key = literal / "*" ``` -#### Key +##### Key A **_key_** is a value in a _variant_ for use by a _selector_ when ranking or excluding _variants_ during the _matcher_ process. @@ -476,7 +474,7 @@ Two _literal_ _keys_ are considered equal if they are canonically equivalent str that is, if they consist of the same sequence of Unicode code points after Unicode Normalization Form C has been applied to both. -## Expressions +### Expressions An **_expression_** is a part of a _message_ that will be determined during the _message_'s formatting. @@ -530,12 +528,12 @@ Additionally, an _input-declaration_ can contain a _variable-expression_. > This placeholder contains a function expression with a variable-valued option: {:ns:func option=$variable} > ``` -### Operand +#### Operand An **_operand_** is the _literal_ of a _literal-expression_ or the _variable_ of a _variable-expression_. -#### Function +##### Function A **_function_** is named functionality in an _expression_. _Functions_ are used to evaluate, format, select, or otherwise process data @@ -565,7 +563,7 @@ function = ":" identifier *(s option) > It is now {$now :datetime}. > ``` -##### Options +###### Options An **_option_** is a key-value pair containing a named argument that is passed to a _function_. @@ -604,7 +602,7 @@ option = identifier o "=" o (literal / variable) > Today is {$date :datetime weekday=$dateStyle}! > ``` -## Markup +### Markup **_Markup_** _placeholders_ are _pattern_ parts that can be used to represent non-language parts of a _message_, @@ -653,7 +651,7 @@ _Markup_ _placeholders_ can appear in any order without making the _message_ inv However, specifications or implementations defining _markup_ might impose requirements on the pairing, ordering, or contents of _markup_ during _formatting_. -## Attributes +### Attributes An **_attribute_** is an _identifier_ with an optional value that appears in an _expression_ or in _markup_. @@ -690,11 +688,11 @@ attribute = "@" identifier [o "=" o literal] > Have a {#span @can-copy}great and wonderful{/span @can-copy} birthday! > ``` -## Other Syntax Elements +### Other Syntax Elements This section defines common elements used to construct _messages_. -### Keywords +#### Keywords A **_keyword_** is a reserved token that has a unique meaning in the _message_ syntax. @@ -707,7 +705,7 @@ local = %s".local" match = %s".match" ``` -### Literals +#### Literals A **_literal_** is a character sequence that appears outside of _text_ in various parts of a _message_. @@ -758,7 +756,7 @@ quoted-literal = "|" *(quoted-char / escaped-char) "|" unquoted-literal = 1*name-char ``` -### Names and Identifiers +#### Names and Identifiers A **_name_** is a character sequence used in an _identifier_ or as the name for a _variable_ @@ -920,7 +918,7 @@ unless required by the syntax. That is, inside _literals_ only escape `|` and inside _patterns_ only escape `{` and `}`. -### Whitespace +#### Whitespace The syntax limits whitespace characters outside of a _pattern_ to the following: `U+0009 CHARACTER TABULATION` (tab), @@ -983,7 +981,7 @@ following mechanisms to make messages display intelligibly in plain-text editors > marks in _messages_, since the characters are invisible and can be difficult > to manage. > Tools (such as resource editors or translation editors) -> and other implementations of MessageFormat 2 serialization are strongly +> and other implementations of MessageFormat serialization are strongly > encouraged to provide paired isolates around any right-to-left > syntax as described above so that _messages_ display appropriately as plain text. @@ -1030,7 +1028,7 @@ bidi = %x061C / %x200E / %x200F / %x2066-2069 ws = SP / HTAB / CR / LF / %x3000 ``` -## Complete ABNF +### Complete ABNF The grammar is formally defined in [`message.abnf`](./message.abnf) using the ABNF notation [[STD68](https://www.rfc-editor.org/info/std68)], diff --git a/spec/u-namespace.md b/spec/u-namespace.md index accabf6d9c..375b2739a1 100644 --- a/spec/u-namespace.md +++ b/spec/u-namespace.md @@ -1,4 +1,4 @@ -# MessageFormat Unicode Namespace +## Unicode Namespace The `u:` _namespace_ is reserved for the definition of _options_ which affect the _function context_ of the specific _expressions_ @@ -10,13 +10,13 @@ It might also be used to define _functions_ in a future release. The CLDR Technical Committee of the Unicode Consortium manages the specification for this namespace, hence the _namespace_ `u:`. -## Options +### Unicode Namespace Options This section describes **_`u:` options_**. When implemented, they apply to all _functions_ and _markup_, including user-defined _functions_ in that implementation. -### `u:id` +#### `u:id` Implementations providing a formatting target other than a concatenated string SHOULD support this option. @@ -40,7 +40,7 @@ or can be resolved to a string without error. For other values, a _Bad Option_ error is emitted and the `u:id` option is ignored. -### `u:locale` +#### `u:locale` > [!IMPORTANT] > This _option_ has a status of **Draft**. @@ -82,7 +82,7 @@ This might be because the locale specified is not supported or because the language tag is not well-formed, not valid, or some other reason. -### `u:dir` +#### `u:dir` Implementations SHOULD support this option.