com.ibm.icu.text
Class MessagePattern

java.lang.Object
  com.ibm.icu.text.MessagePattern

All Implemented Interfaces:

Freezable<MessagePattern>, Cloneable

public final class MessagePattern
extends Object
implements Cloneable, Freezable<MessagePattern>

Parses and represents ICU MessageFormat patterns. Also handles patterns for ChoiceFormat, PluralFormat and SelectFormat. Used in the implementations of those classes as well as in tools for message validation, translation and format conversion.

The parser handles all syntax relevant for identifying message arguments. This includes "complex" arguments whose style strings contain nested MessageFormat pattern substrings. For "simple" arguments (with no nested MessageFormat pattern substrings), the argument style is not parsed any further.

The parser handles named and numbered message arguments and allows both in one message.

Once a pattern has been parsed successfully, iterate through the parsed data with countParts(), getPart() and related methods.

The data logically represents a parse tree, but is stored and accessed as a list of "parts" for fast and simple parsing and to minimize object allocations. Arguments and nested messages are best handled via recursion. For every _START "part", getLimitPartIndex(int) efficiently returns the index of the corresponding _LIMIT "part".

List of "parts":

 message = MSG_START (SKIP_SYNTAX | INSERT_CHAR | REPLACE_NUMBER | argument)* MSG_LIMIT
 argument = noneArg | simpleArg | complexArg
 complexArg = choiceArg | pluralArg | selectArg

 noneArg = ARG_START.NONE (ARG_NAME | ARG_NUMBER) ARG_LIMIT.NONE
 simpleArg = ARG_START.SIMPLE (ARG_NAME | ARG_NUMBER) ARG_TYPE [ARG_STYLE] ARG_LIMIT.SIMPLE
 choiceArg = ARG_START.CHOICE (ARG_NAME | ARG_NUMBER) choiceStyle ARG_LIMIT.CHOICE
 pluralArg = ARG_START.PLURAL (ARG_NAME | ARG_NUMBER) pluralStyle ARG_LIMIT.PLURAL
 selectArg = ARG_START.SELECT (ARG_NAME | ARG_NUMBER) selectStyle ARG_LIMIT.SELECT

 choiceStyle = ((ARG_INT | ARG_DOUBLE) ARG_SELECTOR message)+
 pluralStyle = [ARG_INT | ARG_DOUBLE] (ARG_SELECTOR [ARG_INT | ARG_DOUBLE] message)+
 selectStyle = (ARG_SELECTOR message)+
 

• Literal output text is not represented directly by "parts" but accessed between parts of a message, from one part's getLimit() to the next part's getIndex().
• ARG_START.CHOICE stands for an ARG_START Part with ArgType CHOICE.
• In the choiceStyle, the ARG_SELECTOR has the '<', the '#' or the less-than-or-equal-to sign (U+2264).
• In the pluralStyle, the first, optional numeric Part has the "offset:" value. The optional numeric Part between each (ARG_SELECTOR, message) pair is the value of an explicit-number selector like "=2", otherwise the selector is a non-numeric identifier.
• The REPLACE_NUMBER Part can occur only in an immediate sub-message of the pluralStyle.

  This class is not intended for public subclassing.

  Author:

  Markus Scherer

  Status:

  Draft ICU 4.8.

  Nested Class Summary

  static class	MessagePattern.ApostropheMode Mode for when an apostrophe starts quoted literal text for MessageFormat output.
  static class	MessagePattern.ArgType Argument type constants.
  static class	MessagePattern.Part A message pattern "part", representing a pattern parsing event.

  Field Summary

  static int	ARG_NAME_NOT_NUMBER Return value from validateArgumentName(String) for when the string is a valid "pattern identifier" but not a number.
  static int	ARG_NAME_NOT_VALID Return value from validateArgumentName(String) for when the string is invalid.
  static double	NO_NUMERIC_VALUE Special value that is returned by getNumericValue(Part) when no numeric value is defined for a part.

  Constructor Summary

  MessagePattern()
  Constructs an empty MessagePattern with default ApostropheMode.

  MessagePattern(MessagePattern.ApostropheMode mode)
  Constructs an empty MessagePattern.

  MessagePattern(String pattern)
  Constructs a MessagePattern with default ApostropheMode and parses the MessageFormat pattern string.

  Method Summary

  String	autoQuoteApostropheDeep() Returns a version of the parsed pattern string where each ASCII apostrophe is doubled (escaped) if it is not already, and if it is not interpreted as quoting syntax.
  void	clear() Clears this MessagePattern.
  void	clearPatternAndSetApostropheMode(MessagePattern.ApostropheMode mode) Clears this MessagePattern and sets the ApostropheMode.
  Object	clone() Creates and returns a copy of this object.
  MessagePattern	cloneAsThawed() Creates and returns an unfrozen copy of this object.
  int	countParts() Returns the number of "parts" created by parsing the pattern string.
  boolean	equals(Object other)
  MessagePattern	freeze() Freezes this object, making it immutable and thread-safe.
  MessagePattern.ApostropheMode	getApostropheMode()
  int	getLimitPartIndex(int start) Returns the index of the ARG|MSG_LIMIT part corresponding to the ARG|MSG_START at start.
  double	getNumericValue(MessagePattern.Part part) Returns the numeric value associated with an ARG_INT or ARG_DOUBLE.
  MessagePattern.Part	getPart(int i) Gets the i-th pattern "part".
  MessagePattern.Part.Type	getPartType(int i) Returns the Part.Type of the i-th pattern "part".
  int	getPatternIndex(int partIndex) Returns the pattern index of the specified pattern "part".
  String	getPatternString()
  double	getPluralOffset(int pluralStart) Returns the "offset:" value of a PluralFormat argument, or 0 if none is specified.
  String	getSubstring(MessagePattern.Part part) Returns the substring of the pattern string indicated by the Part.
  int	hashCode()
  boolean	hasNamedArguments() Does the parsed pattern have named arguments like {first_name}?
  boolean	hasNumberedArguments() Does the parsed pattern have numbered arguments like {2}?
  boolean	isFrozen() Determines whether this object is frozen (immutable) or not.
  MessagePattern	parse(String pattern) Parses a MessageFormat pattern string.
  MessagePattern	parseChoiceStyle(String pattern) Parses a ChoiceFormat pattern string.
  MessagePattern	parsePluralStyle(String pattern) Parses a PluralFormat pattern string.
  MessagePattern	parseSelectStyle(String pattern) Parses a SelectFormat pattern string.
  boolean	partSubstringMatches(MessagePattern.Part part, String s) Compares the part's substring with the input string s.
  String	toString()
  static int	validateArgumentName(String name) Validates and parses an argument name or argument number string.

  Methods inherited from class java.lang.Object

  finalize, getClass, notify, notifyAll, wait, wait, wait

  Field Detail

  ARG_NAME_NOT_NUMBER

  public static final int ARG_NAME_NOT_NUMBER

  Return value from validateArgumentName(String) for when the string is a valid "pattern identifier" but not a number.

  See Also:

  Constant Field Values

  Status:

  Draft ICU 4.8.

  ARG_NAME_NOT_VALID

  public static final int ARG_NAME_NOT_VALID

  Return value from validateArgumentName(String) for when the string is invalid. It might not be a valid "pattern identifier", or it have only ASCII digits but there is a leading zero or the number is too large.

  See Also:

  Constant Field Values

  Status:

  Draft ICU 4.8.

  NO_NUMERIC_VALUE

  public static final double NO_NUMERIC_VALUE

  Special value that is returned by getNumericValue(Part) when no numeric value is defined for a part.

  See Also:

  getNumericValue(com.ibm.icu.text.MessagePattern.Part), Constant Field Values

  Status:

  Draft ICU 4.8.

  Constructor Detail

  MessagePattern

  public MessagePattern()

  Constructs an empty MessagePattern with default ApostropheMode.

  Status:

  Draft ICU 4.8.

  MessagePattern

  public MessagePattern(MessagePattern.ApostropheMode mode)

  Constructs an empty MessagePattern.

  Parameters:

  mode - Explicit ApostropheMode.

  Status:

  Draft ICU 4.8.

  MessagePattern

  public MessagePattern(String pattern)

  Constructs a MessagePattern with default ApostropheMode and parses the MessageFormat pattern string.

  Parameters:

  pattern - a MessageFormat pattern string

  Throws:

  IllegalArgumentException - for syntax errors in the pattern string

  IndexOutOfBoundsException - if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)

  NumberFormatException - if a number could not be parsed

  Status:

  Draft ICU 4.8.

  Method Detail

  parse

  public MessagePattern parse(String pattern)

  Parses a MessageFormat pattern string.

  Parameters:

  pattern - a MessageFormat pattern string

  Returns:

  this

  Throws:

  IllegalArgumentException - for syntax errors in the pattern string

  IndexOutOfBoundsException - if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)

  NumberFormatException - if a number could not be parsed

  Status:

  Draft ICU 4.8.

  parseChoiceStyle

  public MessagePattern parseChoiceStyle(String pattern)

  Parses a ChoiceFormat pattern string.

  Parameters:

  pattern - a ChoiceFormat pattern string

  Returns:

  this

  Throws:

  IllegalArgumentException - for syntax errors in the pattern string

  IndexOutOfBoundsException - if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)

  NumberFormatException - if a number could not be parsed

  Status:

  Draft ICU 4.8.

  parsePluralStyle

  public MessagePattern parsePluralStyle(String pattern)

  Parses a PluralFormat pattern string.

  Parameters:

  pattern - a PluralFormat pattern string

  Returns:

  this

  Throws:

  IllegalArgumentException - for syntax errors in the pattern string

  IndexOutOfBoundsException - if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)

  NumberFormatException - if a number could not be parsed

  Status:

  Draft ICU 4.8.

  parseSelectStyle

  public MessagePattern parseSelectStyle(String pattern)

  Parses a SelectFormat pattern string.

  Parameters:

  pattern - a SelectFormat pattern string

  Returns:

  this

  Throws:

  IllegalArgumentException - for syntax errors in the pattern string

  IndexOutOfBoundsException - if certain limits are exceeded (e.g., argument number too high, argument name too long, etc.)

  NumberFormatException - if a number could not be parsed

  Status:

  Draft ICU 4.8.

  clear

  public void clear()

  Clears this MessagePattern. countParts() will return 0.

  Status:

  Draft ICU 4.8.

  clearPatternAndSetApostropheMode

  public void clearPatternAndSetApostropheMode(MessagePattern.ApostropheMode mode)

  Clears this MessagePattern and sets the ApostropheMode. countParts() will return 0.

  Parameters:

  mode - The new ApostropheMode.

  Status:

  Draft ICU 4.8.

  equals

  public boolean equals(Object other)

  Overrides:

  equals in class Object

  Parameters:

  other - another object to compare with.

  Returns:

  true if this object is equivalent to the other one.

  Status:

  Draft ICU 4.8.

  hashCode

  public int hashCode()

  Overrides:

  hashCode in class Object

  Status:

  Draft ICU 4.8.

  getApostropheMode

  public MessagePattern.ApostropheMode getApostropheMode()

  Returns:

  this instance's ApostropheMode.

  Status:

  Draft ICU 4.8.

  getPatternString

  public String getPatternString()

  Returns:

  the parsed pattern string (null if none was parsed).

  Status:

  Draft ICU 4.8.

  hasNamedArguments

  public boolean hasNamedArguments()

  Does the parsed pattern have named arguments like {first_name}?

  Returns:

  true if the parsed pattern has at least one named argument.

  Status:

  Draft ICU 4.8.

  hasNumberedArguments

  public boolean hasNumberedArguments()

  Does the parsed pattern have numbered arguments like {2}?

  Returns:

  true if the parsed pattern has at least one numbered argument.

  Status:

  Draft ICU 4.8.

  toString

  public String toString()

  Overrides:

  toString in class Object

  Status:

  Draft ICU 4.8.

  validateArgumentName

  public static int validateArgumentName(String name)

  Validates and parses an argument name or argument number string. An argument name must be a "pattern identifier", that is, it must contain no Unicode Pattern_Syntax or Pattern_White_Space characters. If it only contains ASCII digits, then it must be a small integer with no leading zero.

  Parameters:

  name - Input string.

  Returns:

  >=0 if the name is a valid number, ARG_NAME_NOT_NUMBER (-1) if it is a "pattern identifier" but not all ASCII digits, ARG_NAME_NOT_VALID (-2) if it is neither.

  Status:

  Draft ICU 4.8.

  autoQuoteApostropheDeep

  public String autoQuoteApostropheDeep()

  Returns a version of the parsed pattern string where each ASCII apostrophe is doubled (escaped) if it is not already, and if it is not interpreted as quoting syntax.

  For example, this turns "I don't '{know}' {gender,select,female{h''er}other{h'im}}." into "I don''t '{know}' {gender,select,female{h''er}other{h''im}}."

  Returns:

  the deep-auto-quoted version of the parsed pattern string.

  See Also:

  MessageFormat.autoQuoteApostrophe(String)

  Status:

  Draft ICU 4.8.

  countParts

  public int countParts()

  Returns the number of "parts" created by parsing the pattern string. Returns 0 if no pattern has been parsed or clear() was called.

  Returns:

  the number of pattern parts.

  Status:

  Draft ICU 4.8.

  getPart

  public MessagePattern.Part getPart(int i)

  Gets the i-th pattern "part".

  Parameters:

  i - The index of the Part data. (0..countParts()-1)

  Returns:

  the i-th pattern "part".

  Throws:

  IndexOutOfBoundsException - if i is outside the (0..countParts()-1) range

  Status:

  Draft ICU 4.8.

  getPartType

  public MessagePattern.Part.Type getPartType(int i)

  Returns the Part.Type of the i-th pattern "part". Convenience method for getPart(i).getType().

  Parameters:

  i - The index of the Part data. (0..countParts()-1)

  Returns:

  The Part.Type of the i-th Part.

  Throws:

  IndexOutOfBoundsException - if i is outside the (0..countParts()-1) range

  Status:

  Draft ICU 4.8.

  getPatternIndex

  public int getPatternIndex(int partIndex)

  Returns the pattern index of the specified pattern "part". Convenience method for getPart(partIndex).getIndex().

  Parameters:

  partIndex - The index of the Part data. (0..countParts()-1)

  Returns:

  The pattern index of this Part.

  Throws:

  IndexOutOfBoundsException - if partIndex is outside the (0..countParts()-1) range

  Status:

  Draft ICU 4.8.

  getSubstring

  public String getSubstring(MessagePattern.Part part)

  Returns the substring of the pattern string indicated by the Part. Convenience method for getPatternString().substring(part.getIndex(), part.getLimit()).

  Parameters:

  part - a part of this MessagePattern.

  Returns:

  the substring associated with part.

  Status:

  Draft ICU 4.8.

  partSubstringMatches

  public boolean partSubstringMatches(MessagePattern.Part part,
                                      String s)

  Compares the part's substring with the input string s.

  Parameters:

  part - a part of this MessagePattern.

  s - a string.

  Returns:

  true if getSubstring(part).equals(s).

  Status:

  Draft ICU 4.8.

  getNumericValue

  public double getNumericValue(MessagePattern.Part part)

  Returns the numeric value associated with an ARG_INT or ARG_DOUBLE.

  Parameters:

  part - a part of this MessagePattern.

  Returns:

  the part's numeric value, or NO_NUMERIC_VALUE if this is not a numeric part.

  Status:

  Draft ICU 4.8.

  getPluralOffset

  public double getPluralOffset(int pluralStart)

  Returns the "offset:" value of a PluralFormat argument, or 0 if none is specified.

  Parameters:

  pluralStart - the index of the first PluralFormat argument style part. (0..countParts()-1)

  Returns:

  the "offset:" value.

  Throws:

  IndexOutOfBoundsException - if pluralStart is outside the (0..countParts()-1) range

  Status:

  Draft ICU 4.8.

  getLimitPartIndex

  public int getLimitPartIndex(int start)

  Returns the index of the ARG|MSG_LIMIT part corresponding to the ARG|MSG_START at start.

  Parameters:

  start - The index of some Part data (0..countParts()-1); this Part should be of Type ARG_START or MSG_START.

  Returns:

  The first i>start where getPart(i).getType()==ARG|MSG_LIMIT at the same nesting level, or start itself if getPartType(msgStart)!=ARG|MSG_START.

  Throws:

  IndexOutOfBoundsException - if start is outside the (0..countParts()-1) range

  Status:

  Draft ICU 4.8.

  clone

  public Object clone()

  Creates and returns a copy of this object.

  Overrides:

  clone in class Object

  Returns:

  a copy of this object (or itself if frozen).

  Status:

  Draft ICU 4.8.

  cloneAsThawed

  public MessagePattern cloneAsThawed()

  Creates and returns an unfrozen copy of this object.

  Specified by:

  cloneAsThawed in interface Freezable<MessagePattern>

  Returns:

  a copy of this object.

  Status:

  Draft ICU 4.8.

  freeze

  public MessagePattern freeze()

  Freezes this object, making it immutable and thread-safe.

  Specified by:

  freeze in interface Freezable<MessagePattern>

  Returns:

  this

  Status:

  Draft ICU 4.8.

  isFrozen

  public boolean isFrozen()

  Determines whether this object is frozen (immutable) or not.

  Specified by:

  isFrozen in interface Freezable<MessagePattern>

  Returns:

  true if this object is frozen.

  Status:

  Draft ICU 4.8.