Kentaro Hayashi 2019-04-25 16:19:29 +0900 (Thu, 25 Apr 2019) Revision: 4ff9d178a2617683bc6366dd91b6157197cba060 https://github.com/groonga/groonga/commit/4ff9d178a2617683bc6366dd91b6157197cba060 Message: doc: add inspect API documentation (#929) * doc: add inspect documentation * doc: update po Added files: doc/source/reference/api/grn_inspect.rst Modified files: doc/locale/ja/LC_MESSAGES/reference.po Modified: doc/locale/ja/LC_MESSAGES/reference.po (+212 -4) =================================================================== --- doc/locale/ja/LC_MESSAGES/reference.po 2019-04-25 16:12:13 +0900 (c6939b06d) +++ doc/locale/ja/LC_MESSAGES/reference.po 2019-04-25 16:19:29 +0900 (87316c5d7) @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: 1.2.1\n" "Report-Msgid-Bugs-To: \n" -"PO-Revision-Date: 2019-04-23 14:57+0900\n" +"PO-Revision-Date: 2019-04-25 11:39+0900\n" "Last-Translator: Masafumi Yokoyama <yokoy****@clear*****>\n" "Language-Team: Japanese\n" "Language: ja\n" @@ -1438,6 +1438,217 @@ msgstr "" msgid "設定しようとする値を指定します。" msgstr "" +msgid "``grn_inspect``" +msgstr "" + +msgid "" +"There are two kind of functions to inspect :c:type:`grn_obj`. One is " +"``grn_inspect`` function, The other is ``grn_p`` function." +msgstr "" +":c:type:`grn_obj` を調べるには2種類の関数があります。1つは ``grn_inspect`` 関" +"数で、もう1つは ``grn_p`` 関数です。" + +msgid "" +"Here is the list of ``grn_inspect`` function series. It sets inspected text " +"into specified object." +msgstr "" +"``grn_inspect`` 系の関数のリストは次の通りです。調査したオブジェクトの内容を" +"指定したオブジェクトに設定します。" + +msgid ":c:func:`grn_inspect()`" +msgstr "" + +msgid ":c:func:`grn_inspect_indented()`" +msgstr "" + +msgid ":c:func:`grn_inspect_limited()`" +msgstr "" + +msgid ":c:func:`grn_inspect_name()`" +msgstr "" + +msgid ":c:func:`grn_inspect_encoding()`" +msgstr "" + +msgid ":c:func:`grn_inspect_type()`" +msgstr "" + +msgid ":c:func:`grn_inspect_query_log_flags()`" +msgstr "" + +msgid "" +"Here is the list of ``grn_p`` function series. It prints inspected text into " +"console." +msgstr "" +"``grn_p`` 系の関数のリストは次の通りです。調査したオブジェクトの内容をコン" +"ソールに出力します。" + +msgid ":c:func:`grn_p()`" +msgstr "" + +msgid ":c:func:`grn_p_geo_point()`" +msgstr "" + +msgid ":c:func:`grn_p_ii_values()`" +msgstr "" + +msgid "Here is an example which inspects specified target object." +msgstr "以下はオブジェクトを調査する例です。" + +msgid "Inspect specified target ``obj`` object." +msgstr "指定した ``obj`` オブジェクトを調査します。" + +msgid "" +"A table is specified and it's table type is ``TABLE_PAT_KEY``, all keys are " +"shown. If you do not want to this behavior, use :c:func:" +"`grn_inspect_limited` instead." +msgstr "" +"``TABLE_PAT_KEY`` なテーブルが指定された場合、すべてのキーが表示されます。こ" +"の挙動が望ましくない場合、 :c:func:`grn_inspect_limited` をかわりに使ってくだ" +"さい。" + +msgid "The context object" +msgstr "その時点のコンテキスト。" + +msgid "The buffer object which is inspected text will be stored." +msgstr "調査した内容が保存されるオブジェクト" + +msgid "The inspect target object." +msgstr "対象のオブジェクト" + +msgid "``buffer`` object which is inspected text is set." +msgstr "調査した内容が設定される ``buffer`` オブジェクト" + +msgid "If obj is ``TABLE_PAT_KEY`` table, it prints like the following::" +msgstr "" +"もし ``obj`` が ``TABLE_PAT_KEY`` なテーブルであれば、次のように表示されま" +"す::" + +msgid "" +"``indent`` is only added if inspected text contains newline (inspected text " +"must be multiple lines)." +msgstr "" +"``indent`` は調査した内容が改行を含む場合に追加されます。(調査した内容のテキ" +"ストは複数行で構成されている必要があります)" + +msgid "The pre-pended indentation text." +msgstr "先頭に挿入されるインデント" + +msgid "``buffer`` object which is inspected text is set with indent." +msgstr "調査した内容がインデントとともに設定される ``buffer`` オブジェクト" + +msgid "If inspected text is too long, it will be truncated." +msgstr "調査した内容が長い場合、切り詰められます。" + +msgid "The buffer object which is inspected(truncated) text will be stored." +msgstr "調査した内容が(切り詰められて)設定されるオブジェクト" + +msgid "" +"``buffer`` object which is object detail is set. If inspected text is longer " +"than 64 characters, inspected text is truncated to it. Otherwise, inspected " +"text will not be truncated." +msgstr "" +"オブジェクトの詳細が設定される ``buffer`` オブジェクト。調査した内容が64文字" +"よりも長い場合には、その内容は切り詰められます。そうでない場合調査した内容が" +"そのまま設定されます。" + +msgid "" +"Even though if obj is ``TABLE_PAT_KEY`` table, it prints truncated result " +"like the following::" +msgstr "" +"``TABLE_PAT_KEY`` なテーブルであっても、切り詰められた内容は次のように表示さ" +"れます::" + +msgid "The buffer object which is object name will be stored." +msgstr "オブジェクト名が設定されるオブジェクト" + +msgid "" +"``buffer`` object which is name of object is set. If target object is nil, " +"``(nil)`` is set to buffer, if target object is internally used object, " +"``(anonymouse: ID)`` is set to buffer." +msgstr "" +"オブジェクトの名前が設定される ``buffer`` オブジェクト。指定したオブジェクト" +"が無効な値であれば ``(nil)`` が設定され、内部で使用しているオブジェクトであれ" +"ば ``(anonymouse: ID)`` が設定されます。" + +msgid "Specified object name is printed like this::" +msgstr "調査対象のオブジェクト名は次のように表示されます::" + +msgid "The buffer object which is encoding name will be stored." +msgstr "エンコーディング名が設定されるオブジェクト" + +msgid "" +"The inspect target encoding. encoding must be ``GRN_ENC_DEFAULT``, " +"``GRN_ENC_NONE``, ``GRN_ENC_EUC_JP``, ``GRN_ENC_UTF8``, ``GRN_ENC_SJIS``, " +"``GRN_ENC_LATIN1`` or ``GRN_ENC_KOI8R``" +msgstr "" +"調査対象のエンコーディング。エンコーディングは ``GRN_ENC_DEFAULT``、 " +"``GRN_ENC_NONE``、 ``GRN_ENC_EUC_JP``、 ``GRN_ENC_UTF8``、 " +"``GRN_ENC_SJIS``、 ``GRN_ENC_LATIN1``、 ``GRN_ENC_KOI8R`` のいずれかでなけれ" +"ばなりません。" + +msgid "" +"``buffer`` object which is encoding name is set. If invalid ``encoding`` is " +"given, ``(unknown: ENCODING)`` is set to ``buffer``." +msgstr "" +"エンコーディング名が設定される ``buffer`` オブジェクト。不正な ``encoding`` " +"が渡された場合、 ``(unknown: ENCODING)`` が ``buffer`` に設定されます。" + +msgid "Specified encoding name is printed like the following::" +msgstr "指定したエンコーディング名が次のように表示されます::" + +msgid "The buffer object which is type name will be stored." +msgstr "型の名前が設定されるオブジェクト" + +msgid "The inspect target type." +msgstr "調査対象の型" + +msgid "" +"``buffer`` object which is type name is set. If invalid ``type`` is given, " +"``(unknown: TYPE_IN_HEX)`` is set to ``buffer``." +msgstr "" +"型の名前が設定される ``buffer`` オブジェクト。正しくない ``type`` が渡された" +"場合、 ``(unknown: TYPE_IN_HEX)`` が ``buffer`` に設定されます。" + +msgid "If obj is builtin type, type name is printed like the following::" +msgstr "``obj`` が組込の型の場合、型の名前は次のように表示されます:" + +msgid "Inspect specified target ``flag``." +msgstr "指定した ``flag`` を調査します。" + +msgid "The buffer object which is flag name will be stored." +msgstr "フラグの名前が設定されるオブジェクト" + +msgid "" +"``buffer`` object which is flag name is set. If invalid ``flags`` is given, " +"empty string is set to ``buffer``." +msgstr "" +"フラグの名前が設定される ``buffer`` オブジェクト。不正な ``flags`` が与えられ" +"た場合、空の文字列が ``buffer`` に設定されます。" + +msgid "The query logger flags are printed like the following::" +msgstr "クエリーログのフラグは次のように表示されます::" + +msgid "Inspect specified target ``obj`` object. It prints inspected text." +msgstr "指定した ``obj`` を調査し、その内容を出力します。" + +msgid "If obj is ``ShortText``, it prints like the following::" +msgstr "オブジェクトが ``ShortText`` なら次のように表示されます::" + +msgid "" +"Inspect specified target ``obj`` object. It prints inspected geo point text." +msgstr "指定した ``obj`` を調査し、geo pointの内容を出力します。" + +msgid "If ``point`` indicates New York City, it prints like the following::" +msgstr "もし ``point`` がニューヨークを示す場合、次のように表示されます::" + +msgid "" +"Inspect specified target ``obj`` object. It prints inspected index values." +msgstr "指定した ``obj`` を調査し、インデックスの値を出力します。" + +msgid "If ``obj`` is an index column, it prints like the following::" +msgstr "もし ``obj`` がインデックスカラムの場合、次のように表示されます::" + msgid "``grn_match_escalation``" msgstr "" @@ -29297,6 +29508,3 @@ msgstr "" msgid "``window_sum``" msgstr "" - -#~ msgid "It specifies a flag of ``grndb`` log." -#~ msgstr "``grndb`` のログに出力する内容を指定します。" Added: doc/source/reference/api/grn_inspect.rst (+289 -0) 100644 =================================================================== --- /dev/null +++ doc/source/reference/api/grn_inspect.rst 2019-04-25 16:19:29 +0900 (51c526f54) @@ -0,0 +1,289 @@ +.. -*- rst -*- + +.. highlightlang:: none + +``grn_inspect`` +=============== + +Summary +------- + +There are two kind of functions to inspect :c:type:`grn_obj`. One is ``grn_inspect`` function, The other is ``grn_p`` function. + +Here is the list of ``grn_inspect`` function series. It sets inspected text into specified object. + +* :c:func:`grn_inspect()` +* :c:func:`grn_inspect_indented()` +* :c:func:`grn_inspect_limited()` +* :c:func:`grn_inspect_name()` +* :c:func:`grn_inspect_encoding()` +* :c:func:`grn_inspect_type()` +* :c:func:`grn_inspect_query_log_flags()` + +Here is the list of ``grn_p`` function series. It prints inspected text into console. + +* :c:func:`grn_p()` +* :c:func:`grn_p_geo_point()` +* :c:func:`grn_p_ii_values()` + +Example +------- + +Here is an example which inspects specified target object. + +.. code-block:: c + + grn_obj buffer; + GRN_TEXT_INIT(&buffer, 0); + grn_inspect(&context, &buffer, obj); + /* equivalent to grn_p(ctx, obj); */ + printf("inspected: <%.*s>\n", (int)GRN_TEXT_LEN(&buffer), GRN_TEXT_VALUE(&buffer)); + +Reference +--------- + +.. c:function:: grn_obj *grn_inspect(grn_ctx *ctx, grn_obj *buffer, grn_obj *obj) + + .. versionadded:: 4.0.8 + + Inspect specified target ``obj`` object. + + .. note:: A table is specified and it's table type is ``TABLE_PAT_KEY``, all keys are shown. + If you do not want to this behavior, use :c:func:`grn_inspect_limited` instead. + + :param ctx: The context object + :param buffer: The buffer object which is inspected text will be stored. + :param obj: The inspect target object. + :return: ``buffer`` object which is inspected text is set. + + .. code-block:: c + + grn_obj buffer; + GRN_TEXT_INIT(&buffer, 0); + grn_inspect(&context, &buffer, obj); + printf("%.*s\n", (int)GRN_TEXT_LEN(&buffer), GRN_TEXT_VALUE(&buffer)); + + If obj is ``TABLE_PAT_KEY`` table, it prints like the following:: + + #<table:pat Users key:ShortText value:(nil) size:7 columns:[] default_tokenizer:(nil) normalizer:(nil) keys:["a", "b", "c", "d", "e", "f", "g"] subrec:none nodes:{ + 4{0,5,0} + L:2{0,6,0} + L:1{0,7,0} + L:0{0,0,0} + R:1{0,7,0}("a")[01100001] + ... + +.. c:function:: grn_obj *grn_inspect_indented(grn_ctx *ctx, grn_obj *buffer, grn_obj *obj, const char *indent) + + .. versionadded:: 4.0.8 + + Inspect specified target ``obj`` object. + + .. note:: ``indent`` is only added if inspected text contains newline (inspected text must be multiple lines). + + :param ctx: The context object + :param buffer: The buffer object which is inspected text will be stored. + :param obj: The inspect target object. + :param indent: The pre-pended indentation text. + :return: ``buffer`` object which is inspected text is set with indent. + + .. code-block:: c + + grn_obj buffer; + GRN_TEXT_INIT(&buffer, 0); + grn_inspect_indented(&context, &buffer, obj, "***"); + printf("%.*s\n", (int)GRN_TEXT_LEN(&buffer), GRN_TEXT_VALUE(&buffer)); + + If obj is ``TABLE_PAT_KEY`` table, it prints like the following:: + + ***#<table:pat Users key:ShortText value:(nil) size:7 columns:[] default_tokenizer:(nil) normalizer:(nil) keys:["a", "b", "c", "d", "e", "f", "g"] subrec:none nodes:{ + ***4{0,5,0} + *** L:2{0,6,0} + *** L:1{0,7,0} + *** L:0{0,0,0} + *** R:1{0,7,0}("a")[01100001] + ... + +.. c:function:: grn_obj *grn_inspect_limited(grn_ctx *ctx, grn_obj *buffer, grn_obj *obj) + + .. versionadded:: 7.0.0 + + Inspect specified target ``obj`` object. + + .. note:: If inspected text is too long, it will be truncated. + + :param ctx: The context object + :param buffer: The buffer object which is inspected(truncated) text will be stored. + :param obj: The inspect target object. + :return: ``buffer`` object which is object detail is set. + If inspected text is longer than 64 characters, inspected text is truncated to it. Otherwise, inspected text will not be truncated. + + .. code-block:: c + + grn_obj buffer; + GRN_TEXT_INIT(&buffer, 0); + grn_inspect(&context, &buffer, obj); + printf("#=> %.*s\n", (int)GRN_TEXT_LEN(&buffer), GRN_TEXT_VALUE(&buffer)); + + Even though if obj is ``TABLE_PAT_KEY`` table, it prints truncated result like the following:: + + #<table:pat Users key:ShortText value:(nil) size:7 columns:[] de...(502) + +.. c:function:: grn_obj *grn_inspect_name(grn_ctx *ctx, grn_obj *buffer, grn_obj *obj) + + .. versionadded:: 4.0.8 + + Inspect specified target ``obj`` object. + + :param ctx: The context object + :param buffer: The buffer object which is object name will be stored. + :param obj: The inspect target object. + :return: ``buffer`` object which is name of object is set. + If target object is nil, ``(nil)`` is set to buffer, if target object is internally used object, ``(anonymouse: ID)`` is set to buffer. + + .. code-block:: c + + grn_obj buffer; + GRN_TEXT_INIT(&buffer, 0); + grn_inspect_name(&context, &buffer, obj); + printf("%.*s\n", (int)GRN_TEXT_LEN(&buffer), GRN_TEXT_VALUE(&buffer)); + + Specified object name is printed like this:: + + Users + +.. c:function:: grn_obj *grn_inspect_encoding(grn_ctx *ctx, grn_obj *buffer, grn_encoding encoding) + + .. versionadded:: 4.0.8 + + Inspect specified target ``obj`` object. + + :param ctx: The context object + :param buffer: The buffer object which is encoding name will be stored. + :param encoding: The inspect target encoding. encoding must be ``GRN_ENC_DEFAULT``, ``GRN_ENC_NONE``, ``GRN_ENC_EUC_JP``, ``GRN_ENC_UTF8``, ``GRN_ENC_SJIS``, ``GRN_ENC_LATIN1`` or ``GRN_ENC_KOI8R`` + :return: ``buffer`` object which is encoding name is set. + If invalid ``encoding`` is given, ``(unknown: ENCODING)`` is set to ``buffer``. + + .. code-block:: c + + grn_obj buffer; + GRN_TEXT_INIT(&buffer, 0); + grn_inspect_encoding(&context, &buffer, GRN_ENC_UTF8); + printf("%.*s\n", (int)GRN_TEXT_LEN(&buffer), GRN_TEXT_VALUE(&buffer)); + + Specified encoding name is printed like the following:: + + UTF-8 + +.. c:function:: grn_obj *grn_inspect_type(grn_ctx *ctx, grn_obj *buffer, unsigned char type) + + .. versionadded:: 4.0.8 + + Inspect specified target ``obj`` object. + + :param ctx: The context object + :param buffer: The buffer object which is type name will be stored. + :param type: The inspect target type. + :return: ``buffer`` object which is type name is set. + If invalid ``type`` is given, ``(unknown: TYPE_IN_HEX)`` is set to ``buffer``. + + .. code-block:: c + + grn_obj buffer; + GRN_TEXT_INIT(&buffer, 0); + grn_inspect_type(&context, &buffer, obj->header.type); + printf("#=> %.*s\n", (int)GRN_TEXT_LEN(&buffer), GRN_TEXT_VALUE(&buffer)); + + If obj is builtin type, type name is printed like the following:: + + GRN_TYPE + +.. c:function:: grn_obj *grn_inspect_query_log_flags(grn_ctx *ctx, grn_obj *buffer, unsigned int flags) + + .. versionadded:: 7.0.4 + + Inspect specified target ``flag``. + + :param ctx: The context object + :param buffer: The buffer object which is flag name will be stored. + :param flags: The inspect target type. + :return: ``buffer`` object which is flag name is set. + If invalid ``flags`` is given, empty string is set to ``buffer``. + + .. code-block:: c + + grn_obj buffer; + GRN_TEXT_INIT(&buffer, 0); + int current_flags = grn_query_logger_get_flags(&context); + grn_inspect_query_log_flags(&context, &buffer, current_flags); + printf("%.*s\n", (int)GRN_TEXT_LEN(&buffer), GRN_TEXT_VALUE(&buffer)); + + The query logger flags are printed like the following:: + + COMMAND|RESULT_CODE|DESTINATION|CACHE|SIZE|SCORE + +.. c:function:: void grn_p(grn_ctx *ctx, grn_obj *obj) + + .. versionadded:: 4.0.8 + + Inspect specified target ``obj`` object. + It prints inspected text. + + :param ctx: The context object + :param obj: The inspect target object. + + .. code-block:: c + + grn_p(&context, &buffer, obj); + + If obj is ``ShortText``, it prints like the following:: + + #<type ShortText size:4096 type:var_size> + +.. c:function:: void grn_p_geo_point(grn_ctx *ctx, grn_geo_point *point) + + .. versionadded:: 4.0.8 + + Inspect specified target ``obj`` object. + It prints inspected geo point text. + + :param ctx: The context object + :param point: The inspect target object. + + .. code-block:: c + + grn_obj point; + int latitude = ((40 * 60 * 60) + (42 * 60) + 46) * 1000; + int longitude = ((-74 * 60 * 60) + (0 * 60) + 22) * 1000; + GRN_WGS84_GEO_POINT_INIT(&point, 0); + GRN_GEO_POINT_SET(&context, &point, latitude, longitude); + grn_p_geo_point(&context, (grn_geo_point*)&point); + + If ``point`` indicates New York City, it prints like the following:: + + [(524290,18) ((0, 8, 44, 290),(0, 0, 0, 18)) [00000000 00000000 00000000 10000000 00000000 00000000 00000001 00001100]] + +.. c:function:: void grn_p_ii_values(grn_ctx *ctx, grn_obj *obj) + + .. versionadded:: 4.0.8 + + Inspect specified target ``obj`` object. + It prints inspected index values. + + :param ctx: The context object + :param obj: The inspect target object. + + .. code-block:: c + + grn_p_ii_values(&context, obj); + + If ``obj`` is an index column, it prints like the following:: + + [ + #<"!" + elements:[ + {status:available, rid:1, sid:1, pos:0, tf:1, weight:0, rest:1}, + {status:available, rid:2, sid:1, pos:0, tf:1, weight:0, rest:1} + ] + >, + ... -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://lists.osdn.me/mailman/archives/groonga-commit/attachments/20190425/75301763/attachment-0001.html>
