SCWS - PHP 扩展之文档

==运行时配置==



scws.default.charset  (default = gbk) , Changeable = PHP_INI_ALL

scws.default.fpath (default = NULL) , Changeable = PHP_INI_ALL

有关 PHP_INI_* 常量进一步的细节与定义参见PHP手册。



==资源类型==



本扩展定义了一种资源类型：一个 scws 指针，指向正在被操作的 scws 对象。



==预定义常量==



本扩展模块未定义任何常量。



==预定义类==



这是一个类似 Directory 的内置式伪类操作，类方法建立请使用 scws_new() 函数，

而不要直接用 new SimpledCWS。否则不会包含有 handle 指针，将无法正确操作。

包含的方法有：

class SimpledCWS  {

  resource handle;

  bool close(void);

  bool set_charset(string charset)

  bool set_dict(string dict_path)

  bool set_rule(string rule_path)

  bool set_ignore(bool yes)

  bool set_multi(int mode)

  bool set_duality(bool yes)

  bool send_text(string text)

  mixed get_result(void)

  mixed get_tops([int limit [, string xattr]])

  bool has_word(string xattr)

  mixed get_words(string xattr)

  string version(void)

};  



例子1. 使用类方法分词

<?php

$so = scws_new();

$so->set_charset('gbk');

// 这里没有调用 set_dict 和 set_rule 系统会自动试调用 ini 中指定路径下的词典和规则文件

$so->send_text("我是一个中国人,我会C++语言,我也有很多T恤衣服");

while ($tmp = $so->get_result())

{

  print_r($tmp);

}

$so->close();

?>



例子2. 使用函数提取高频词

<?php

$sh = scws_open();

scws_set_charset($sh, 'gbk');

scws_set_dict($sh, '/path/to/dict.xdb');

scws_set_rule($sh, '/path/to/rules.ini');

$text = "我是一个中国人，我会C++语言，我也有很多T恤衣服";

scws_send_text($sh, $text);

$top = scws_get_tops($sh, 5);

print_r($top);

?>



注意：

为方便使用，当 send_text 方法或 scws_send_text 函数被调用前，没有加载词典和规则集时，

系统会自动在scws.default.fpath(ini配置)中查找相应的字符集词典。词典和规则文件的命名

方式为 dict[.字符集].xdb 和 rules[.字符集].ini ，当字符集是 gbk 时中括号里面的部分则

不需要，直接使用 dict.xdb 和 rules.ini 而不是 dict.gbk.xdb 。



此外，输入的文字，词典，规则文件这三者的字符集必须统一，如果不是默认的 gbk 字符集

请调用 set_charset 或 scws_set_charset来设定，否则可能出现意外错误。



==函数列表：==



mixed scws_new(void)

说明：创建并返回一个 SimpledCWS 类操作对象。

参数：无

返回值：成功返回类操作句柄，失败返回 false



mixed scws_open(void)

说明：创建并返回一个分词操作句柄

参数：无

返回值：成功返回 scws 操作句柄，失败返回 false



bool scws_close(resource scws_handle)

说明：关闭一个已打开的 scws 分词操作句柄

返回：始终为 true

参数：scws_handle 即之前由 scws_open 打开返回的。



bool scws_set_charset(resource scws_handle, string charset)

说明：设定分词词典、规则集、欲分文本字符串的字符集，系统缺省是 gbk 字集。

返回：始终为 true

参数：scws_handle 即之前由 scws_open 打开返回的；

      charset 是要新设定的字符集，目前只支持 utf8 和 gbk。



bool scws_add_dict(resource scws_handle, string dict_path [, int mode])

说明：添加分词所用的词典，新加入的优先查找。

返回：成功返回 true 失败返回 false

参数：scws_handle 即之前由 scws_open 打开返回的；

         dict_path 是词典的路径，可以是相对路径或完全路径。（遵查安全模式下的open_basedir）

         mode 是可选参数，表示加载的方式，其值有三：SCWS_XDICT_XDB SCWS_XDICT_MEM SCWS_XDICT_TXT

              其中 SCWS_XDICT_TXT 表示文本词典，可结合另外2个值使用



bool scws_set_dict(resource scws_handle, string dict_path [, int mode])

说明：设定分词所用的词典并清除已存在的词典列表。

返回：成功返回 true 失败返回 false

参数：scws_handle 即之前由 scws_open 打开返回的；

         dict_path 是词典的路径，可以是相对路径或完全路径。（遵查安全模式下的open_basedir）

         mode 是可选参数，表示加载的方式，其值有三：SCWS_XDICT_XDB SCWS_XDICT_MEM SCWS_XDICT_TXT

              其中 SCWS_XDICT_TXT 表示文本词典，可结合另外2个值使用



bool scws_set_rule(resource scws_handle, string rule_path)

说明：设定分词所用的新词识别规则集（用于人名、地名、数字时间年代等识别）。

返回：成功返回 true 失败返回 false

参数：scws_handle 即之前由 scws_open 打开返回的；

      rule_path 是规则集的路径，可以是相对路径或完全路径。（遵查安全模式下的open_basedir）



bool scws_set_ignore(resource scws_handle, bool yes)

说明：设定分词返回结果时是否去除一些特殊的标点符号之类。

返回：始终为 true

参数：scws_handle 即之前由 scws_open 打开返回的；

      yes 设定值，如果为 true 则结果中不返回标点符号，如果为 false 则会返回，缺省为 false。



bool scws_set_multi(resource scws_handle, int mode)

说明：设定分词返回结果时是否复式分割，如“中国人”返回“中国＋人＋中国人”三个词。

返回：始终为 true

参数：scws_handle 即之前由 scws_open 打开返回的；

      mode 设定值，1~15。1|2|4|8 = short|duality|zmain|zall    

      按位与的 1 | 2 | 4 | 8 分别表示: 短词 | 二元 | 主要单字 | 所有单字

	  1.1.1 起 1,2,4,8 分别对应常量 SCWS_MULTI_SHORT  SCWS_MULTI_DUALITY SCWS_MULTI_ZMAIN SCWS_MULTI_ZALL



bool scws_set_duality(resource scws_handle, bool yes)

说明：设定是否将闲散文字自动以二字分词法聚合

返回：始终为 true

参数：scws_handle 即之前由 scws_open 打开返回的；

      yes 设定值，如果为 true 则结果中多个单字会自动按二分法聚分，如果为 false 则不处理，缺省为 false。



bool scws_send_text(resource scws_handle, string text)

说明：发送设定分词所要切割的文本

返回：成功返回 true 失败返回 false

参数：scws_handle 即之前由 scws_open 打开返回的；

      text 是文本的内容。

注1：系统底层处理方式为对该文本增加一个引用，故不论多长的文本并不会造成内存浪费；

注2：执行本函数时，若未加载任何词典和规则集，则会自动试图在ini指定的缺省目录下查找词典和规则集。



mixed scws_get_result(resource scws_handle)

说明：根据 send_text 设定的文本内容，返回一系列切好的词汇。

返回：成功返回切好的词汇组成的数组， 若无更多词汇，返回 false。

参数：scws_handle 即之前由 scws_open 打开返回的。



注1：每次切割后本函数应该循环调用，直到返回 false 为止，因为程序每次返回的词数是不确定的。

注2：返回的词汇包含的键值有：word (string, 词本身) idf (folat, 逆文本词频) 

                             off (long, 在文本中的位置) attr(string, 词性表示)



mixed scws_get_tops(resource scws_handle [, int limit [, string attr]] )

说明：根据 send_text 设定的文本内容，返回系统计算出来的最关键词汇列表。

返回：成功返回切好的词汇组成的数组， 若无更多词汇，返回 false。

参数：scws_handle 即之前由 scws_open 打开返回的；

      limit 可选参数，返回的词的最大数量，缺省是 10；

      attr 可选参数，是一系列词性组成的字符串，各词性之间以半角的逗号隔开，

      这表示返回的词性必须在列表中，如果以~开头，则表示取反，词性必须不在列表中，

      缺省为NULL，返回全部词性，不过滤。



mixed scws_get_words(resource scws_handle, string attr )

说明：根据 send_text 设定的文本内容，返回系统中词性符合要求的关键词汇。

返回：成功返回符合要求词汇组成的数组，返回 false。

参数：scws_handle 即之前由 scws_open 打开返回的；

        attr 是一系列词性组成的字符串，各词性之间以半角的逗号隔开，

        这表示返回的词性必须在列表中，如果以~开头，则表示取反，词性必须不在列表中，

        若为空则返回全部词性，不过滤。



bool scws_has_words(resource scws_handle, string attr )

说明：根据 send_text 设定的文本内容，返回系统中是否包括符合词性要求的关键词。

返回：如果有则返回 true，没有就返回 false。

参数：scws_handle 即之前由 scws_open 打开返回的；

        attr 是一系列词性组成的字符串，各词性之间以半角的逗号隔开，

        这表示要判断的词只要有一个符合词性要求就立即返回 true，

        若为空则只要 text 不为空就返回 true.



mixed scws_version(void)

说明：返回 scws 版本号名称信息。

返回：字符串

参数：无



类对象用法参照函数用法，区别就是不需要传入第一参数（会自动从handle的属性中取值）。