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