reworked api, renamed decoder to parser, added types and function specs for exported functions

src/jsx.erl

@@ -21,34 +21,52 @@
 %% THE SOFTWARE.
 
 
+
 -module(jsx).
 -author("alisdairsullivan@yahoo.ca").
 
--export([decode/1, decoder/0, decoder/1, decoder/2, detect_encoding/4]).
+-export([decode/1, decode/2, parser/0, parser/1, parser/2]).
+
+-include("jsx_types.hrl").
+
+
+
+-spec decode(JSON::json()) -> {ok, [jsx_event(),...]} | {error, badjson}.
+-spec decode(JSON::json(), Opts::[any()]) -> {ok, [jsx_event(),...]} | {error, badjson}.
 
 decode(JSON) ->
-    F = decoder(),
+    decode(JSON, []).
+
+decode(JSON, Opts) ->
+    F = parser(Opts),
     case F(JSON) of
         {incomplete, _} -> {error, badjson}
         ; {error, badjson} -> {error, badjson}
         ; {Result, _} -> {ok, Result}
-    end. 
+    end.
+    
 
-decoder() ->
-    decoder([]).
+-spec parser() -> jsx_parser().
+-spec parser(Opts::[any()]) -> jsx_parser().
+-spec parser(Callbacks::{fun((jsx_event(), any()) -> any())}, Opts::[any()]) -> jsx_parser()
+    ; (Callbacks::{atom(), atom(), any()}, Opts::[any()]) -> jsx_parser().
 
-decoder(Opts) ->
+parser() ->
+    parser([]).
+
+parser(Opts) ->
     F = fun(end_of_json, State) -> lists:reverse(State) 
             ; (reset, _State) -> []
             ; (Event, State) -> [Event] ++ State
         end,
-    decoder({F, []}, Opts).
+    parser({F, []}, Opts).
 
-decoder({F, _} = Callbacks, OptsList) when is_list(OptsList), is_function(F) ->
+parser({F, _} = Callbacks, OptsList) when is_list(OptsList), is_function(F) ->
     start(Callbacks, OptsList);
-decoder({Mod, Fun, State}, OptsList) when is_list(OptsList), is_atom(Mod), is_atom(Fun) ->
+parser({Mod, Fun, State}, OptsList) when is_list(OptsList), is_atom(Mod), is_atom(Fun) ->
     start({fun(E, S) -> Mod:Fun(E, S) end, State}, OptsList).
 
+
 start(Callbacks, OptsList) ->
     F = case proplists:get_value(encoding, OptsList, auto) of
         utf8 -> fun jsx_utf8:start/4
@@ -56,7 +74,7 @@ start(Callbacks, OptsList) ->
         ; utf32 -> fun jsx_utf32:start/4
         ; {utf16, little} -> fun jsx_utf16le:start/4
         ; {utf32, little} -> fun jsx_utf32le:start/4
-        ; auto -> fun jsx:detect_encoding/4
+        ; auto -> fun detect_encoding/4
     end,
     start(Callbacks, OptsList, F).
     
@@ -64,6 +82,7 @@ start(Callbacks, OptsList, F) ->
     Opts = parse_opts(OptsList),
     fun(Stream) -> F(Stream, [], Callbacks, Opts) end.
 
+
 parse_opts(Opts) ->
     parse_opts(Opts, {false, codepoint, false}).
 

src/jsx_types.hrl

@@ -0,0 +1,55 @@
+%% The MIT License
+
+%% Copyright (c) 2010 Alisdair Sullivan <alisdairsullivan@yahoo.ca>
+
+%% Permission is hereby granted, free of charge, to any person obtaining a copy
+%% of this software and associated documentation files (the "Software"), to deal
+%% in the Software without restriction, including without limitation the rights
+%% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+%% copies of the Software, and to permit persons to whom the Software is
+%% furnished to do so, subject to the following conditions:
+
+%% The above copyright notice and this permission notice shall be included in
+%% all copies or substantial portions of the Software.
+
+%% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+%% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+%% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+%% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+%% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+%% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+%% THE SOFTWARE.
+
+
+%% unsure of how to specify a binary with a complex structure like utfx encoded
+%%   binaries. this should be further limited somehow probably.
+
+-type json() :: binary().
+
+
+%% events emitted by the parser and component types
+
+-type unicode_codepoint() :: 0..16#10ffff.
+-type unicode_string() :: [unicode_codepoint()].
+
+-type jsx_event() :: start_object
+    | end_object
+    | start_array
+    | end_array
+    | end_of_json
+    | reset
+    | {key, unicode_string()}
+    | {string, unicode_string()}
+    | {integer, unicode_string()}
+    | {float, unicode_string()}
+    | {literal, true}
+    | {literal, false}
+    | {literal, null}.
+    
+    
+%% this probably doesn't work properly
+
+-type jsx_parser() :: fun((json()) -> {[jsx_event(),...], jsx_parser()} 
+    | {incomplete, jsx_parser()}
+    | {error, badjson}
+).