How to use the ktuo parser/encoder

Starting

Ktuo is a json and tuple parser encoder for the erlang language. It is reasonably simple to use, however, it never hurts to have a walk through.

Unlike the existing Erlang parser for json ktuo needs an entire expression to be available before it is able to parse said expression. This limits its use to some extent but it vastly simplifies the codebase and allows for many speed improvements.

Json Decode API

To parse anything in Ktuo you must have already read in the data from some source. Once you have done that and you have some reasonable certainty that you have an entire expression you can call the decode functions of ktuo.

 Data = <read in data>,
 {Json, Rest, {Lines, Cols}} = ktuo_json:decode(Data).

As you can see ktuo returns a tuple describing its output. The first element of the tuple is the parsed json expression. The second element is the data that was left over after parsing. If you expect multiple expressions you may use this data to call the decode function again. The Lines and Columns tuple is returned for informational purposes. If you have multiple expressions to parse you may pass them to the decode/3 function of ktuo_json so that error reporting of lines/cols may remain accurate.

 Data = <read in data>,
 {Json, Rest, {Lines, Cols}} = ktuo_json:decode(Data),
 {NewJSon, NewRest, {NLines, NCols}} = ktuo_json:decode(Rest, Lines, Cols).

Errors are returned as a tuple of three elements.

 {error, Reason, {Line, Col}}

The first element is the error atom. The second element is the error reason and the third element is a tuple of the line and column of the error.

Json Decode Mapping

Json Encode API

The json encode api is actually much simpler then the decode api. There is only one function and that function converts the Erlang data into json data. The resultant json data is a deeply nested list of lists. The Erlang IO primitives understand and flatten deeply nested lists without any problem. However, if you wish to manipulate the resultant list you must be aware of its deeply nested nature.

 OutputList = ktuo_json:encode({string, "Hello!"}),
 OutputList2 = ktuo_json:encode([1,2,3,4]),
 OutputList3 = ktuo_json:encode([{key, {string, "Value"}}]).

The only real gotcha here is that, because of the nature of Erlang's strings, you must inform the encoder that a particular list is a string. You do this via a tuple {string, "Value"}. Its a bit of a pain but its the only way I know how to handle this at the moment.

Json Encode Mapping

The tuple parser works just like the json parser except it takes erlang tuples. The only caveat is that when it encounters atoms it converts them to native atoms. However, it only does this if the atom is already in the atom table. This could cause problems if you try to parse arbitrary tuples.