.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Estraier 3pm"
.TH Estraier 3pm "2014-08-15" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Estraier - Perl Binding of Hyper Estraier
.SH "SYNOPSYS"
.IX Header "SYNOPSYS"
.Vb 1
\&  use Estraier;
.Ve
.SH "INTRODUCTION"
.IX Header "INTRODUCTION"
Hyper Estraier is a full-text search system for communities.
.PP
This is a package implementing the core \s-1API\s0 of Hyper Estraier ( http://hyperestraier.sourceforge.net/ ), including native codes written in C with \s-1XS\s0 macros.  As it works on Linux, Mac \s-1OS X,\s0 Windows, and so on, native libraries for each environment are required to run programs.  This package requires Perl 5.8.8 or later versions.
.SS "Setting"
.IX Subsection "Setting"
Install the latest version of Hyper Estraier.
.PP
Enter the sub directory `perlnative' in the extracted package then perform installation.
.PP
.Vb 5
\&  cd perlnative
\&  ./configure
\&  make
\&  su
\&  make install
.Ve
.PP
On Linux and other \s-1UNIX\s0 systems: set the environment variable \s-1LD_LIBRARY_PATH\s0 to find libraries; \*(L"libestraier.so\*(R".  On Mac \s-1OS X:\s0 set the environment variable \s-1DYLD_LIBRARY_PATH\s0 to find libraries; \*(L"libestraier.dylib\*(R".  On Windows: set the environment variable \s-1PATH\s0 to find libraries; \*(L"estraier.dll\*(R".
.PP
The package `Estraier' should be loaded in each source file of application programs.
.PP
.Vb 1
\&  use Estraier;
.Ve
.PP
If you want to enable runtime assertion, set the variable `$Estraier::DEBUG' to be true.
.PP
.Vb 1
\&  $Estraier::DEBUG = 1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Class Document"
.IX Subsection "Class Document"
.ie n .IP "$doc = new Document(\fIdraft\fR)" 4
.el .IP "\f(CW$doc\fR = new Document(\fIdraft\fR)" 4
.IX Item "$doc = new Document(draft)"
Create a document object.  `draft' specifies a string of draft data.  If it is omitted, an empty document object is created.
.ie n .IP "$doc\->add_attr(\fIname\fR, \fIvalue\fR)" 4
.el .IP "\f(CW$doc\fR\->add_attr(\fIname\fR, \fIvalue\fR)" 4
.IX Item "$doc->add_attr(name, value)"
Add an attribute.  `name' specifies the name of an attribute.  `value' specifies the value of the attribute.  If it is `undef', the attribute is removed.  The return value is always `undef'.
.ie n .IP "$doc\->add_text(\fItext\fR)" 4
.el .IP "\f(CW$doc\fR\->add_text(\fItext\fR)" 4
.IX Item "$doc->add_text(text)"
Add a sentence of text.  `text' specifies a sentence of text.  The return value is always `undef'.
.ie n .IP "$doc\->add_hidden_text(\fItext\fR)" 4
.el .IP "\f(CW$doc\fR\->add_hidden_text(\fItext\fR)" 4
.IX Item "$doc->add_hidden_text(text)"
Add a hidden sentence.  `text' specifies a hidden sentence.  The return value is always `undef'.
.ie n .IP "$doc\->set_keywords(\fIkwords\fR)" 4
.el .IP "\f(CW$doc\fR\->set_keywords(\fIkwords\fR)" 4
.IX Item "$doc->set_keywords(kwords)"
Attach keywords.  `kwords' specifies the reference of a hash object of keywords.  Keys of the hash should be keywords of the document and values should be their scores in decimal string.  The return value is always `undef'.
.ie n .IP "$doc\->set_score(\fIscore\fR)" 4
.el .IP "\f(CW$doc\fR\->set_score(\fIscore\fR)" 4
.IX Item "$doc->set_score(score)"
Set the substitute score.  `score' specifies the substitute score.  It should be zero or positive.  The return value is always `undef'.
.ie n .IP "$doc\->\fIid()\fR" 4
.el .IP "\f(CW$doc\fR\->\fIid()\fR" 4
.IX Item "$doc->id()"
Get the \s-1ID\s0 number.  The return value is the \s-1ID\s0 number of the document object.  If the object has never been registered, \-1 is returned.
.ie n .IP "$doc\->\fIattr_names()\fR" 4
.el .IP "\f(CW$doc\fR\->\fIattr_names()\fR" 4
.IX Item "$doc->attr_names()"
Get an array of attribute names of a document object.  The return value is a reference of an array object of attribute names.
.ie n .IP "$doc\->\fIattr()\fR" 4
.el .IP "\f(CW$doc\fR\->\fIattr()\fR" 4
.IX Item "$doc->attr()"
Get the value of an attribute.  `name' specifies the name of an attribute.  The return value is the value of the attribute or `undef' if it does not exist.
.ie n .IP "$doc\->\fItexts()\fR" 4
.el .IP "\f(CW$doc\fR\->\fItexts()\fR" 4
.IX Item "$doc->texts()"
Get an array of sentences of the text.  The return value is a reference of an array object of sentences of the text.
.ie n .IP "$doc\->\fIcat_texts()\fR" 4
.el .IP "\f(CW$doc\fR\->\fIcat_texts()\fR" 4
.IX Item "$doc->cat_texts()"
Concatenate sentences of the text of a document object.  The return value is concatenated sentences.
.ie n .IP "$doc\->\fIkeywords()\fR" 4
.el .IP "\f(CW$doc\fR\->\fIkeywords()\fR" 4
.IX Item "$doc->keywords()"
Get attached keywords.  The return value is a reference of a hash object of keywords and their scores in decimal string.  If no keyword is attached, `undef' is returned.
.ie n .IP "$doc\->\fIscore()\fR" 4
.el .IP "\f(CW$doc\fR\->\fIscore()\fR" 4
.IX Item "$doc->score()"
Get the substitute score.  The return value is the substitute score or \-1 if it is not set.
.ie n .IP "$doc\->\fIdump_draft()\fR" 4
.el .IP "\f(CW$doc\fR\->\fIdump_draft()\fR" 4
.IX Item "$doc->dump_draft()"
Dump draft data of a document object.  The return value is draft data.
.ie n .IP "$doc\->make_snippet(\fIwords\fR, \fIwwidth\fR, \fIhwidth\fR, \fIawidth\fR)" 4
.el .IP "\f(CW$doc\fR\->make_snippet(\fIwords\fR, \fIwwidth\fR, \fIhwidth\fR, \fIawidth\fR)" 4
.IX Item "$doc->make_snippet(words, wwidth, hwidth, awidth)"
Make a snippet of the body text.  `words' specifies a reference of an array object of words to be highlight.  `wwidth' specifies whole width of the result.  `hwidth' specifies width of strings picked up from the beginning of the text.  `awidth' width of strings picked up around each highlighted word.  The return value is a snippet string of the body text.  There are tab separated values.  Each line is a string to be shown.  Though most lines have only one field, some lines have two fields.  If the second field exists, the first field is to be shown with highlighted, and the second field means its normalized form.
.SS "Class Condition"
.IX Subsection "Class Condition"
.IP "Condition::SURE = 1 << 0" 4
.IX Item "Condition::SURE = 1 << 0"
option: check every N\-gram key
.IP "Condition::USUAL = 1 << 1" 4
.IX Item "Condition::USUAL = 1 << 1"
option: check N\-gram keys skipping by one
.IP "Condition::FAST = 1 << 2" 4
.IX Item "Condition::FAST = 1 << 2"
option: check N\-gram keys skipping by two
.IP "Condition::AGITO = 1 << 3" 4
.IX Item "Condition::AGITO = 1 << 3"
option: check N\-gram keys skipping by three
.IP "Condition::NOIDF = 1 << 4" 4
.IX Item "Condition::NOIDF = 1 << 4"
option: without TF-IDF tuning
.IP "Condition::SIMPLE = 1 << 10" 4
.IX Item "Condition::SIMPLE = 1 << 10"
option: with the simplified phrase
.IP "Condition::ROUGH = 1 << 11" 4
.IX Item "Condition::ROUGH = 1 << 11"
option: with the rough phrase
.IP "Condition::UNION = 1 << 15" 4
.IX Item "Condition::UNION = 1 << 15"
option: with the union phrase
.IP "Condition::ISECT = 1 << 16" 4
.IX Item "Condition::ISECT = 1 << 16"
option: with the intersection phrase
.IP "Condition::ECLSIMURL = 10.0" 4
.IX Item "Condition::ECLSIMURL = 10.0"
eclipse tuning: consider \s-1URL\s0
.IP "Condition::ECLSERV = 100.0" 4
.IX Item "Condition::ECLSERV = 100.0"
eclipse tuning: on server basis
.IP "Condition::ECLDIR = 101.0" 4
.IX Item "Condition::ECLDIR = 101.0"
eclipse tuning: on directory basis
.IP "Condition::ECLFILE = 102.0" 4
.IX Item "Condition::ECLFILE = 102.0"
eclipse tuning: on file basis
.ie n .IP "$cond = new \fICondition()\fR" 4
.el .IP "\f(CW$cond\fR = new \fICondition()\fR" 4
.IX Item "$cond = new Condition()"
Create a search condition object.
.ie n .IP "$cond\->set_phrase(\fIphrase\fR)" 4
.el .IP "\f(CW$cond\fR\->set_phrase(\fIphrase\fR)" 4
.IX Item "$cond->set_phrase(phrase)"
Set the search phrase.  `phrase' specifies a search phrase.  The return value is always `undef'.
.ie n .IP "$cond\->add_attr(\fIexpr\fR)" 4
.el .IP "\f(CW$cond\fR\->add_attr(\fIexpr\fR)" 4
.IX Item "$cond->add_attr(expr)"
Add an expression for an attribute.  `expr' specifies an expression for an attribute.  The return value is always `undef'.
.ie n .IP "$cond\->set_order(\fIexpr\fR)" 4
.el .IP "\f(CW$cond\fR\->set_order(\fIexpr\fR)" 4
.IX Item "$cond->set_order(expr)"
Set the order of a condition object.  `expr' specifies an expression for the order.  By default, the order is by score descending.  The return value is always `undef'.
.ie n .IP "$cond\->set_max(\fImax\fR)" 4
.el .IP "\f(CW$cond\fR\->set_max(\fImax\fR)" 4
.IX Item "$cond->set_max(max)"
Set the maximum number of retrieval.  `max' specifies the maximum number of retrieval.  By default, the number of retrieval is not limited.
.ie n .IP "$cond\->set_skip(\fIskip\fR)" 4
.el .IP "\f(CW$cond\fR\->set_skip(\fIskip\fR)" 4
.IX Item "$cond->set_skip(skip)"
Set the number of skipped documents.  `skip' specifies the number of documents to be skipped in the search result.  The return value is always `undef'.
.ie n .IP "$cond\->set_options(\fIoptions\fR)" 4
.el .IP "\f(CW$cond\fR\->set_options(\fIoptions\fR)" 4
.IX Item "$cond->set_options(options)"
Set options of retrieval.  `options' specifies options: `Condition::SURE' specifies that it checks every N\-gram key, `Condition::USU', which is the default, specifies that it checks N\-gram keys with skipping one key, `Condition::FAST' skips two keys, `Condition::AGITO' skips three keys, `Condition::NOIDF' specifies not to perform TF-IDF tuning, `Condition::SIMPLE' specifies to use simplified phrase, `Condition::ROUGH' specifies to use rough phrase, `Condition::UNION' specifies to use union phrase, `Condition::ISECT' specifies to use intersection phrase.  Each option can be specified at the same time by bitwise or.  If keys are skipped, though search speed is improved, the relevance ratio grows less.  The return value is always `undef'.
.ie n .IP "$cond\->set_auxiliary(\fImin\fR)" 4
.el .IP "\f(CW$cond\fR\->set_auxiliary(\fImin\fR)" 4
.IX Item "$cond->set_auxiliary(min)"
Set permission to adopt result of the auxiliary index.  `min' specifies the minimum hits to adopt result of the auxiliary index.  If it is not more than 0, the auxiliary index is not used.  By default, it is 32.
.ie n .IP "$cond\->set_eclipse(\fIlimit\fR)" 4
.el .IP "\f(CW$cond\fR\->set_eclipse(\fIlimit\fR)" 4
.IX Item "$cond->set_eclipse(limit)"
Set the lower limit of similarity eclipse.  `limit' specifies the lower limit of similarity for documents to be eclipsed.  Similarity is between 0.0 and 1.0.  If the limit is added by `Condition::ECLSIMURL', similarity is weighted by \s-1URL. \s0 If the limit is `Condition::ECLSERV', similarity is ignored and documents in the same server are eclipsed.  If the limit is `Condition::ECLDIR', similarity is ignored and documents in the same directory are eclipsed.  If the limit is `Condition::ECLFILE', similarity is ignored and documents of the same file are eclipsed.
.ie n .IP "$cond\->set_distinct(\fIname\fR)" 4
.el .IP "\f(CW$cond\fR\->set_distinct(\fIname\fR)" 4
.IX Item "$cond->set_distinct(name)"
Set the attribute distinction filter.  `name' specifies the name of an attribute to be distinct.  The return value is always `undef'.
.SS "Class Result"
.IX Subsection "Class Result"
.ie n .IP "$result\->\fIdoc_num()\fR" 4
.el .IP "\f(CW$result\fR\->\fIdoc_num()\fR" 4
.IX Item "$result->doc_num()"
Get the number of documents.  The return value is the number of documents in the result.
.ie n .IP "$result\->get_doc_id(\fIindex\fR)" 4
.el .IP "\f(CW$result\fR\->get_doc_id(\fIindex\fR)" 4
.IX Item "$result->get_doc_id(index)"
Get the \s-1ID\s0 number of a document.  `index' specifies the index of a document.  The return value is the \s-1ID\s0 number of the document or \-1 if the index is out of bounds.
.ie n .IP "$result\->get_dbidx(\fIindex\fR)" 4
.el .IP "\f(CW$result\fR\->get_dbidx(\fIindex\fR)" 4
.IX Item "$result->get_dbidx(index)"
Get the index of the container database of a document.  `index' specifies the index of a document.  The return value is the index of the container database of the document or \-1 if the index is out of bounds.
.ie n .IP "$result\->\fIhint_words()\fR" 4
.el .IP "\f(CW$result\fR\->\fIhint_words()\fR" 4
.IX Item "$result->hint_words()"
Get an array of hint words.  The return value is a reference of an array of hint words.
.ie n .IP "$result\->hint(\fIword\fR)" 4
.el .IP "\f(CW$result\fR\->hint(\fIword\fR)" 4
.IX Item "$result->hint(word)"
Get the value of a hint word.  `word' specifies a hint word.  An empty string means the number of whole result.  The return value is the number of documents corresponding the hint word.  If the word is in a negative condition, the value is negative.
.ie n .IP "$result\->get_score(\fIindex\fR)" 4
.el .IP "\f(CW$result\fR\->get_score(\fIindex\fR)" 4
.IX Item "$result->get_score(index)"
Get the score of a document.  `index' specifies the index of a document.  The return value is the score of the document or \-1 if the index is out of bounds.
.ie n .IP "$result\->get_shadows(\fIid\fR)" 4
.el .IP "\f(CW$result\fR\->get_shadows(\fIid\fR)" 4
.IX Item "$result->get_shadows(id)"
Get an array of \s-1ID\s0 numbers of eclipsed docuemnts of a document.  `id' specifies the \s-1ID\s0 number of a parent document.  The return value is a reference of an array whose elements expresse the \s-1ID\s0 numbers and their scores alternately.
.SS "Class Database"
.IX Subsection "Class Database"
.ie n .IP "Database::VERSION = ""0.0.0""" 4
.el .IP "Database::VERSION = ``0.0.0''" 4
.IX Item "Database::VERSION = 0.0.0"
version of Hyper Estraier
.IP "Database::ERRNOERR = 0" 4
.IX Item "Database::ERRNOERR = 0"
error code: no error
.IP "Database::ERRINVAL = 1" 4
.IX Item "Database::ERRINVAL = 1"
error code: invalid argument
.IP "Database::ERRACCES = 2" 4
.IX Item "Database::ERRACCES = 2"
error code: access forbidden
.IP "Database::ERRLOCK = 3" 4
.IX Item "Database::ERRLOCK = 3"
error code: lock failure
.IP "Database::ERRDB = 4" 4
.IX Item "Database::ERRDB = 4"
error code: database problem
.IP "Database::ERRIO = 5" 4
.IX Item "Database::ERRIO = 5"
error code: I/O problem
.IP "Database::ERRNOITEM = 6" 4
.IX Item "Database::ERRNOITEM = 6"
error code: no item
.IP "Database::ERRMISC = 9999" 4
.IX Item "Database::ERRMISC = 9999"
error code: miscellaneous
.IP "Database::DBREADER = 1 << 0" 4
.IX Item "Database::DBREADER = 1 << 0"
open mode: open as a reader
.IP "Database::DBWRITER = 1 << 1" 4
.IX Item "Database::DBWRITER = 1 << 1"
open mode: open as a writer
.IP "Database::DBCREAT = 1 << 2" 4
.IX Item "Database::DBCREAT = 1 << 2"
open mode: a writer creating
.IP "Database::DBTRUNC = 1 << 3" 4
.IX Item "Database::DBTRUNC = 1 << 3"
open mode: a writer truncating
.IP "Database::DBNOLCK = 1 << 4" 4
.IX Item "Database::DBNOLCK = 1 << 4"
open mode: open without locking
.IP "Database::DBLCKNB = 1 << 5" 4
.IX Item "Database::DBLCKNB = 1 << 5"
open mode: lock without blocking
.IP "Database::DBPERFNG = 1 << 10" 4
.IX Item "Database::DBPERFNG = 1 << 10"
open mode: use perfect N\-gram analyzer
.IP "Database::DBCHRCAT = 1 << 11" 4
.IX Item "Database::DBCHRCAT = 1 << 11"
open mode: use character category analyzer
.IP "Database::DBSMALL= 1 << 20" 4
.IX Item "Database::DBSMALL= 1 << 20"
open mode: small tuning
.IP "Database::DBLARGE = 1 << 21" 4
.IX Item "Database::DBLARGE = 1 << 21"
open mode: large tuning
.IP "Database::DBHUGE = 1 << 22" 4
.IX Item "Database::DBHUGE = 1 << 22"
open mode: huge tuning
.IP "Database::DBHUGE2 = 1 << 23" 4
.IX Item "Database::DBHUGE2 = 1 << 23"
open mode: huge tuning second
.IP "Database::DBHUGE3 = 1 << 24" 4
.IX Item "Database::DBHUGE3 = 1 << 24"
open mode: huge tuning third
.IP "Database::DBSCVOID = 1 << 25" 4
.IX Item "Database::DBSCVOID = 1 << 25"
open mode: store scores as void
.IP "Database::DBSCINT = 1 << 26" 4
.IX Item "Database::DBSCINT = 1 << 26"
open mode: store scores as integer
.IP "Database::DBSCASIS = 1 << 27" 4
.IX Item "Database::DBSCASIS = 1 << 27"
open mode: refrain from adjustment of scores
.IP "Database::IDXATTRSEQ = 0" 4
.IX Item "Database::IDXATTRSEQ = 0"
attribute index type: for multipurpose sequential access method
.IP "Database::IDXATTRSTR = 1" 4
.IX Item "Database::IDXATTRSTR = 1"
attribute index type: for narrowing with attributes as strings
.IP "Database::IDXATTRNUM = 2" 4
.IX Item "Database::IDXATTRNUM = 2"
attribute index type: for narrowing with attributes as numbers
.IP "Database::OPTNOPURGE = 1 << 0" 4
.IX Item "Database::OPTNOPURGE = 1 << 0"
optimize option: omit purging dispensable region of deleted
.IP "Database::OPTNODBOPT = 1 << 1" 4
.IX Item "Database::OPTNODBOPT = 1 << 1"
optimize option: omit optimization of the database files
.IP "Database::MGCLEAN = 1 << 0" 4
.IX Item "Database::MGCLEAN = 1 << 0"
merge option: clean up dispensable regions
.IP "Database::PDCLEAN = 1 << 0" 4
.IX Item "Database::PDCLEAN = 1 << 0"
put_doc option: clean up dispensable regions
.IP "Database::PDWEIGHT = 1 << 1" 4
.IX Item "Database::PDWEIGHT = 1 << 1"
put_doc option: weight scores statically when indexing
.IP "Database::ODCLEAN = 1 << 0" 4
.IX Item "Database::ODCLEAN = 1 << 0"
out_doc option: clean up dispensable regions
.IP "Database::GDNOATTR = 1 << 0" 4
.IX Item "Database::GDNOATTR = 1 << 0"
get_doc option: no attributes
.IP "Database::GDNOTEXT = 1 << 1" 4
.IX Item "Database::GDNOTEXT = 1 << 1"
get_doc option: no text
.IP "Database::GDNOKWD = 1 << 2" 4
.IX Item "Database::GDNOKWD = 1 << 2"
get_doc option: no keywords
.ie n .IP "$db = new \fIDatabase()\fR" 4
.el .IP "\f(CW$db\fR = new \fIDatabase()\fR" 4
.IX Item "$db = new Database()"
Create a database object.
.IP "Database::search_meta(dbs, cond)" 4
.IX Item "Database::search_meta(dbs, cond)"
Search plural databases for documents corresponding a condition.  `dbs' specifies a reference of an array whose elements are database objects.  `cond' specifies a condition object.  The return value is a result object.  On error, `undef' is returned.
.ie n .IP "$db\->err_msg(\fIecode\fR)" 4
.el .IP "\f(CW$db\fR\->err_msg(\fIecode\fR)" 4
.IX Item "$db->err_msg(ecode)"
Get the string of an error code.  `ecode' specifies an error code.  The return value is the string of the error code.
.ie n .IP "$db\->open(\fIname\fR, \fIomode\fR)" 4
.el .IP "\f(CW$db\fR\->open(\fIname\fR, \fIomode\fR)" 4
.IX Item "$db->open(name, omode)"
Open a database.  `name' specifies the name of a database directory.  `omode' specifies open modes: `Database::DBWRITER' as a writer, `Database::DBREADER' as a reader.  If the mode is `Database::DBWRITER', the following may be added by bitwise or: `Database::DBCREAT', which means it creates a new database if not exist, `Database::DBTRUNC', which means it creates a new database regardless if one exists.  Both of `Database::DBREADER' and  `Database::DBWRITER' can be added to by bitwise or: `Database::DBNOLCK', which means it opens a database file without file locking, or `Database::DBLCKNB', which means locking is performed without blocking.  If `Database::DBNOLCK' is used, the application is responsible for exclusion control.  `Database::DBCREAT' can be added to by bitwise or: `Database::DBPERFNG', which means N\-gram analysis is performed against European text also, `Database::DBCHACAT', which means character category analysis is performed instead of N\-gram analysis, `Database::DBSMALL', which means the index is tuned to register less than 50000 documents, `Database::DBLARGE', which means the index is tuned to register more than 300000 documents, `Database::DBHUGE', which means the index is tuned to register more than 1000000 documents, `Database::DBHUGE2', which means the index is tuned to register more than 5000000 documents, `Database::DBHUGE3', which means the index is tuned to register more than 10000000 documents, `Database::DBSCVOID', which means scores are stored as void, `Database::DBSCINT', which means scores are stored as 32\-bit integer, `Database::DBSCASIS', which means scores are stored as-is and marked not to be tuned when search.  The return value is true if success, else it is false.
.ie n .IP "$db\->\fIclose()\fR" 4
.el .IP "\f(CW$db\fR\->\fIclose()\fR" 4
.IX Item "$db->close()"
Close the database.  The return value is true if success, else it is false.
.ie n .IP "$db\->\fIerror()\fR" 4
.el .IP "\f(CW$db\fR\->\fIerror()\fR" 4
.IX Item "$db->error()"
Get the last happened error code.  The return value is the last happened error code.
.ie n .IP "$db\->\fIfatal()\fR" 4
.el .IP "\f(CW$db\fR\->\fIfatal()\fR" 4
.IX Item "$db->fatal()"
Check whether the database has a fatal error.  The return value is true if the database has fatal erroor, else it is false.
.ie n .IP "$db\->add_attr_index(\fIname\fR, \fItype\fR)" 4
.el .IP "\f(CW$db\fR\->add_attr_index(\fIname\fR, \fItype\fR)" 4
.IX Item "$db->add_attr_index(name, type)"
Add an index for narrowing or sorting with document attributes.  `name' specifies the name of an attribute.  `type' specifies the data type of attribute index; `Database::IDXATTRSEQ' for multipurpose sequential access method, `Database::IDXATTRSTR' for narrowing with attributes as strings, `Database::IDXATTRNUM' for narrowing with attributes as numbers.  The return value is true if success, else it is false.
.ie n .IP "$db\->flush(\fImax\fR)" 4
.el .IP "\f(CW$db\fR\->flush(\fImax\fR)" 4
.IX Item "$db->flush(max)"
Flush index words in the cache.  `max' specifies the maximum number of words to be flushed.  If it not more than zero, all words are flushed.  The return value is true if success, else it is false.
.ie n .IP "$db\->\fIsync()\fR" 4
.el .IP "\f(CW$db\fR\->\fIsync()\fR" 4
.IX Item "$db->sync()"
Synchronize updating contents.  The return value is true if success, else it is false.
.ie n .IP "$db\->optimize(\fIoptions\fR)" 4
.el .IP "\f(CW$db\fR\->optimize(\fIoptions\fR)" 4
.IX Item "$db->optimize(options)"
Optimize the database.  `options' specifies options: `Database::OPTNOPURGE' to omit purging dispensable region of deleted documents, `Database::OPTNODBOPT' to omit optimization of the database files.  The two can be specified at the same time by bitwise or.  The return value is true if success, else it is false.
.ie n .IP "$db\->merge(\fIname\fR, \fIoptions\fR)" 4
.el .IP "\f(CW$db\fR\->merge(\fIname\fR, \fIoptions\fR)" 4
.IX Item "$db->merge(name, options)"
Merge another database.  `name' specifies the name of another database directory.  `options' specifies options: `Database::MGCLEAN' to clean up dispensable regions of the deleted document.  The return value is true if success, else it is false.
.ie n .IP "$db\->put_doc(\fIdoc\fR, \fIoptions\fR)" 4
.el .IP "\f(CW$db\fR\->put_doc(\fIdoc\fR, \fIoptions\fR)" 4
.IX Item "$db->put_doc(doc, options)"
Add a document.  `doc' specifies a document object.  The document object should have the \s-1URI\s0 attribute.  `options' specifies options: `Database::PDCLEAN' to clean up dispensable regions of the overwritten document.  The return value is true if success, else it is false.
.ie n .IP "$db\->out_doc(\fIid\fR, \fIoptions\fR)" 4
.el .IP "\f(CW$db\fR\->out_doc(\fIid\fR, \fIoptions\fR)" 4
.IX Item "$db->out_doc(id, options)"
Remove a document.  `id' specifies the \s-1ID\s0 number of a registered document.  `options' specifies options: `Database::ODCLEAN' to clean up dispensable regions of the deleted document.  The return value is true if success, else it is false.
.ie n .IP "$db\->edit_doc(\fIdoc\fR)" 4
.el .IP "\f(CW$db\fR\->edit_doc(\fIdoc\fR)" 4
.IX Item "$db->edit_doc(doc)"
Edit attributes of a document.  `doc' specifies a document object.  The return value is true if success, else it is false.
.ie n .IP "$db\->get_doc(\fIid\fR, \fIoptions\fR)" 4
.el .IP "\f(CW$db\fR\->get_doc(\fIid\fR, \fIoptions\fR)" 4
.IX Item "$db->get_doc(id, options)"
Retrieve a document.  `id' specifies the \s-1ID\s0 number of a registered document.  `options' specifies options: `Database::GDNOATTR' to ignore attributes, `Database::GDNOTEXT' to ignore the body text, `Database::GDNOKWD' to ignore keywords.  The three can be specified at the same time by bitwise or.  The return value is a document object.  On error, `undef' is returned.
.ie n .IP "$db\->get_doc_attr(\fIid\fR, \fIname\fR)" 4
.el .IP "\f(CW$db\fR\->get_doc_attr(\fIid\fR, \fIname\fR)" 4
.IX Item "$db->get_doc_attr(id, name)"
Retrieve the value of an attribute of a document.  `id' specifies the \s-1ID\s0 number of a registered document.  `name' specifies the name of an attribute.  The return value is the value of the attribute or `undef' if it does not exist.
.ie n .IP "$db\->uri_to_id(\fIuri\fR)" 4
.el .IP "\f(CW$db\fR\->uri_to_id(\fIuri\fR)" 4
.IX Item "$db->uri_to_id(uri)"
Get the \s-1ID\s0 of a document specified by \s-1URI. \s0 `uri' specifies the \s-1URI\s0 of a registered document.  The return value is the \s-1ID\s0 of the document.  On error, \-1 is returned.
.ie n .IP "$db\->\fIname()\fR" 4
.el .IP "\f(CW$db\fR\->\fIname()\fR" 4
.IX Item "$db->name()"
Get the name.  The return value is the name of the database.
.ie n .IP "$db\->\fIdoc_num()\fR" 4
.el .IP "\f(CW$db\fR\->\fIdoc_num()\fR" 4
.IX Item "$db->doc_num()"
Get the number of documents.  The return value is the number of documents in the database.
.ie n .IP "$db\->\fIword_num()\fR" 4
.el .IP "\f(CW$db\fR\->\fIword_num()\fR" 4
.IX Item "$db->word_num()"
Get the number of unique words.  The return value is the number of unique words in the database.
.ie n .IP "$db\->\fIsize()\fR" 4
.el .IP "\f(CW$db\fR\->\fIsize()\fR" 4
.IX Item "$db->size()"
Get the size.  The return value is the size of the database.
.ie n .IP "$db\->search(\fIcond\fR)" 4
.el .IP "\f(CW$db\fR\->search(\fIcond\fR)" 4
.IX Item "$db->search(cond)"
Search for documents corresponding a condition.  `cond' specifies a condition object.  The return value is a result object.  On error, `undef' is returned.
.ie n .IP "$db\->scan_doc(\fIdoc\fR, \fIcond\fR)" 4
.el .IP "\f(CW$db\fR\->scan_doc(\fIdoc\fR, \fIcond\fR)" 4
.IX Item "$db->scan_doc(doc, cond)"
Check whether a document object matches the phrase of a search condition object definitely.  `doc' specifies a document object.  `cond' specifies a search condition object.  The return value is true if the document matches the phrase of the condition object definitely, else it is false.
.ie n .IP "$db\->set_cache_size(\fIsize\fR, \fIanum\fR, \fItnum\fR, \fIrnum\fR)" 4
.el .IP "\f(CW$db\fR\->set_cache_size(\fIsize\fR, \fIanum\fR, \fItnum\fR, \fIrnum\fR)" 4
.IX Item "$db->set_cache_size(size, anum, tnum, rnum)"
Set the maximum size of the cache memory.  `size' specifies the maximum size of the index cache.  By default, it is 64MB.  If it is not more than 0, the current size is not changed.  `anum' specifies the maximum number of cached records for document attributes.  By default, it is 8192.  If it is not more than 0, the current size is not changed.  `tnum' specifies the maximum number of cached records for document texts.  By default, it is 1024.  If it is not more than 0, the current size is not changed.  `rnum' specifies the maximum number of cached records for occurrence results.  By default, it is 256.  If it is not more than 0, the current size is not changed.  The return value is always `undef'.
.ie n .IP "$db\->add_pseudo_index(\fIpath\fR)" 4
.el .IP "\f(CW$db\fR\->add_pseudo_index(\fIpath\fR)" 4
.IX Item "$db->add_pseudo_index(path)"
Add a pseudo index directory.  `path' specifies the path of a pseudo index directory.  The return value is true if success, else it is false.
.ie n .IP "$db\->set_wildmax(\fInum\fR)" 4
.el .IP "\f(CW$db\fR\->set_wildmax(\fInum\fR)" 4
.IX Item "$db->set_wildmax(num)"
Set the maximum number of expansion of wild cards.  `num' specifies the maximum number of expansion of wild cards.  The return value is always `undef'.
.ie n .IP "$db\->set_informer(\fIinformer\fR)" 4
.el .IP "\f(CW$db\fR\->set_informer(\fIinformer\fR)" 4
.IX Item "$db->set_informer(informer)"
Set the callback function to inform of database events.  `informer' specifies the name of an arbitrary function.  The function should have one parameter for a string of a message of each event.  The return value is always `undef'.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.SS "Gatherer"
.IX Subsection "Gatherer"
The following is the simplest implementation of a gatherer.
.PP
.Vb 4
\&  use strict;
\&  use warnings;
\&  use Estraier;
\&  $Estraier::DEBUG = 1;
\&
\&  # create the database object
\&  my $db = new Database();
\&
\&  # open the database
\&  unless($db\->open("casket", Database::DBWRITER | Database::DBCREAT)){
\&      printf("error: %s\en", $db\->err_msg($db\->error()));
\&      exit;
\&  }
\&
\&  # create a document object
\&  my $doc = new Document();
\&
\&  # add attributes to the document object
\&  $doc\->add_attr(\*(Aq@uri\*(Aq, "https://estraier.gov/example.txt");
\&  $doc\->add_attr(\*(Aq@title\*(Aq, "Over the Rainbow");
\&
\&  # add the body text to the document object
\&  $doc\->add_text("Somewhere over the rainbow.  Way up high.");
\&  $doc\->add_text("There\*(Aqs a land that I heard of once in a lullaby.");
\&
\&  # register the document object to the database
\&  unless($db\->put_doc($doc, Database::PDCLEAN)){
\&      printf("error: %s\en", $db\->err_msg($db\->error()));
\&  }
\&
\&  # close the database
\&  unless($db\->close()){
\&      printf("error: %s\en", $db\->err_msg($db\->error()));
\&  }
.Ve
.SS "Searcher"
.IX Subsection "Searcher"
The following is the simplest implementation of a searcher.
.PP
.Vb 4
\&  use strict;
\&  use warnings;
\&  use Estraier;
\&  $Estraier::DEBUG = 1;
\&
\&  # create the database object
\&  my $db = new Database();
\&
\&  # open the database
\&  unless($db\->open("casket", Database::DBREADER)){
\&      printf("error: %s\en", $db\->err_msg($db\->error()));
\&      exit;
\&  }
\&
\&  # create a search condition object
\&  my $cond = new Condition();
\&
\&  # set the search phrase to the search condition object
\&  $cond\->set_phrase("rainbow AND lullaby");
\&
\&  # get the result of search
\&  my $result = $db\->search($cond);
\&
\&  # for each document in the result
\&  my $dnum = $result\->doc_num();
\&  foreach my $i (0..$dnum\-1){
\&      # retrieve the document object
\&      my $doc = $db\->get_doc($result\->get_doc_id($i), 0);
\&      next unless(defined($doc));
\&      # display attributes
\&      my $uri = $doc\->attr(\*(Aq@uri\*(Aq);
\&      printf("URI: %s\en", $uri) if defined($uri);
\&      my $title = $doc\->attr(\*(Aq@title\*(Aq);
\&      printf("Title: %s\en", $title) if defined($title);
\&      # display the body text
\&      my $texts = $doc\->texts();
\&      foreach my $text (@$texts){
\&          printf("%s\en", $text);
\&      }
\&  }
\&
\&  # close the database
\&  unless($db.close()){
\&      printf("error: %s\en", $db\->err_msg($db\->error()));
\&  }
.Ve
.SH "LICENSE"
.IX Header "LICENSE"
.Vb 2
\& Copyright (C) 2004\-2007 Mikio Hirabayashi
\& All rights reserved.
.Ve
.PP
Hyper Estraier is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License or any later version.  Hyper Estraier is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE. \s0 See the \s-1GNU\s0 Lesser General Public License for more details.  You should have received a copy of the \s-1GNU\s0 Lesser General Public License along with Hyper Estraier; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, \s-1MA 02111\-1307 USA.\s0