rroonga 2.0.4-x86-mingw32 → 2.0.7-x86-mingw32

data/ext/groonga/rb-grn-column.c

@@ -31,13 +31,14 @@ VALUE rb_cGrnColumn;
  * 加することができる。
  *
  * カラムには大きく分けて3種類ある。
- * [Groonga::FixSizeColumn]
- *   固定長のデータを格納するカラム。
- * [Groonga::VariableSizeColumn]
- *   可変長のデータを格納するカラム。
- * [Groonga::IndexColumn]
+ *
+ * - {Groonga::FixSizeColumn} :=
+ *   固定長のデータを格納するカラム。 =:
+ * - {Groonga::VariableSizeColumn} :=
+ *   可変長のデータを格納するカラム。 =:
+ * - {Groonga::IndexColumn} :=
  *   転置インデックスを格納するカラム。全文検索や参照元レコー
- *   ドの検索を行う場合はこのカラムを使用する。
+ *   ドの検索を行う場合はこのカラムを使用する。 =:
  *
  * 固定長データ用カラム・可変長データ用カラムは1つのデータだ
  * けを格納するか複数のデータを格納するかを選ぶことができる。
@@ -110,10 +111,10 @@ rb_grn_column_deconstruct (RbGrnColumn *rb_column,
 }
 
 /*
- * call-seq:
- *   column.table -> Groonga::Table
- *
  * カラムが所属するテーブルを返す。
+ *
+ * @overload table
+ *   @return [Groonga::Table]
  */
 static VALUE
 rb_grn_column_get_table (VALUE self)
@@ -132,14 +133,14 @@ rb_grn_column_get_table (VALUE self)
 }
 
 /*
- * call-seq:
- *   column.local_name
- *
- * @example テーブル名を除いたカラム名を返す。
+ * テーブル名を除いたカラム名を返す。
+ * @example
  *   items = Groonga::Array.create(:name => "Items")
  *   title = items.define_column("title", "ShortText")
  *   title.name # => "Items.title"
  *   title.local_name # => "title"
+ *
+ * @overload local_name
  */
 static VALUE
 rb_grn_column_get_local_name (VALUE self)
@@ -167,113 +168,136 @@ rb_grn_column_get_local_name (VALUE self)
     return rb_name;
 }
 
-/*
- * call-seq:
- *   column.select(options) {|record| ...} -> Groonga::Hash
- *   column.select(query, options) -> Groonga::Hash
- *   column.select(expression, options) -> Groonga::Hash
- *
+ /*
  * カラムが所属するテーブルからブロックまたは文字列で指定し
  * た条件にマッチするレコードを返す。返されたテーブルには
  * +expression+ という特異メソッドがあり、指定した条件を表し
- * ているGroonga::Expressionを取得できる。
- * Groonga::Expression#snippetを使うことにより、指定した条件
+ * ている {Groonga::Expression} を取得できる。
+ * {Groonga::Expression#snippet} を使うことにより、指定した条件
  * 用のスニペットを簡単に生成できる。
  *
  * bc. !!!ruby
- * results = description_column.select do |column|
- *   column =~ "groonga"
- * end
- * snippet = results.expression.snippet([["<em>", "</em>"]])
- * results.each do |record|
- *   puts "#{record['name']}の説明文の中で「groonga」が含まれる部分"
- *   snippet.execute(record["description"]).each do |snippet|
- *     puts "---"
- *     puts "#{snippet}..."
- *     puts "---"
+ *   results = description_column.select do |column|
+ *     column =~ "groonga"
+ *   end
+ *   snippet = results.expression.snippet([["<em>", "</em>"]])
+ *   results.each do |record|
+ *     puts "#{record['name']}の説明文の中で「groonga」が含まれる部分"
+ *     snippet.execute(record["description"]).each do |snippet|
+ *       puts "---"
+ *       puts "#{snippet}..."
+ *       puts "---"
+ *     end
  *   end
- * end
  *
  * 出力例
  *
- * pre. rroongaの説明文の中で「groonga」が含まれる部分
+ * <pre>
+ * !!!text
+ * rroongaの説明文の中で「groonga」が含まれる部分
  * ---
  * rroongaは<em>groonga</em>のいわゆるDB-APIの層の...
  * ---
- *
- * _query_ には「[カラム名]:[演算子][値]」という書式で条件を
- * 指定する。演算子は以下の通り。
- *
- * - なし := [カラム値] == [値]
- * - @!@ := [カラム値] != [値]
- * - @<@ := [カラム値] < [値]
- * - @>@ := [カラム値] > [値]
- * - @<=@ := [カラム値] <= [値]
- * - @>=@ := [カラム値] >= [値]
- * - @@@ := [カラム値]が[値]を含んでいるかどうか
- *
- * 例:
- *
- * - @"groonga"@ := _column_ カラムの値が @"groonga"@ のレコードにマッチ
- * - @"name:daijiro"@ :=
- *   _column_ カラムが属しているテーブルの @"name"@ カラムの値が
- *   @"daijiro"@ のレコードにマッチ  =:
- * - @"description:@@@groonga"@ :=
- *   _column_ カラムが属しているテーブルの @"description"@ カラムが
- *   @"groonga"@ を含んでいるレコードにマッチ =:
- *
- * _expression_ には既に作成済みのGroonga::Expressionを渡す
- *
- * ブロックで条件を指定する場合は
- * {Groonga::ColumnExpressionBuilder} を参照。
- *
- * _options_ に指定可能な値は以下の通り。
- * @param [::Hash] options The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :operator (Groonga::Operator::OR) The operator
- *   マッチしたレコードをどのように扱うか。指定可能な値は以
- *   下の通り。
- *
- *   [Groonga::Operator::OR]
- *     マッチしたレコードを追加。すでにレコードが追加され
- *     ている場合は何もしない。
- *   [Groonga::Operator::AND]
- *     マッチしたレコードのスコアを増加。マッチしなかった
- *     レコードを削除。
- *   [Groonga::Operator::BUT]
- *     マッチしたレコードを削除。
- *   [Groonga::Operator::ADJUST]
- *     マッチしたレコードのスコアを増加。
- *
- * @option options :result The result
- *   検索結果を格納するテーブル。マッチしたレコードが追加さ
- *   れていく。省略した場合は新しくテーブルを作成して返す。
- *
- * @option options :name The name
- *   条件の名前。省略した場合は名前を付けない。
- *
- * @option options :syntax (:query) The syntax
- *   _query_の構文。
- *
- *   参考: Groonga::Expression#parse.
- *
- * @option options :allow_pragma The allow_pragma
- *   query構文時にプラグマを利用するかどうか。省略した場合は
- *   利用する。
- *
- *   参考: Groonga::Expression#parse.
- *
- * @option options :allow_column The allow_column
- *   query構文時にカラム指定を利用するかどうか。省略した場合
- *   は利用する。
- *
- *   参考: Groonga::Expression#parse.
- *
- * @option options :allow_update
- *   script構文時に更新操作を利用するかどうか。省略した場合
- *   は利用する。
- *
- *   参考: Groonga::Expression#parse.
+ * </pre>
+ *
+ * @return [Groonga::Hash] 検索結果
+ * @overload select(options)
+ *   @yieldparam [Groonga::Record] record
+ *     検索条件を指定するのに、 _record_ に対して次のメソッドを使って検索条
+ *     件を指定できます。
+ *
+ *     @==@ 、 @=~@ 、 @<@ 、 @<=@ 、 @>@ 、 @>=@ 、 @+@ 、 @-@ 、
+ *     @*@ 、 @/@ 、 @%@ 、
+ *     @match(query, :syntax => :query/:script, &block)@
+ *     （ _query_ に指定した
+ *     "grn_expr":http://groonga.org/ja/docs/reference/grn_expr.html
+ *     とのマッチ）、
+ *     @similar_search(text)@ （ _text_ との類似文書探索）、
+ *     @term_extract(text)@ （ _text_ 内から _record_ の単語を抽出）
+ *
+ *   @!macro [new] column.select.options
+ *     @param [::Hash] options The name and value
+ *       pairs. Omitted names are initialized as the default value.
+ *     @option options :operator (Groonga::Operator::OR)
+ *       マッチしたレコードをどのように扱うか。指定可能な値は以
+ *       下の通り。
+ *
+ *       - Groonga::Operator::OR :=
+ *         マッチしたレコードを追加。すでにレコードが追加され
+ *         ている場合は何もしない。 =:
+ *       - Groonga::Operator::AND :=
+ *         マッチしたレコードのスコアを増加。マッチしなかった
+ *         レコードを削除。 =:
+ *       - Groonga::Operator::BUT :=
+ *         マッチしたレコードを削除。 =:
+ *       - Groonga::Operator::ADJUST :=
+ *         マッチしたレコードのスコアを増加。 =:
+ *
+ *     @option options :result
+ *       検索結果を格納するテーブル。マッチしたレコードが追加さ
+ *       れていく。省略した場合は新しくテーブルを作成して返す。
+ *
+ *     @option options :name
+ *       条件の名前。省略した場合は名前を付けない。
+ *
+ *     @option options :syntax (:query)
+ *       _query_ の構文。
+ *
+ *       参考: {Groonga::Expression#parse} .
+ *
+ *     @option options :allow_pragma
+ *       query構文時にプラグマを利用するかどうか。省略した場合は
+ *       利用する。
+ *
+ *       参考: {Groonga::Expression#parse} .
+ *
+ *     @option options :allow_column The allow_column
+ *       query構文時にカラム指定を利用するかどうか。省略した場合
+ *       は利用する。
+ *
+ *       参考: {Groonga::Expression#parse} .
+ *
+ *     @option options :allow_update
+ *       script構文時に更新操作を利用するかどうか。省略した場合
+ *       は利用する。
+ *
+ *       参考: {Groonga::Expression#parse} .
+ *
+ *     @option options :allow_leading_not
+ *       指定語句の先頭に-を付けることで指定した語句を含まないレコードの
+ *       検索を有効にするかどうかを指定する。省略した場合は無効にする。
+ *
+ *       参考: {Groonga::Expression#parse} .
+ *
+ *   @!macro column.select.options
+ * @overload select(query, options)
+ *   @param [String] query 条件の指定
+ *     _query_ には「[カラム名]:[演算子][値]」という書式で条件を
+ *     指定する。演算子は以下の通り。
+ *
+ *     - なし := [カラム値] == [値]
+ *     - @!@ := [カラム値] != [値]
+ *     - @<@ := [カラム値] < [値]
+ *     - @>@ := [カラム値] > [値]
+ *     - @<=@ := [カラム値] <= [値]
+ *     - @>=@ := [カラム値] >= [値]
+ *     - @@@ := [カラム値]が[値]を含んでいるかどうか
+ *
+ *     例:
+ *
+ *     - @"groonga"@ := _column_ カラムの値が @"groonga"@ のレコードにマッチ
+ *     - @"name:daijiro"@ :=
+ *       _column_ カラムが属しているテーブルの @"name"@ カラムの値が
+ *       @"daijiro"@ のレコードにマッチ  =:
+ *     - @"description:@@@groonga"@ :=
+ *       _column_ カラムが属しているテーブルの @"description"@ カラムが
+ *       @"groonga"@ を含んでいるレコードにマッチ =:
+ *
+ *   @!macro column.select.options
+ * @overload select(expression, options)
+ *   @param [Groonga::Expression] expression 条件を表すオブジェクト
+ *     _expression_ には既に作成済みの {Groonga::Expression} を渡す。
+ *   @!macro column.select.options
  */
 static VALUE
 rb_grn_column_select (int argc, VALUE *argv, VALUE self)
@@ -284,7 +308,7 @@ rb_grn_column_select (int argc, VALUE *argv, VALUE self)
     VALUE options;
     VALUE rb_query, condition_or_options;
     VALUE rb_name, rb_operator, rb_result, rb_syntax;
-    VALUE rb_allow_pragma, rb_allow_column, rb_allow_update;
+    VALUE rb_allow_pragma, rb_allow_column, rb_allow_update, rb_allow_leading_not;
     VALUE builder;
     VALUE rb_expression = Qnil;
 
@@ -320,6 +344,7 @@ rb_grn_column_select (int argc, VALUE *argv, VALUE self)
 			"allow_pragma", &rb_allow_pragma,
 			"allow_column", &rb_allow_column,
 			"allow_update", &rb_allow_update,
+			"allow_leading_not", &rb_allow_leading_not,
 			NULL);
 
     if (!NIL_P(rb_operator))
@@ -341,6 +366,7 @@ rb_grn_column_select (int argc, VALUE *argv, VALUE self)
       rb_funcall(builder, rb_intern("allow_pragma="), 1, rb_allow_pragma);
       rb_funcall(builder, rb_intern("allow_column="), 1, rb_allow_column);
       rb_funcall(builder, rb_intern("allow_update="), 1, rb_allow_update);
+      rb_funcall(builder, rb_intern("allow_leading_not="), 1, rb_allow_leading_not);
       rb_expression = rb_grn_column_expression_builder_build(builder);
     }
     rb_grn_object_deconstruct(RB_GRN_OBJECT(DATA_PTR(rb_expression)),
@@ -359,18 +385,12 @@ rb_grn_column_select (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Document-method: unlock
- *
- * call-seq:
- *   column.unlock(options={})
- *
  * _column_ のロックを解除する。
- *
- * 利用可能なオプションは以下の通り。
- *
- * [_:id_]
- *   _:id_ で指定したレコードのロックを解除する。
- *   （注: groonga側が未実装のため、現在は無視される）
+ * @overload unlock(options={})
+ *   @param [::Hash] options 利用可能なオプションは以下の通り。
+ *   @option options :id
+ *     _:id_ で指定したレコードのロックを解除する。
+ *     （注: groonga側が未実装のため、現在は無視される）
  */
 static VALUE
 rb_grn_column_unlock (int argc, VALUE *argv, VALUE self)
@@ -408,26 +428,23 @@ rb_grn_column_unlock_ensure (VALUE self)
 }
 
 /*
- * Document-method: lock
- *
- * call-seq:
- *   column.lock(options={})
- *   column.lock(options={}) {...}
- *
  * _column_ をロックする。ロックに失敗した場合は
- * Groonga::ResourceDeadlockAvoided例外が発生する。
- *
- * ブロックを指定した場合はブロックを抜けたときにunlockする。
- *
- * 利用可能なオプションは以下の通り。
- *
- * [_:timeout_]
- *   ロックを獲得できなかった場合は_:timeout_秒間ロックの獲
- *   得を試みる。_:timeout_秒以内にロックを獲得できなかった
- *   場合は例外が発生する。
- * [_:id_]
- *   _:id_で指定したレコードをロックする。（注: groonga側が
- *   未実装のため、現在は無視される）
+ * {Groonga::ResourceDeadlockAvoided} 例外が発生する。
+ *
+ * @overload lock(options={})
+ *   @!macro [new] column.lock.options
+ *     @param [::Hash] options 利用可能なオプションは以下の通り。
+ *     @option options :timeout
+ *       ロックを獲得できなかった場合は _:timeout_ 秒間ロックの獲
+ *       得を試みる。 _:timeout_ 秒以内にロックを獲得できなかった
+ *       場合は例外が発生する。
+ *     @option options :id
+ *       _:id_で指定したレコードをロックする。（注: groonga側が
+ *       未実装のため、現在は無視される）
+ *   @!macro column.lock.options
+ * @overload lock(options={})
+ *   @yield ブロックを指定した場合はブロックを抜けたときにunlockする。
+ *   @!macro column.lock.options
  */
 static VALUE
 rb_grn_column_lock (int argc, VALUE *argv, VALUE self)
@@ -468,20 +485,14 @@ rb_grn_column_lock (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Document-method: clear_lock
- *
- * call-seq:
- *   column.clear_lock(options={})
- *
- * _column_のロックを強制的に解除する。
- *
- * 利用可能なオプションは以下の通り。
- *
- * [_:id_]
- *   _:id_で指定したレコードのロックを強制的に解除する。
- *   （注: groonga側が未実装のため、現在は無視される。実装さ
- *   れるのではないかと思っているが、実装されないかもしれな
- *   い。）
+ * _column_ のロックを強制的に解除する。
+ * @overload clear_lock(options={})
+ *   @param [::Hash] options 利用可能なオプションは以下の通り。
+ *   @option options :id
+ *     _:id_で指定したレコードのロックを強制的に解除する。
+ *     （注: groonga側が未実装のため、現在は無視される。実装さ
+ *     れるのではないかと思っているが、実装されないかもしれな
+ *     い。）
  */
 static VALUE
 rb_grn_column_clear_lock (int argc, VALUE *argv, VALUE self)
@@ -510,20 +521,14 @@ rb_grn_column_clear_lock (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Document-method: locked?
- *
- * call-seq:
- *   column.locked?(options={})
- *
  * _column_ がロックされていれば +true+ を返す。
- *
- * 利用可能なオプションは以下の通り。
- *
- * [_:id_]
- *   _:id_で指定したレコードがロックされていれば +true+ を返す。
- *   （注: groonga側が未実装のため、現在は無視される。実装さ
- *   れるのではないかと思っているが、実装されないかもしれな
- *   い。）
+ * @overload locked?(options={})
+ *   @param [::Hash] options 利用可能なオプションは以下の通り。
+ *   @option options :id
+ *     _:id_で指定したレコードがロックされていれば +true+ を返す。
+ *     （注: groonga側が未実装のため、現在は無視される。実装さ
+ *     れるのではないかと思っているが、実装されないかもしれな
+ *     い。）
  */
 static VALUE
 rb_grn_column_is_locked (int argc, VALUE *argv, VALUE self)
@@ -550,15 +555,12 @@ rb_grn_column_is_locked (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Document-method: reference?
- *
- * call-seq:
- *   column.reference? -> true/false
- *
  * _column_ の値がテーブルのレコードとなる場合は +true+ を返し、
  * そうでない場合は +false+ を返す。
  *
  * @since 1.0.5
+ *
+ * @overload reference?
  */
 static VALUE
 rb_grn_column_reference_p (VALUE self)
@@ -588,15 +590,12 @@ rb_grn_column_reference_p (VALUE self)
 }
 
 /*
- * Document-method: index?
- *
- * call-seq:
- *   column.index? -> true/false
- *
- * _column_ がGroonga::IndexColumnの場合は +true+ を返し、
+ * _column_ が {Groonga::IndexColumn} の場合は +true+ を返し、
  * そうでない場合は +false+ を返す。
  *
  * @since 1.0.5
+ *
+ * @overload index?
  */
 static VALUE
 rb_grn_column_index_p (VALUE self)
@@ -616,15 +615,12 @@ rb_grn_column_index_p (VALUE self)
 }
 
 /*
- * Document-method: vector?
- *
- * call-seq:
- *   column.vector? -> true/false
- *
  * _column_ がベクターカラムの場合は +true+ を返し、
  * そうでない場合は +false+ を返す。
  *
  * @since 1.0.5
+ *
+ * @overload vector?
  */
 static VALUE
 rb_grn_column_vector_p (VALUE self)
@@ -646,15 +642,12 @@ rb_grn_column_vector_p (VALUE self)
 }
 
 /*
- * Document-method: scalar?
- *
- * call-seq:
- *   column.scalar? -> true/false
- *
  * _column_ がスカラーカラムの場合は +true+ を返し、
  * そうでない場合は +false+ を返す。
  *
  * @since 1.0.5
+ *
+ * @overload scalar?
  */
 static VALUE
 rb_grn_column_scalar_p (VALUE self)
@@ -682,14 +675,11 @@ rb_grn_column_scalar_p (VALUE self)
 }
 
 /*
- * Document-method: indexes
- *
- * call-seq:
- *   column.indexes(operator=Groonga::Operator::MATCH) -> [index_column, ...]
- *
- * _operation_ を実行できる _column_ のインデックスを返す。
- *
+ * _operator_ を実行できる _column_ のインデックスを返す。
  * @since 1.0.9
+ * @return [Array<index_column>] _operator_ を実行できる _column_ のインデックス
+ * @overload indexes(operator=Groonga::Operator::MATCH)
+ *   @param [Groonga::Operator::XXX] operator
  */
 static VALUE
 rb_grn_column_get_indexes (int argc, VALUE *argv, VALUE self)
@@ -731,15 +721,10 @@ rb_grn_column_get_indexes (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Document-method: rename
- *
- * call-seq:
- *   table.rename(name)
- *
  * Renames the table to name.
- *
- * @param name [String] the new name
  * @since 1.3.0
+ * @overload rename(name)
+ *   @param name [String] the new name
  */
 static VALUE
 rb_grn_column_rename (VALUE self, VALUE rb_name)