net.paoding.analysis.knife.Knife Maven / Gradle / Ivy
/**
* 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}接口。
*
*
* @author Zhiliang Wang [[email protected]]
*
* @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接受进行分词。
*
* {@link KnifeBox}据此将一段由这种性质字符开始的内容(由beef和offset封装)交给Knife分解。
*
* 同样的一段内容的一个位置的字符，对不同的Knife来说，往往具有不同的性质结果。
*
*
* @see KnifeBox#dissect(Collector, Beef, int)
*/
int ASSIGNED = 1;
/**
* 表征 {@link #assignable(Beef beef, int offset, int indec)}对index位置字符的性质规定。
* POINT性质的字符表示如果给定分解的内容之前存在ASSIGNED性质的字符时，该字符可以被Knife接受进行分词。
*
* {@link KnifeBox}不关心给定的文本内容是否包含POINT性质的字符。
* 这种性质的字符的最大关心者是{@link Knife}本身。
* 一般情况下，如果存在POINT性质的字符，下一个合适的Knife将从第一个这样性质的字符开始分解内容
* (这仅是一般的情况，具体是由{@link #dissect(Collector, Beef, int)}来确定)。
*
* 同样的一段内容的一个位置的字符，对不同的Knife来说，往往具有不同的性质结果。
*
*/
int POINT = 0;
/**
* 表征 {@link #assignable(Beef beef, int offset, int indec)}对index位置字符的性质规定。
* LIMIT性质的字符表示给定的字符不属于此Knife的分解范畴。本Knife分解应该到此为止。
* 一般情况下，如果不存在POINT性质的字符，下一个合适的Knife将从这样性质的字符开始分解内容
* (这仅是一般的情况，具体是由{@link #dissect(Collector, Beef, int)}来确定)。
*
* 同样的一段内容的一个位置的字符，对不同的Knife来说，往往具有不同的性质结果。
*
*/
int LIMIT = -1;
/**
* 返回beef的index位置字符的性质，{@link KnifeBox}据此决定将一段文本内容“交给”一个合适的Knife切词
*
* @param beef
* 要被分词的字符串
* @param offset
* Knife开始或有可能开始切词的始发位置。
* @param index
* 被判断的字符的位置，本方法返回的即时该位置字符的性质。index>=offset。
* 当{@link KnifeBox}根据字符的性质(是否为{@link #ASSIGNED})选择Knife分解时，index=offset。
* @return index位置的字符在本Knife中的性质规定
* 当offset==index时，仅当返回ASSIGNED时，该Knife才有机会被{@link KnifeBox}分配接收文本内容进行分词
* (即才有机会调用dissect方法)
* @see #LIMIT
* @see #ASSIGNED
* @see #POINT
*/
public int assignable(Beef beef, int offset, int index);
/**
* 分解词语，并将分解成的词语相关信息告知{@link Collector}接口。
*
* 分解从beef的offset位置开始，直至可能的结束的位置，结束时返回具有特定意义的一个非0数字。
*
* @param collector
* 当分解到词语时，collector将被通知接收该词语
* @param beef
* 待分解的字符串内容，这个字符串可能是所要分解的全部字符串的一部分(比如文章中的某一部分)，当beef的最后一个字符为'\0'时，表示此次分解是文章最后一段。
* @param offset
* 此次分解从beef的offset位置开始，即本此分解只需从beef.charAt(offset)开始
* @return 非0的整数，即正整数或负整数。
* 正数时：表示此次分解到该结束位置(不包括该边界)，即此次成功分解了从offset到该位置的文本流。
* 特别地，当其>=beef.lenght()表示已经把beef所有的词语分解完毕
* 如果，当其==offset时，表示{@link KnifeBox}应该继续遍历还未遍历的Knife，确定是否有其他Knife接收分解offset位置开始的文本内容
*
* 负数时：该负数的绝对值必须>=offset。这个绝对值表示此次成功分解了从offset到该绝对值的文本流，剩下的字符，该knife已经不能正确解析。(一般此时应该重新传入新的beef对象解析)
*
* 比如，有内容为"hello yang!"的文章，先读入8个字符"hello ya"，
* 此时分解后应该返回-5，表示正确解析到5这个位置，即"hello"，但必须读入新的字符然后再继续解析。
* 此时beef构造者就读入剩下的字符"ng!"并与前次剩下的" ya"
* 构成串" yang!"，这样才能继续解析，从而解析出"yang"!
*
*
*/
public int dissect(Collector collector, Beef beef, int offset);
}