Kouhei Sutou
null+****@clear*****
Wed Nov 21 19:08:24 JST 2012
Kouhei Sutou 2012-11-21 19:08:24 +0900 (Wed, 21 Nov 2012) New Revision: f757c6f5487b811825577b410663687b48d82d18 https://github.com/groonga/groonga/commit/f757c6f5487b811825577b410663687b48d82d18 Log: doc: add document about output format It is not completed yet... Added files: doc/source/reference/command/output_format.txt Modified files: doc/source/reference/command.txt Modified: doc/source/reference/command.txt (+1 -0) =================================================================== --- doc/source/reference/command.txt 2012-11-21 18:42:36 +0900 (cb2cd15) +++ doc/source/reference/command.txt 2012-11-21 19:08:24 +0900 (66abaf4) @@ -12,5 +12,6 @@ :glob: command/command_version + command/output_format command/return_code commands/* Added: doc/source/reference/command/output_format.txt (+209 -0) 100644 =================================================================== --- /dev/null +++ doc/source/reference/command/output_format.txt 2012-11-21 19:08:24 +0900 (d280988) @@ -0,0 +1,209 @@ +.. -*- rst -*- + +.. highlightlang:: none + +Output format +============= + +Summary +------- + +Commands output their result as JSON, MessagePack, XML or TSV format. + +JSON and MessagePack output have the same structure. XML and TSV are +their original structure. + +JSON or MessagePack is recommend format. XML is useful for visual +result check. TSV is just for special use. Normally you doesn't need +to use TSV. + +JSON and MessagePack +-------------------- + +This secsion describes the structure of command result on JSON and +MessagePack format. JSON is used to show structure because MessagePack +is binary format. Binary format isn't proper for documenataion. + +JSON and MessagePack uses the following structure:: + + [HEADER, BODY] + +For example:: + + [ + [ + 0, + 1337566253.89858, + 0.000355720520019531 + ], + [ + [ + [ + 1 + ], + [ + [ + "_id", + "UInt32" + ], + [ + "_key", + "ShortText" + ], + [ + "content", + "Text" + ], + [ + "n_likes", + "UInt32" + ] + ], + [ + 2, + "Groonga", + "I started to use groonga. It's very fast!", + 10 + ] + ] + ] + ] + +In the example, the following part is ``HEADER``:: + + [ + 0, + 1337566253.89858, + 0.000355720520019531 + ] + +The following part is ``BODY``:: + + [ + [ + [ + 1 + ], + [ + [ + "_id", + "UInt32" + ], + [ + "_key", + "ShortText" + ], + [ + "content", + "Text" + ], + [ + "n_likes", + "UInt32" + ] + ], + [ + 2, + "Groonga", + "I started to use groonga. It's very fast!", + 10 + ] + ] + ] + +``HEADER`` +^^^^^^^^^^ + +``HEADER`` is an array. The content of ``HEADER`` has some patterns. + +Success case +++++++++++++ + +``HEADER`` has three elements on success:: + + [0, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME] + +The first element is always ``0``. + +``UNIX_TIME_WHEN_COMMAND_IS_STARTED`` is the number of seconds +since 1970-01-01 00:00:00 UTC when the command is started +processing. ``ELAPSED_TIME`` is the elapsed time for processing the +command in seconds. Both ``UNIX_TIME_WHEN_COMMAND_IS_STARTED`` and +``ELAPSED_TIME`` are float value. The precision of them are +nanosecond. + +Error case +++++++++++ + +``HEADER`` has four or five elements on error:: + + [ + RETURN_CODE, + UNIX_TIME_WHEN_COMMAND_IS_STARTED, + ELAPSED_TIME, + ERROR_MESSAGE, + ERROR_LOCATION + ] + +``ERROR_LOCATION`` may not be included in ``HEADER`` but other four +elements are always included. + +``RETURN_CODE`` is non 0 value. TODO: Write list of return code. + +``UNIX_TIME_WHEN_COMMAND_IS_STARTED`` and ``ELAPSED_TIME`` are the +same as success case. + +``ERROR_MESSAGE`` is a error message in string. + +``ERROR_LOCATION`` is optional. If error location is collected, +``ERROR_LOCATION`` is included. ``ERROR_LOCATION`` is an +array. ``ERROR_LOCATION`` has one ore two elements:: + + [ + LOCATION_IN_GROONGA, + LOCATION_IN_INPUT + ] + +``LOCATION_IN_GROONGA`` is the source location that error is occurred +in groonga. It is useful for groonga developers but not useful for +users. ``LOCATION_IN_GROONGA`` is an array. ``LOCATION_IN_GROONGA`` has +three elements:: + + [ + FUNCTION_NAME, + SOURCE_FILE_NAME, + LINE_NUMBER + ] + +``FUNCTION_NAME`` is the function that error is occurred. + +``SOURCE_FILE_NAME`` is the groonga's source file name that error is +occurred. + +``LINE_NUMBER`` is the line number of ``SOURCE_FILE_NAME`` that error +is occurred. + +``LOCATION_IN_INPUT`` is optional. ``LOCATION_IN_INPUT`` is included +when the location that error is occurred in input file is +collected. Input file can be specified by ``--file`` command line +option for ``groonga`` command. ``LOCATION_IN_GROONGA`` is an +array. ``LOCATION_IN_GROONGA`` has three elements:: + + [ + INPUT_FILE_NAME, + LINE_NUMBER, + LINE_CONTENT + ] + +``INPUT_FILE_NAME`` is the input file name that error is occurred. + +``LINE_NUMBER`` is the line number of ``INPUT_FILE_NAME`` that error +is occurred. + +``LINE_CONTENT`` is the content at ``LINE_NUMBER`` in +``INPUT_FILE_NAME``. + +``BODY`` +^^^^^^^^ + +TODO -------------- next part -------------- HTML����������������������������...Download