001/**
002 * Portions Copyright 2001 Sun Microsystems, Inc.
003 * Portions Copyright 1999-2001 Language Technologies Institute, 
004 * Carnegie Mellon University.
005 * All Rights Reserved.  Use is subject to license terms.
006 * 
007 * See the file "license.terms" for information on usage and
008 * redistribution of this file, and for a DISCLAIMER OF ALL 
009 * WARRANTIES.
010 */
011package com.sun.speech.freetts.lexicon;
012
013import java.util.List;
014import java.io.IOException;
015
016/**
017 * Provides the phone list for words.  A Lexicon is composed of three
018 * pieces:  an addenda, the compiled form, and the letter to sound
019 * rules.
020 * <ul>
021 *   <li>The addenda either contains Word instances that are not in
022 *   the compiled form, or it contains Word instances that replace
023 *   definitions in the compiled form.  The addenda is meant to be
024 *   relatively small (e.g., 10's of words).
025 *   <li>The compiled form is meant to hold a large number of words
026 *   (e.g., 10's of thousands of words) and provide a very efficient
027 *   means for finding those words.
028 *   <li>The letter to sound rules will attempt to find a definition for
029 *   a word not found in either the addenda or compiled form.
030 * </ul>
031 */
032public interface Lexicon {
033    /**
034     * Gets the phone list for a given word.  If a phone list cannot
035     * be found, <code>null</code> is returned.  The
036     * <code>partOfSpeech</code> is implementation dependent, but
037     * <code>null</code> always matches.
038     *
039     * @param word the word to find
040     * @param partOfSpeech the part of speech or <code>null</code>
041     *
042     * @return the list of phones for word or null
043     */
044    public String[] getPhones(String word, String partOfSpeech);
045
046    /**
047     * Gets the phone list for a given word.  If a phone list cannot
048     * be found, <code>null</code> is returned.  The
049     * <code>partOfSpeech</code> is implementation dependent, but
050     * <code>null</code> always matches.
051     *
052     * @param word the word to find
053     * @param partOfSpeech the part of speech or <code>null</code>
054     * @param useLTS whether to use the letter-to-sound rules when
055     *        the word is not in the lexicon.
056     *
057     * @return the list of phones for word or null
058     */    
059    public String[] getPhones(String word, String partOfSpeech, boolean useLTS);
060
061    /**
062     * Adds a word to the addenda.  The
063     * part of speech is implementation dependent.
064     *
065     * @param word the word to add
066     * @param partOfSpeech the part of speech or <code>null</code>
067     * 
068     */
069    public void addAddendum(String word, String partOfSpeech, String[] phones);
070
071    /**
072     * Removes a word from the addenda.  Both the part of speech and
073     * word must be an exact match.
074     *
075     * @param word the word to add
076     * @param partOfSpeech the part of speech
077     */
078    public void removeAddendum(String word, String partOfSpeech);
079
080    /**
081     * Determines if the <code>currentWordPhone</code> represents a
082     * new syllable boundary.
083     *
084     * @param syllablePhones the phones in the current syllable so far
085     * @param wordPhones the phones for the whole word
086     * @param currentWordPhone the word phone in question
087     *
088     * @return <code>true</code> if the phone is a new boundary
089     */
090    public boolean isSyllableBoundary(List syllablePhones,
091                                      String[] wordPhones,
092                                      int currentWordPhone);    
093
094    /**
095     * Loads this lexicon.  The loading of a lexicon need not be done
096     * in the constructor.
097     *
098     * @throws IOException if an error occurs while loading
099     */
100    public void load() throws IOException;
101
102
103    /**
104     * Determines if this lexicon is loaded.
105     *
106     * @return <code>true</code> if the lexicon is loaded
107     */
108    public boolean isLoaded();
109}