/**
 * Copyright 2007 The Apache Software Foundation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package net.paoding.analysis.knife;

/**
 * Knife規定如何分解字符串成詞語，并將分解成的詞語告知{@link Collector}接口。
 * <p>
 * 
 * @author Zhiliang Wang [qieqie.wang@gmail.com]
 * 
 * @see Collector
 * @see Paoding
 * @see CJKKnife
 * @see CombinatoricsKnife
 * @see NumberKnife
 * @see LetterKnife
 * 
 * @since 1.0
 * 
 */
public interface Knife {

	/**
	 * 表征 {@link #assignable(Beef beef, int offset, int indec)}對index位置字符的性質規定。
	 * ASSIGNED性質的字符表示該字符可以被Knife接受進行分詞。
	 * <p>
	 * {@link KnifeBox}據此將一段由這種性質字符開始的內容(由beef和offset封裝)交給Knife分解。
	 * <p>
	 * 同樣的一段內容的一個位置的字符，對不同的Knife來說，往往具有不同的性質結果。
	 * <P>
	 * 
	 * @see KnifeBox#dissect(Collector, Beef, int)
	 */
	int ASSIGNED = 1;

	/**
	 * 表征 {@link #assignable(Beef beef, int offset, int indec)}對index位置字符的性質規定。
	 * POINT性質的字符表示如果給定分解的內容之前存在ASSIGNED性質的字符時，該字符可以被Knife接受進行分詞。
	 * <P>
	 * {@link KnifeBox}不關心給定的文本內容是否包含POINT性質的字符。<br>
	 * 這種性質的字符的最大關心者是{@link Knife}本身。
	 * 一般情況下，如果存在POINT性質的字符，下一個合適的Knife將從第一個這樣性質的字符開始分解內容<br>
	 * (這僅是一般的情況，具體是由{@link #dissect(Collector, Beef, int)}來確定)。
	 * <p>
	 * 同樣的一段內容的一個位置的字符，對不同的Knife來說，往往具有不同的性質結果。
	 * <P>
	 */
	int POINT = 0;

	/**
	 * 表征 {@link #assignable(Beef beef, int offset, int indec)}對index位置字符的性質規定。
	 * LIMIT性質的字符表示給定的字符不屬于此Knife的分解范疇。本Knife分解應該到此為止。 <br>
	 * 一般情況下，如果不存在POINT性質的字符，下一個合適的Knife將從這樣性質的字符開始分解內容<br>
	 * (這僅是一般的情況，具體是由{@link #dissect(Collector, Beef, int)}來確定)。
	 * <p>
	 * 同樣的一段內容的一個位置的字符，對不同的Knife來說，往往具有不同的性質結果。
	 * <P>
	 */
	int LIMIT = -1;

	/**
	 * 返回beef的index位置字符的性質，{@link KnifeBox}據此決定將一段文本內容“交給”一個合適的Knife切詞
	 * 
	 * @param beef
	 *            要被分詞的字符串
	 * @param offset
	 *            Knife開始或有可能開始切詞的始發位置。
	 * @param index
	 *            被判斷的字符的位置，本方法返回的即時該位置字符的性質。index>=offset。<br>
	 *            當{@link KnifeBox}根據字符的性質(是否為{@link #ASSIGNED})選擇Knife分解時，index=offset。
	 * @return index位置的字符在本Knife中的性質規定 <br>
	 *         當offset==index時，僅當返回ASSIGNED時，該Knife才有機會被{@link KnifeBox}分配接收文本內容進行分詞<br>
	 *         (即才有機會調用dissect方法)
	 * @see #LIMIT
	 * @see #ASSIGNED
	 * @see #POINT
	 */
	public int assignable(Beef beef, int offset, int index);

	/**
	 * 分解詞語，并將分解成的詞語相關信息告知{@link Collector}接口。
	 * <p>
	 * 分解從beef的offset位置開始，直至可能的結束的位置，結束時返回具有特定意義的一個非0數字。<br>
	 * 
	 * @param collector
	 *            當分解到詞語時，collector將被通知接收該詞語
	 * @param beef
	 *            待分解的字符串內容，這個字符串可能是所要分解的全部字符串的一部分(比如文章中的某一部分)，當beef的最后一個字符為'\0'時，表示此次分解是文章最后一段。
	 * @param offset
	 *            此次分解從beef的offset位置開始，即本此分解只需從beef.charAt(offset)開始
	 * @return 非0的整數，即正整數或負整數。<br>
	 *         正數時：表示此次分解到該結束位置(不包括該邊界)，即此次成功分解了從offset到該位置的文本流。<br>
	 *         特別地，當其>=beef.lenght()表示已經把beef所有的詞語分解完畢<br>
	 *         如果，當其==offset時，表示{@link KnifeBox}應該繼續遍歷還未遍歷的Knife，確定是否有其他Knife接收分解offset位置開始的文本內容<br>
	 *         <p>
	 *         負數時：該負數的絕對值必須>=offset。這個絕對值表示此次成功分解了從offset到該絕對值的文本流，剩下的字符，該knife已經不能正確解析。(一般此時應該重新傳入新的beef對象解析)
	 *         <p>
	 *         比如，有內容為"hello yang!"的文章，先讀入8個字符"hello ya"，<br>
	 *         此時分解后應該返回-5，表示正確解析到5這個位置，即"hello"，但必須讀入新的字符然后再繼續解析。
	 *         此時beef構造者就讀入剩下的字符"ng!"并與前次剩下的" ya"<br>
	 *         構成串" yang!"，這樣才能繼續解析，從而解析出"yang"!
	 * 
	 * 
	 */
	public int dissect(Collector collector, Beef beef, int offset);
}