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

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

@@ -30,15 +30,17 @@ static VALUE cGrnContext;
  * 複数のコンテキストを利用する必要はない。
  *
  * デフォルトで使用されるコンテキストは
- * Groonga::Context#defaultでアクセスできる。コンテキストを
- * 指定できる箇所でコンテキストの指定を省略したり +nil+ を指定
- * した場合はGroonga::Context.defaultが利用される。
+ * {Groonga::Context.default} でアクセスできる。コンテキ
+ * ストを指定できる箇所でコンテキストの指定を省略したり +nil+
+ * を指定した場合は {Groonga::Context.default} が利用さ
+ * れる。
  *
  * また、デフォルトのコンテキストは必要になると暗黙のうちに
  * 作成される。そのため、コンテキストを意識することは少ない。
  *
  * 暗黙のうちに作成されるコンテキストにオプションを指定する
- * 場合はGroonga::Context.default_options=を使用する。
+ * 場合は {Groonga::Context.default_options=} を使用
+ * する。
  */
 
 grn_ctx *
@@ -325,15 +327,15 @@ rb_grn_context_text_set (grn_ctx *context, grn_obj *bulk, VALUE rb_string)
 }
 
 /*
- * call-seq:
- *   Groonga::Context.default -> Groonga::Context
- *
  * デフォルトのコンテキストを返す。デフォルトのコンテキスト
  * が作成されていない場合は暗黙のうちに作成し、それを返す。
  *
  * 暗黙のうちにコンテキストを作成する場合は、
- * Groonga::Context.default_optionsに設定されているオプショ
- * ンを利用する。
+ * {Groonga::Context.default_options} に設定されているオプ
+ * ションを利用する。
+ *
+ * @overload default
+ *   @return [Groonga::Context]
  */
 static VALUE
 rb_grn_context_s_get_default (VALUE self)
@@ -355,13 +357,12 @@ rb_grn_context_get_default (void)
 }
 
 /*
- * call-seq:
- *   Groonga::Context.default=(context)
- *
  * デフォルトのコンテキストを設定する。 +nil+ を指定すると、
  * デフォルトのコンテキストをリセットする。リセットすると、次
- * 回Groonga::Context.defaultを呼び出したときに新しくコンテ
- * キストが作成される。
+ * 回 {Groonga::Context.default} を呼び出したときに新しくコ
+ * ンテキストが作成される。
+ *
+ * @overload default=(context)
  */
 static VALUE
 rb_grn_context_s_set_default (VALUE self, VALUE context)
@@ -371,11 +372,11 @@ rb_grn_context_s_set_default (VALUE self, VALUE context)
 }
 
 /*
- * call-seq:
- *   Groonga::Context.default_options -> Hash or nil
- *
  * コンテキストを作成する時に利用するデフォルトのオプション
  * を返す。
+ *
+ * @overload default_options
+ *   @return [::Hash or nil]
  */
 static VALUE
 rb_grn_context_s_get_default_options (VALUE self)
@@ -384,12 +385,11 @@ rb_grn_context_s_get_default_options (VALUE self)
 }
 
 /*
- * call-seq:
- *   Groonga::Context.default_options=(options)
- *
  * コンテキストを作成する時に利用するデフォルトのオプション
  * を設定する。利用可能なオプションは
- * Groonga::Context.newを参照。
+ * {Groonga::Context.new} を参照。
+ *
+ * @overload default_options=(options)
  */
 static VALUE
 rb_grn_context_s_set_default_options (VALUE self, VALUE options)
@@ -399,17 +399,13 @@ rb_grn_context_s_set_default_options (VALUE self, VALUE options)
 }
 
 /*
- * call-seq:
- *   Groonga::Context.new(options=nil)
- *
- * コンテキストを作成する。 _options_ に指定可能な値は以下の通
- * り。
- * @param [::Hash] options The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :encoding The encoding
- *
- *   エンコーディングを指定する。エンコーディングの指定方法
- *   はGroonga::Encodingを参照。
+ * コンテキストを作成する。
+ * @overload new(options=nil)
+ *   @param [::Hash] options The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options [Groonga::Encoding] :encoding The encoding
+ *     エンコーディングを指定する。エンコーディングの指定方法
+ *     は {Groonga::Encoding} を参照。
  */
 static VALUE
 rb_grn_context_initialize (int argc, VALUE *argv, VALUE self)
@@ -458,11 +454,10 @@ rb_grn_context_initialize (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * call-seq:
- *   context.close
- *
  * Closes the _context_. Closed _context_ can't be used
  * anymore.
+ *
+ * @overload close
  */
 static VALUE
 rb_grn_context_close (VALUE self)
@@ -483,10 +478,9 @@ rb_grn_context_close (VALUE self)
 }
 
 /*
- * call-seq:
- *   context.closed?
- *
  * Returns whether the _context_ is closed by #close or not.
+ *
+ * @overload closed?
  */
 static VALUE
 rb_grn_context_closed_p (VALUE self)
@@ -499,10 +493,10 @@ rb_grn_context_closed_p (VALUE self)
 }
 
 /*
- * call-seq:
- *   context.inspect -> String
- *
  * コンテキストの中身を人に見やすい文字列で返す。
+ *
+ * @overload inspect
+ *   @return [String]
  */
 static VALUE
 rb_grn_context_inspect (VALUE self)
@@ -539,10 +533,10 @@ rb_grn_context_inspect (VALUE self)
 }
 
 /*
- * call-seq:
- *   context.encoding -> Groonga::Encoding
- *
  * コンテキストが使うエンコーディングを返す。
+ *
+ * @overload encoding
+ *   @return [Groonga::Encoding]
  */
 static VALUE
 rb_grn_context_get_encoding (VALUE self)
@@ -551,11 +545,10 @@ rb_grn_context_get_encoding (VALUE self)
 }
 
 /*
- * call-seq:
- *   context.encoding=(encoding)
- *
  * コンテキストが使うエンコーディングを設定する。エンコーディ
- * ングの指定のしかたはGroonga::Encodingを参照。
+ * ングの指定のしかたは {Groonga::Encoding} を参照。
+ *
+ * @overload encoding=(encoding)
  */
 static VALUE
 rb_grn_context_set_encoding (VALUE self, VALUE rb_encoding)
@@ -571,13 +564,36 @@ rb_grn_context_set_encoding (VALUE self, VALUE rb_encoding)
 }
 
 /*
- * call-seq:
- *   context.match_escalation_threshold -> Integer
+ * Gets the encoding used by the context as Ruby's encoding object.
+ *
+ * @overload ruby_encoding
+ *
+ * @return [::Encoding] the encoding used by the context
  *
+ * @since 2.0.5
+ */
+static VALUE
+rb_grn_context_get_ruby_encoding (VALUE self)
+{
+#ifdef HAVE_RUBY_ENCODING_H
+    grn_encoding encoding;
+
+    encoding = GRN_CTX_GET_ENCODING(SELF(self));
+    return rb_grn_encoding_to_ruby_encoding_object(encoding);
+#else
+    return Qnil;
+#endif
+}
+
+/*
  * このコンテキストを使って検索したときに検索の挙動をエスカレー
- * ションする閾値を返します。エスカレーションの詳細はgroonga
- * の検索の仕様に関するドキュメントを参照してください。
- * http://groonga.org/docs/spec/search.html#spec-search
+ * ションする閾値を返します。
+ * エスカレーションの詳細は
+ * "groongaの検索の仕様に関するドキュメント":http://groonga.org/docs/spec/search.html#match-escalation-threshold
+ * を参照してください。
+ *
+ * @overload match_escalation_threshold
+ *   @return [Integer]
  */
 static VALUE
 rb_grn_context_get_match_escalation_threshold (VALUE self)
@@ -586,13 +602,13 @@ rb_grn_context_get_match_escalation_threshold (VALUE self)
 }
 
 /*
- * call-seq:
- *   context.match_escalation_threshold=(match_escalation_threshold)
- *
  * このコンテキストを使って検索したときに検索の挙動をエスカレー
- * ションする閾値を設定します。エスカレーションの詳細はgroonga
- * の検索の仕様に関するドキュメントを参照してください。
- * http://groonga.org/docs/spec/search.html#spec-search
+ * ションする閾値を設定します。
+ * エスカレーションの詳細は
+ * "groongaの検索の仕様に関するドキュメント":http://groonga.org/docs/spec/search.html#match-escalation-threshold
+ * を参照してください。
+ *
+ * @overload match_escalation_threshold=(match_escalation_threshold)
  */
 static VALUE
 rb_grn_context_set_match_escalation_threshold (VALUE self, VALUE threshold)
@@ -606,11 +622,10 @@ rb_grn_context_set_match_escalation_threshold (VALUE self, VALUE threshold)
 }
 
 /*
- * call-seq:
- *   context.support_zlib?
- *
  * groongaがZlibサポート付きでビルドされていれば +true+ 、そう
  * でなければ +false+ を返す。
+ *
+ * @overload support_zlib?
  */
 static VALUE
 rb_grn_context_support_zlib_p (VALUE self)
@@ -629,11 +644,10 @@ rb_grn_context_support_zlib_p (VALUE self)
 }
 
 /*
- * call-seq:
- *   context.support_lzo?
- *
  * groongaがLZOサポート付きでビルドされていれば +true+ 、そう
  * でなければ +false+ を返す。
+ *
+ * @overload support_lzo?
  */
 static VALUE
 rb_grn_context_support_lzo_p (VALUE self)
@@ -652,10 +666,10 @@ rb_grn_context_support_lzo_p (VALUE self)
 }
 
 /*
- * call-seq:
- *   context.database -> Groonga::Database
- *
  * コンテキストが使うデータベースを返す。
+ *
+ * @overload database
+ *   @return [Groonga::Database]
  */
 static VALUE
 rb_grn_context_get_database (VALUE self)
@@ -667,21 +681,15 @@ rb_grn_context_get_database (VALUE self)
 }
 
 /*
- * call-seq:
- *   context.connect(options=nil)
- *
- * groongaサーバに接続する。 _options_ に指定可能な値は以下の通
- * り。
- * @param [::Hash] options The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :host (localhost) The groonga server host name
- *
- *   groongaサーバのホスト名。またはIPアドレス。省略すると
- *   "localhost"に接続する。
- * @option options :port (10041) The port number
- *
- *   groongaサーバのポート番号。省略すると10041番ポートに接
- *   続する。
+ * groongaサーバに接続する。
+ * @overload connect(options=nil)
+ *   @param [::Hash] options 利用可能なオプションは次の通り。
+ *   @option options :host (localhost)
+ *     groongaサーバのホスト名。またはIPアドレス。省略すると
+ *     "localhost"に接続する。
+ *   @option options :port (10041)
+ *     groongaサーバのポート番号。省略すると10041番ポートに接
+ *     続する。
  */
 static VALUE
 rb_grn_context_connect (int argc, VALUE *argv, VALUE self)
@@ -721,10 +729,10 @@ rb_grn_context_connect (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * call-seq:
- *   context.send(string) -> ID
- *
  * groongaサーバにクエリ文字列を送信する。
+ * @return [Integer] ID
+ * @overload send(string)
+ *   @param [String] string クエリ文字列
  */
 static VALUE
 rb_grn_context_send (VALUE self, VALUE rb_string)
@@ -745,10 +753,9 @@ rb_grn_context_send (VALUE self, VALUE rb_string)
 }
 
 /*
- * call-seq:
- *   context.receive -> [ID, String]
- *
  * groongaサーバからクエリ実行結果文字列を受信する。
+ * @overload receive
+ * @return [[ID, String]] クエリ実行結果
  */
 static VALUE
 rb_grn_context_receive (VALUE self)
@@ -844,10 +851,6 @@ rb_grn_context_get_backward_compatibility (grn_ctx *context,
 
 
 /*
- * call-seq:
- *   context[name] -> Groonga::Object or nil
- *   context[id]   -> Groonga::Object or nil
- *
  * コンテキスト管理下にあるオブジェクトを返す。
  *
  * _name_ として文字列を指定した場合はオブジェクト名でオブジェ
@@ -855,6 +858,11 @@ rb_grn_context_get_backward_compatibility (grn_ctx *context,
  *
  * _id_ として数値を指定した場合はオブジェクトIDでオブジェク
  * トを検索する。
+ *
+ * @overload [](name)
+ *   @return [Groonga::Object or nil]
+ * @overload [](id)
+ *   @return [Groonga::Object or nil]
  */
 static VALUE
 rb_grn_context_array_reference (VALUE self, VALUE name_or_id)
@@ -889,6 +897,7 @@ rb_grn_context_array_reference (VALUE self, VALUE name_or_id)
 		 rb_grn_inspect(name_or_id));
 	break;
     }
+    rb_grn_context_check(context, name_or_id);
 
     return GRNOBJECT2RVAL(Qnil, context, object, GRN_FALSE);
 }
@@ -920,6 +929,8 @@ rb_grn_init_context (VALUE mGrn)
 
     rb_define_method(cGrnContext, "encoding", rb_grn_context_get_encoding, 0);
     rb_define_method(cGrnContext, "encoding=", rb_grn_context_set_encoding, 1);
+    rb_define_method(cGrnContext, "ruby_encoding",
+		     rb_grn_context_get_ruby_encoding, 0);
     rb_define_method(cGrnContext, "match_escalation_threshold",
 		     rb_grn_context_get_match_escalation_threshold, 0);
     rb_define_method(cGrnContext, "match_escalation_threshold=",