Merge pull request #60 from msgpack/new-option-style

New option style

Author: kuenishi

README.md

@@ -4,10 +4,10 @@
 
 [![Drone.io](https://drone.io/github.com/msgpack/msgpack-erlang/status.png)](https://drone.io/github.com/msgpack/msgpack-erlang)
 
-## prequisites for runtime
+## Prerequisites for runtime
 
-[Erlang/OTP](http://erlang.org/), >= 17.0
-Also based on [the new msgpack spec 232a0d](https://github.com/msgpack/msgpack/blob/232a0d14c6057000cc4a478f0dfbb5942ac54e9e/spec.md).
+[Erlang/OTP](http://erlang.org/), >= 17.0 Also based on
+[the new msgpack spec 0b8f5a](https://github.com/msgpack/msgpack/blob/0b8f5ac67cdd130f4d4d4fe6afb839b989fdb86a/spec.md).
 
 ## edit rebar.config to use in your application
 
@@ -18,6 +18,14 @@ Also based on [the new msgpack spec 232a0d](https://github.com/msgpack/msgpack/b
 ]}.
 ```
 
+Or as it is [now published at hex.pm](https://hex.pm/packages/msgpack), just
+
+```erlang
+{deps, [msgpack]}.
+```
+
+might work.
+
 ## Simple deserialization
 
 ```erlang
@@ -33,35 +41,95 @@ Ham = msgpack:pack(Spam),
 ...
 ```
 
-## String type
+## Options, for packing and unpacking
 
-Now this supports string type!
+### `{spec, new|old}`
+
+Both for packing and unpacking. Default is `new`. Major difference
+between old and new spec is:
+
+- raw family (`0xa0~0xbf`, `0xda`, `0xdb`) becomes new str family
+- `0xd9` is new as str8
+- new bin space (`0xc4, 0xc5, 0xc6` as bin8, bin16, bin32)
+- new ext space (`0xc7, 0xc8, 0xc9` as ext8, ext16, ext32)
+- new fixext space (`0xd4, 0xd5, 0xd6, 0xd7, 0xd8` as fixext1, fixext2, fixext4, fixext8, fixext16),
+
+The default is new spec. Old spec mode does not handle these new types but
+returns error. To use
+[old spec](https://github.com/msgpack/msgpack/blob/master/spec-old.md)
+mode, this option is explicitly added.
 
 ```erlang
-Opt = [{enable_str, true}]
-{ok, "埼玉"} = msgpack:unpack(msgpack:pack("埼玉", Opt), Opt).
- => {ok,[22524,29577]}
+OldHam = msgpack:pack(Spam, [{spec, old}]),
+{ok, Spam} = msgpack:unpack(OldHam, [{spec, old}]).
 ```
 
-There are several options for `msgpack:pack/2` and `msgpack:unpack/2` .
-See `msgpack:options()` in `msgpack.hrl`.
+### `{allow_atom, none|pack}`
 
-## Map Style
+Only in packing. Atoms are packed as binaries. Default value is `pack`.
+Otherwise, any term including atoms throws badarg.
 
-Since Erlang/OTP 17.0
+### `{known_atoms, [atom()]}`
+
+Both in packing and unpacking. In packing, if an atom is in this list
+a binary is encoded as a binary. In unpacking, msgpacked binaries are
+decoded as atoms with `erlang:binary_to_existing_atom/2` with encoding
+`utf8`. Default value is an empty list.
+
+Even if `allow_atom` is `none`, known atoms are packed.
+
+### `{unpack_str, as_binary|as_list}`
+
+A switch to choose decoded term style of `str` type when *unpacking*.
+Only available at new spec. Default is `as_list`.
 
-```erlang
-msgpack:pack(#{ <<"key">> => <<"value">> }, [{format, map}]).
 ```
+mode        as_binary    as_list
+-----------+------------+-------
+bin         binary()     binary()
+str         binary()     string()
+```
+
+### `{validate_string, boolean()}`
 
-Or use old jiffy/jsx style
+Only in unpacking, UTF-8 validation at unpacking from `str` type will
+be enabled. Default value is `false`.
+
+### `{pack_str, from_binary|from_list|none}`
+
+A switch to choose packing of `string()` when packing. Only available
+at new spec. Default is `from_list` for symmetry with `unpack_str`
+option.
+
+```
+mode        from_list    from_binary    none
+-----------+------------+--------------+-----------------
+binary()    bin          str*/bin       bin
+string()    str*/array   array of int   array of int
+list()      array        array          array
+```
+
+But the default option pays the cost of performance for symmetry. If
+the overhead of UTF-8 validation is unacceptable, choosing `none` as
+the option would be the best.
+
+- \* Tries to pack as `str` if it is a valid `string()`.
+
+### `{map_format, maps|jiffy|jsx}`
+
+Both at packing and unpacking. Default value is `maps`.
 
 ```erlang
+msgpack:pack(#{ <<"key">> => <<"value">> }, []).
 msgpack:pack({[{<<"key">>, <<"value">>}]}, [{format, jiffy}]),
 msgpack:pack([{<<"key">>, <<"value">>}], [{format, jsx}]).
 ```
 
-## Ext type
+
+### `{ext, {msgpack_ext_packer(), msgpack_ext_unpacker()}|module()}`
+
+At both. The default behaviour in case of facing ext data at decoding
+is to ignore them as its length is known.
 
 Now msgpack-erlang supports ext type. Now you can serialize everything
 with your original (de)serializer. That will enable us to handle
@@ -76,29 +144,17 @@ Opt = [{ext,{Packer,Unpacker}}],
 {ok, {ref, Ref}} = msgpack:unpack(msgpack:pack({ref, Ref}, Opt), Opt).
 ```
 
-This is still experimental feature, so I'm waiting for your feedback.
-
-## Compatibility mode
-
-To use as same with [old spec](https://github.com/msgpack/msgpack/blob/master/spec-old.md):
-
-```erlang
-OldHam = msgpack:pack(Spam, [{enable_str,false}]),
-{ok, Spam} = msgpack:unpack(OldHam, [{enable_str,false}]).
-```
-
-Since 0.2.3 now it's **false by default**.
-
-## Further tests
-
-See [msgpack-erlang-tests](http://github.com/kuenishi/msgpack-erlang-tests) for further tests
-
 ## License
 
 Apache License 2.0
 
 # Release Notes
 
+## 0.5.0
+
+- Renewed optional arguments to pack/unpack interface. This is
+  incompatible change from 0.4 series.
+
 ## 0.4.0
 
 - Deprecate `nil`

include/msgpack.hrl

@@ -1,7 +1,7 @@
 %%
 %% MessagePack for Erlang
 %%
-%% Copyright (C) 2009-2013 UENISHI Kota
+%% Copyright (C) 2009-2016 UENISHI Kota
 %%
 %%    Licensed under the Apache License, Version 2.0 (the "License");
 %%    you may not use this file except in compliance with the License.
@@ -45,10 +45,32 @@
 
 -include("msgpack.hrl").
 
-%% for export
--export_type([object/0, msgpack_map/0, options/0]).
+-export_type([object/0, msgpack_map/0, options/0, ext_packer/0, ext_unpacker/0]).
 -type object() :: msgpack_term().
--type options() :: msgpack_list_options().
+
+-type options() :: 
+        [{spec, new|old} |
+         {allow_atom, none|pack} |
+         {known_atoms, [atom()]} |
+         {unpack_str, as_binary|as_list} |
+         {validate_string, boolean()} |
+         {pack_str, from_binary|from_list|none} |
+         {map_format, map|jiffy|jsx} |
+         {ext, {msgpack:ext_packer(), msgpack:ext_unpacker()} | module()}].
+
+-type opt_record() :: ?OPTION{}.
+-export_type([opt_record/0]).
+
+%% @doc ext_packer that packs only tuples with length > 2
+-type ext_packer()   :: fun((tuple(), msgpack:options()) ->
+                                   {ok, {Type::byte(), Data::binary()}} |
+                                   {error, any()}).
+-type ext_unpacker() ::
+        fun((byte(), binary(), msgpack:options()) ->
+                   {ok, msgpack_term()} | {error, any()})
+      | fun((byte(), binary()) ->
+                   {ok, msgpack_term()} | {error, any()}).
+
 
 -spec term_to_binary(term()) -> binary().
 term_to_binary(Term) ->
@@ -114,39 +136,43 @@ unpack_stream(Bin, Opts0) when is_binary(Bin) ->
 unpack_stream(Other, _) -> {error, {badarg, Other}}.
 
 %% @private
--spec parse_options(msgpack:options()) -> msgpack_option().
+-spec parse_options(msgpack:options()) -> ?OPTION{}.
 
 parse_options(Opt) ->
     parse_options(Opt, ?OPTION{original_list=Opt}).
 
 %% @private
--spec parse_options(msgpack:options(), msgpack_option()) -> msgpack_option().
+-spec parse_options(msgpack:options(), ?OPTION{}) -> ?OPTION{}.
 parse_options([], Opt) -> Opt;
 
-parse_options([jsx|TL], Opt0) ->
-    Opt = Opt0?OPTION{interface=jsx,
-                      map_unpack_fun=msgpack_unpacker:map_unpacker(jsx)},
-    parse_options(TL, Opt);
-parse_options([jiffy|TL], Opt0) ->
-    Opt = Opt0?OPTION{interface=jiffy,
-                      map_unpack_fun=msgpack_unpacker:map_unpacker(jiffy)},
-    parse_options(TL, Opt);
-parse_options([{format,Type}|TL], Opt0)
-  when Type =:= jsx; Type =:= jiffy; Type =:= map->
-    Opt = Opt0?OPTION{interface=Type,
-                      map_unpack_fun=msgpack_unpacker:map_unpacker(Type)},
-    parse_options(TL, Opt);
+parse_options([{spec, Spec}|T], Opt0) when Spec =:= new orelse Spec =:= old ->
+    parse_options(T, Opt0?OPTION{spec = Spec});
 
-parse_options([{allow_atom,Type}|TL], Opt0) ->
+parse_options([{allow_atom,Type}|T], Opt0) ->
     Opt = case Type of
               none -> Opt0?OPTION{allow_atom=none};
               pack -> Opt0?OPTION{allow_atom=pack}
           end,
-    parse_options(TL, Opt);
+    parse_options(T, Opt);
 
-parse_options([{enable_str,Bool}|TL], Opt0) ->
-    Opt = Opt0?OPTION{enable_str=Bool},
-    parse_options(TL, Opt);
+parse_options([{known_atoms, Atoms}|T], Opt0) when is_list(Atoms) ->
+    parse_options(T, Opt0?OPTION{known_atoms=Atoms});
+
+parse_options([{unpack_str, As}|T], Opt0) when As =:= as_binary orelse As =:= as_list ->
+    parse_options(T, Opt0?OPTION{unpack_str=As});
+
+parse_options([{validate_string, Bool}|T], Opt) when is_boolean(Bool) ->
+    parse_options(T, Opt?OPTION{validate_string=Bool});
+
+parse_options([{pack_str, From}|T], Opt)
+  when From =:= from_binary orelse From =:= from_list orelse From =:= none ->
+    parse_options(T, Opt?OPTION{pack_str=From});
+
+parse_options([{map_format,Type}|T], Opt0)
+  when Type =:= jsx; Type =:= jiffy; Type =:= map ->
+    Opt = Opt0?OPTION{map_format=Type,
+                      map_unpack_fun=msgpack_unpacker:map_unpacker(Type)},
+    parse_options(T, Opt);
 
 parse_options([{ext, Module}|TL], Opt0) when is_atom(Module) ->
     Opt = Opt0?OPTION{ext_packer=fun Module:pack_ext/2,
@@ -200,10 +226,10 @@ test_data()->
 -endif.
 
 enable_str_test() ->
-    ?assertEqual(<<167:8, (<<"saitama">>)/binary >>,
-                 msgpack:pack(<<"saitama">>, [{enable_str, false}])),
-    ?assertEqual(<<196,7,115,97,105,116,97,109,97>>,
-                 msgpack:pack(<<"saitama">>, [{enable_str, true}])).
+    ?assertEqual(<<167:8, "saitama">>,
+                 msgpack:pack(<<"saitama">>, [{spec,old}])),
+    ?assertEqual(<<2#101:3, 7:5, "saitama">>, %% binary becomes str8 from_binary
+                 msgpack:pack(<<"saitama">>, [{spec,new},{pack_str,from_binary}])).
 
 basic_test()->
     Tests = test_data(),
@@ -240,9 +266,9 @@ other_test()->
     ?assertEqual({error,incomplete},msgpack:unpack(<<>>)).
 
 error_test()->
-    ?assertEqual({error,{badarg, atom}}, msgpack:pack(atom)),
+    ?assertEqual({error,{badarg, atom}}, msgpack:pack(atom, [{allow_atom, none}])),
     Term = {"hoge", "hage", atom},
-    ?assertEqual({error,{badarg, Term}}, msgpack:pack(Term)).
+    ?assertEqual({error,{badarg, Term}}, msgpack:pack(Term, [{allow_atom, none}])).
 
 long_binary_test()->
     A = msgpack:pack(1),