1 // 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html#License 3 /* 4 ******************************************************************************* 5 * Copyright (C) 1996-2005, International Business Machines Corporation and * 6 * others. All Rights Reserved. * 7 ******************************************************************************* 8 */ 9 package com.ibm.icu.text; 10 import java.text.ParsePosition; 11 12 /** 13 * An interface that defines both lookup protocol and parsing of 14 * symbolic names. 15 * 16 * <p>This interface is used by UnicodeSet to resolve $Variable style 17 * references that appear in set patterns. RBBI and Transliteration 18 * both independently implement this interface. 19 * 20 * <p>A symbol table maintains two kinds of mappings. The first is 21 * between symbolic names and their values. For example, if the 22 * variable with the name "start" is set to the value "alpha" 23 * (perhaps, though not necessarily, through an expression such as 24 * "$start=alpha"), then the call lookup("start") will return the 25 * char[] array ['a', 'l', 'p', 'h', 'a']. 26 * 27 * <p>The second kind of mapping is between character values and 28 * UnicodeMatcher objects. This is used by RuleBasedTransliterator, 29 * which uses characters in the private use area to represent objects 30 * such as UnicodeSets. If U+E015 is mapped to the UnicodeSet [a-z], 31 * then lookupMatcher(0xE015) will return the UnicodeSet [a-z]. 32 * 33 * <p>Finally, a symbol table defines parsing behavior for symbolic 34 * names. All symbolic names start with the SYMBOL_REF character. 35 * When a parser encounters this character, it calls parseReference() 36 * with the position immediately following the SYMBOL_REF. The symbol 37 * table parses the name, if there is one, and returns it. 38 * 39 * @stable ICU 2.8 40 */ 41 public interface SymbolTable { 42 43 /** 44 * The character preceding a symbol reference name. 45 * @stable ICU 2.8 46 */ 47 static final char SYMBOL_REF = '$'; 48 49 /** 50 * Lookup the characters associated with this string and return it. 51 * Return <tt>null</tt> if no such name exists. The resultant 52 * array may have length zero. 53 * @param s the symbolic name to lookup 54 * @return a char array containing the name's value, or null if 55 * there is no mapping for s. 56 * @stable ICU 2.8 57 */ 58 char[] lookup(String s); 59 60 /** 61 * Lookup the UnicodeMatcher associated with the given character, and 62 * return it. Return <tt>null</tt> if not found. 63 * @param ch a 32-bit code point from 0 to 0x10FFFF inclusive. 64 * @return the UnicodeMatcher object represented by the given 65 * character, or null if there is no mapping for ch. 66 * @stable ICU 2.8 67 */ 68 UnicodeMatcher lookupMatcher(int ch); 69 70 /** 71 * Parse a symbol reference name from the given string, starting 72 * at the given position. If no valid symbol reference name is 73 * found, return null and leave pos unchanged. That is, if the 74 * character at pos cannot start a name, or if pos is at or after 75 * text.length(), then return null. This indicates an isolated 76 * SYMBOL_REF character. 77 * @param text the text to parse for the name 78 * @param pos on entry, the index of the first character to parse. 79 * This is the character following the SYMBOL_REF character. On 80 * exit, the index after the last parsed character. If the parse 81 * failed, pos is unchanged on exit. 82 * @param limit the index after the last character to be parsed. 83 * @return the parsed name, or null if there is no valid symbolic 84 * name at the given position. 85 * @stable ICU 2.8 86 */ 87 String parseReference(String text, ParsePosition pos, int limit); 88 } 89