zf

zenflows testing
git clone https://s.sonu.ch/~srfsh/zf.git
Log | Files | Refs | Submodules | README | LICENSE

README.md (4692B)

      1 # Jason
      2 
      3 A blazing fast JSON parser and generator in pure Elixir.
      4 
      5 The parser and generator are at least twice as fast as other Elixir/Erlang libraries
      6 (most notably `Poison`).
      7 The performance is comparable to `jiffy`, which is implemented in C as a NIF.
      8 Jason is usually only twice as slow.
      9 
     10 Both parser and generator fully conform to
     11 [RFC 8259](https://tools.ietf.org/html/rfc8259) and
     12 [ECMA 404](http://www.ecma-international.org/publications/standards/Ecma-404.htm)
     13 standards. The parser is tested using [JSONTestSuite](https://github.com/nst/JSONTestSuite).
     14 
     15 ## Installation
     16 
     17 The package can be installed by adding `jason` to your list of dependencies
     18 in `mix.exs`:
     19 
     20 ```elixir
     21 def deps do
     22   [{:jason, "~> 1.3"}]
     23 end
     24 ```
     25 
     26 ## Basic Usage
     27 
     28 ``` elixir
     29 iex(1)> Jason.encode!(%{"age" => 44, "name" => "Steve Irwin", "nationality" => "Australian"})
     30 "{\"age\":44,\"name\":\"Steve Irwin\",\"nationality\":\"Australian\"}"
     31 
     32 iex(2)> Jason.decode!(~s({"age":44,"name":"Steve Irwin","nationality":"Australian"}))
     33 %{"age" => 44, "name" => "Steve Irwin", "nationality" => "Australian"}
     34 ```
     35 
     36 Full documentation can be found at [https://hexdocs.pm/jason](https://hexdocs.pm/jason).
     37 
     38 ## Use with other libraries
     39 
     40 ### Postgrex
     41 
     42 Versions starting at 0.14.0 use `Jason` by default. For earlier versions, please refer to
     43 [previous versions of this document](https://github.com/michalmuskala/jason/tree/v1.1.2#postgrex).
     44 
     45 ### Ecto
     46 
     47 Versions starting at 3.0.0 use `Jason` by default. For earlier versions, please refer to
     48 [previous versions of this document](https://github.com/michalmuskala/jason/tree/v1.1.2#ecto).
     49 
     50 ### Plug (and Phoenix)
     51 
     52 Phoenix starting at 1.4.0 uses `Jason` by default. For earlier versions, please refer to
     53 [previous versions of this document](https://github.com/michalmuskala/jason/tree/v1.1.2#plug-and-phoenix).
     54 
     55 ### Absinthe
     56 
     57 You need to pass the `:json_codec` option to `Absinthe.Plug`
     58 
     59 ```elixir
     60 # When called directly:
     61 plug Absinthe.Plug,
     62   schema: MyApp.Schema,
     63   json_codec: Jason
     64 
     65 # When used in phoenix router:
     66 forward "/api",
     67   to: Absinthe.Plug,
     68   init_opts: [schema: MyApp.Schema, json_codec: Jason]
     69 ```
     70 
     71 ## Benchmarks
     72 
     73 Detailed benchmarks (including memory measurements):
     74 https://gist.github.com/michalmuskala/4d64a5a7696ca84ac7c169a0206640d5
     75 
     76 HTML reports for the benchmark (only performance measurements):
     77 http://michal.muskala.eu/jason/decode.html and http://michal.muskala.eu/jason/encode.html
     78 
     79 ### Running
     80 
     81 Benchmarks against most popular Elixir & Erlang json libraries can be executed after
     82 going into the `bench/` folder and then executing `mix bench.encode` and `mix bench.decode`.
     83 A HTML report of the benchmarks (after their execution) can be found in
     84 `bench/output/encode.html` and `bench/output/decode.html` respectively.
     85 
     86 ## Differences to Poison
     87 
     88 Jason has a couple feature differences compared to Poison.
     89 
     90   * Jason follows the JSON spec more strictly, for example it does not allow
     91     unescaped newline characters in JSON strings - e.g. `"\"\n\""` will
     92     produce a decoding error.
     93   * no support for decoding into data structures (the `as:` option).
     94   * no built-in encoders for `MapSet`, `Range` and `Stream`.
     95   * no support for encoding arbitrary structs - explicit implementation
     96     of the `Jason.Encoder` protocol is always required.
     97   * different pretty-printing customisation options (default `pretty: true` works the same)
     98 
     99 If you require encoders for any of the unsupported collection types, I suggest
    100 adding the needed implementations directly to your project:
    101 
    102 ```elixir
    103 defimpl Jason.Encoder, for: [MapSet, Range, Stream] do
    104   def encode(struct, opts) do
    105     Jason.Encode.list(Enum.to_list(struct), opts)
    106   end
    107 end
    108 ```
    109 
    110 If you need to encode some struct that does not implement the protocol,
    111 if you own the struct, you can derive the implementation specifying
    112 which fields should be encoded to JSON:
    113 
    114 ```elixir
    115 @derive {Jason.Encoder, only: [....]}
    116 defstruct # ...
    117 ```
    118 
    119 It is also possible to encode all fields, although this should be
    120 used carefully to avoid accidentally leaking private information
    121 when new fields are added:
    122 
    123 ```elixir
    124 @derive Jason.Encoder
    125 defstruct # ...
    126 ```
    127 
    128 Finally, if you don't own the struct you want to encode to JSON,
    129 you may use `Protocol.derive/3` placed outside of any module:
    130 
    131 ```elixir
    132 Protocol.derive(Jason.Encoder, NameOfTheStruct, only: [...])
    133 Protocol.derive(Jason.Encoder, NameOfTheStruct)
    134 ```
    135 
    136 ## License
    137 
    138 Jason is released under the Apache License 2.0 - see the [LICENSE](LICENSE) file.
    139 
    140 Some elements of tests and benchmarks have their origins in the
    141 [Poison library](https://github.com/devinus/poison) and were initially licensed under [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/).