Commit fe418b88 authored by Ralf Treinen's avatar Ralf Treinen

New upstream version 3.0

parents
*.native
*.byte
*.docdir
_build
*.install
pkg/META
PKG compiler-libs.common ppx_deriving.api ppx_import oUnit yojson result ppx_tools.metaquot
language: c
env:
- OCAML=4.02.3
- OCAML=4.03.0
script:
- echo "yes" | sudo add-apt-repository ppa:avsm/ppa
- sudo apt-get update -qq
- sudo apt-get install -qq opam
- export OPAMYES=1
- opam init
- opam switch $OCAML
- eval `opam config env`
- opam pin add -n -k path ppx_deriving_yojson .
- opam install --deps-only -d -t ppx_deriving_yojson
- opam install -d -t -v ppx_deriving_yojson
Changelog
=========
3.0
---
* Use Result.result in generated code.
* Compatibility with statically linked ppx drivers.
2.3
---
* Adapt to syntactic changes in 4.02.2.
* Improve compatibility with libraries that shadow modules
from standard library, such as Core.
* Allow deserializing float values that appear as integer
literals in the input JSON.
* Suppress some warnings.
2.2
---
* Add support for open types.
2.1
---
* Handle inheriting from a parametric polymorphic variant type.
* Don't leak type variables.
2.0
---
* Update to accomodate syntactic changes in _deriving_ 1.0.
* Common helper functions have been extracted into
ppx_deriving_yojson.runtime, reducing code size.
* Add support for `[@@deriving to_yojson, of_yojson]`
and `[%to_yojson:]`, `[%of_yojson:]` shortcuts.
* Add support for `[@@deriving yojson { strict = false }]`.
1.1
---
* Add `[@key]`, `[@name]` and `[@default]` attributes.
* Add support for `Yojson.Safe.json` values.
1.0
---
* Initial release.
Copyright (c) 2014-2016 whitequark <whitequark@whitequark.org>
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.
build:
cp pkg/META.in pkg/META
ocaml pkg/build.ml native=true native-dynlink=true
test: build
rm -rf _build/src_test/
ocamlbuild -j 0 -use-ocamlfind -classic-display \
src_test/test_ppx_yojson.byte --
doc:
ocamlbuild -use-ocamlfind doc/api.docdir/index.html \
-docflags -t -docflag "API reference for ppx_deriving_yojson" \
-docflags '-colorize-code -short-functors -charset utf-8' \
-docflags '-css-style style.css'
cp doc/style.css api.docdir/
clean:
ocamlbuild -clean
.PHONY: build test doc clean
gh-pages: doc
git clone `git config --get remote.origin.url` .gh-pages --reference .
git -C .gh-pages checkout --orphan gh-pages
git -C .gh-pages reset
git -C .gh-pages clean -dxf
cp -t .gh-pages/ api.docdir/*
git -C .gh-pages add .
git -C .gh-pages commit -m "Update Pages"
git -C .gh-pages push origin gh-pages -f
rm -rf .gh-pages
VERSION := $$(opam query --version)
NAME_VERSION := $$(opam query --name-version)
ARCHIVE := $$(opam query --archive)
release:
git tag -a v$(VERSION) -m "Version $(VERSION)."
git push origin v$(VERSION)
opam publish prepare $(NAME_VERSION) $(ARCHIVE)
opam publish submit $(NAME_VERSION)
rm -rf $(NAME_VERSION)
.PHONY: gh-pages release
[@@deriving yojson]
===================
_deriving Yojson_ is a [ppx_deriving][pd] plugin that generates
[JSON][] serializers and deserializes that use the [Yojson][] library
from an OCaml type definition.
Sponsored by [Evil Martians](http://evilmartians.com).
[pd]: https://github.com/whitequark/ppx_deriving
[json]: http://tools.ietf.org/html/rfc4627
[yojson]: http://mjambon.com/yojson.html
Installation
------------
_deriving Yojson_ can be installed via [OPAM](https://opam.ocaml.org):
$ opam install ppx_deriving_yojson
Usage
-----
In order to use _deriving yojson_, require the package `ppx_deriving_yojson`.
Syntax
------
_deriving yojson_ generates two functions per type:
``` ocaml
# #require "ppx_deriving";;
# type ty = .. [@@deriving yojson];;
val ty_of_yojson : Yojson.Safe.json -> (ty, string) Result.result
val ty_to_yojson : ty -> Yojson.Safe.json
```
When the deserializing function returns <code>\`Error loc</code>, `loc` points to the point in the JSON hierarchy where the error has occurred.
It is possible to generate only serializing or deserializing functions by using `[@@deriving to_yojson]` or `[@@deriving of_yojson]`. It is also possible to generate an expression for serializing or deserializing a type by using `[%to_yojson:]` or `[%of_yojson:]`; non-conflicting versions `[%derive.to_yojson:]` or `[%derive.of_yojson:]` are available as well.
If the type is called `t`, the functions generated are `{of,to}_yojson` instead of `t_{of,to}_yojson`.
Semantics
---------
_deriving yojson_ handles tuples, records, normal and polymorphic variants; builtin types: `int`, `int32`, `int64`, `nativeint`, `float`, `bool`, `char`, `string`, `bytes`, `ref`, `list`, `array`, `option` and their `Mod.t` aliases.
The following table summarizes the correspondence between OCaml types and JSON values:
| OCaml type | JSON value | Remarks |
| ---------------------- | ---------- | -------------------------------- |
| `int`, `int32`, `float`| Number | |
| `int64`, `nativeint` | Number | Can exceed range of `double` |
| `bool` | Boolean | |
| `string`, `bytes` | String | |
| `char` | String | Strictly one character in length |
| `list`, `array` | Array | |
| `ref` | 'a | |
| `option` | Null or 'a | |
| A record | Object | |
| `Yojson.Safe.json` | any | Identity transformation |
Variants (regular and polymorphic) are represented using arrays; the first element is a string with the name of the constructor, the rest are the arguments. Note that the implicit tuple in a polymorphic variant is flattened. For example:
``` ocaml
# type pvs = [ `A | `B of int | `C of int * string ] list [@@deriving yojson];;
# type v = A | B of int | C of int * string [@@deriving yojson];;
# type vs = v list [@@deriving yojson];;
# print_endline (Yojson.Safe.to_string (vs_to_yojson [A; B 42; C (42, "foo")]));;
[["A"],["B",42],["C",42,"foo"]]
# print_endline (Yojson.Safe.to_string (pvs_to_yojson [`A; `B 42; `C (42, "foo")]));;
[["A"],["B",42],["C",42,"foo"]]
```
By default, objects are deserialized strictly; that is, all keys in the object have to correspond to fields of the record. Passing `strict = false` as an option to the deriver (i.e. `[@@deriving yojson { strict = false }]`) changes the behavior to ignore any unknown fields.
### Options
Option attribute names may be prefixed with `yojson.` to avoid conflicts with other derivers.
#### [@key]
If the JSON object keys differ from OCaml conventions, lexical or otherwise, it is possible to specify the corresponding JSON key implicitly using <code>[@key "field"]</code>, e.g.:
``` ocaml
type geo = {
lat : float [@key "Latitude"];
lon : float [@key "Longitude"];
}
[@@deriving yojson]
```
#### [@name]
If the JSON variant names differ from OCaml conventions, it is possible to specify the corresponding JSON string explicitly using <code>[@name "constr"]</code>, e.g.:
``` ocaml
type units =
| Metric [@name "metric"]
| Imperial [@name "imperial"]
[@@deriving yojson]
```
#### [@encoding]
Very large `int64` and `nativeint` numbers can wrap when decoded in a runtime which represents all numbers using double-precision floating point, e.g. JavaScript and Lua. It is possible to specify the <code>[@encoding \`string]</code> attribute to encode them as strings.
#### [@default]
It is possible to specify a default value for fields that can be missing from the JSON object, e.g.:
``` ocaml
type pagination = {
pages : int;
current : (int [@default 0]);
} [@@deriving yojson]
```
Fields with default values are not required to be present in inputs and will not be emitted in outputs.
License
-------
_deriving yojson_ is distributed under the terms of [MIT license](LICENSE.txt).
true: warn(@5@8@10@11@12@14@23@24@26@29@40), bin_annot, safe_string, cppo_V_OCAML
"src": include
<src/*.{ml,mli,byte,native}>: package(ppx_tools.metaquot), package(ppx_deriving.api), package(result)
<src_test/*.{ml,byte,native}>: debug, package(result), package(oUnit), package(yojson), use_yojson
JSON codec generator for OCaml >=4.02
ppx_deriving_yojson is a ppx_deriving plugin that provides
a JSON codec generator.
open Ocamlbuild_plugin
let () = dispatch (fun phase ->
Ocamlbuild_cppo.dispatcher phase;
match phase with
| After_rules ->
let ppx_deriving_component deriver =
(Findlib.query "ppx_deriving").Findlib.location ^ "/" ^ deriver
in
flag ["ocaml"; "compile"; "use_yojson"] &
S[A"-ppx"; A"ocamlfind ppx_import/ppx_import";
A"-ppx"; A("ocamlfind ppx_deriving/ppx_deriving "^
"src/ppx_deriving_yojson.cma "^
(ppx_deriving_component "ppx_deriving_show.cma"));
A"-I"; A(ppx_deriving_component "")];
flag ["ocaml"; "link"; "use_yojson"; "byte"] &
A(ppx_deriving_component "ppx_deriving_runtime.cma");
flag ["ocaml"; "link"; "use_yojson"; "native"] &
A(ppx_deriving_component "ppx_deriving_runtime.cmxa");
ocaml_lib ~dir:"src" "src/ppx_deriving_yojson_runtime";
| _ -> ())
opam-version: "1.2"
name: "ppx_deriving_yojson"
version: "3.0"
maintainer: "whitequark <whitequark@whitequark.org>"
authors: [ "whitequark <whitequark@whitequark.org>" ]
license: "MIT"
homepage: "https://github.com/whitequark/ppx_deriving_yojson"
doc: "http://whitequark.github.io/ppx_deriving_yojson"
bug-reports: "https://github.com/whitequark/ppx_deriving_yojson/issues"
dev-repo: "git://github.com/whitequark/ppx_deriving_yojson.git"
tags: [ "syntax" "json" ]
substs: [ "pkg/META" ]
build: [
"ocaml" "pkg/build.ml" "native=%{ocaml-native}%"
"native-dynlink=%{ocaml-native-dynlink}%"
]
build-test: [
"ocamlbuild" "-classic-display" "-use-ocamlfind" "src_test/test_ppx_yojson.byte" "--"
]
depends: [
"yojson"
"result"
"ppx_deriving" {>= "4.0" & < "5.0"}
"ocamlfind" {build}
"cppo" {build}
"ounit" {test}
"ppx_import" {test & >= "1.1"}
]
version = "%{version}%"
description = "[@@deriving yojson]"
requires(-ppx_driver) = "ppx_deriving ppx_deriving_yojson.runtime"
ppxopt(-ppx_driver,-custom_ppx) = "ppx_deriving,./ppx_deriving_yojson.cma"
requires(ppx_driver) = "ppx_deriving.api"
archive(ppx_driver, byte) = "ppx_deriving_yojson.cma"
archive(ppx_driver, native) = "ppx_deriving_yojson.cmxa"
exists_if = "ppx_deriving_yojson.cma"
package "runtime" (
version = "%{version}%"
description = "Runtime components of [@@deriving yojson]"
requires = "yojson result"
archive(byte) = "ppx_deriving_yojson_runtime.cma"
archive(byte, plugin) = "ppx_deriving_yojson_runtime.cma"
archive(native) = "ppx_deriving_yojson_runtime.cmxa"
archive(native, plugin) = "ppx_deriving_yojson_runtime.cmxs"
exists_if = "ppx_deriving_yojson_runtime.cma"
)
#!/usr/bin/env ocaml
#directory "pkg"
#use "topkg.ml"
let ocamlbuild =
"ocamlbuild -use-ocamlfind -classic-display -plugin-tag 'package(cppo_ocamlbuild)'"
let () =
Pkg.describe "ppx_deriving_yojson" ~builder:(`Other (ocamlbuild, "_build")) [
Pkg.lib "pkg/META";
Pkg.lib ~exts:Exts.library "src/ppx_deriving_yojson";
Pkg.lib ~exts:Exts.module_library "src/ppx_deriving_yojson_runtime";
Pkg.doc "README.md";
Pkg.doc "LICENSE.txt";
Pkg.doc "CHANGELOG.md"; ]
This diff is collapsed.
This diff is collapsed.
include Ppx_deriving_runtime
let (>>=) x f =
match x with Result.Ok x -> f x | (Result.Error _) as x -> x
let (>|=) x f =
x >>= fun x -> Result.Ok (f x)
let rec map_bind f acc xs =
match xs with
| x :: xs -> f x >>= fun x -> map_bind f (x :: acc) xs
| [] -> Result.Ok (List.rev acc)
type 'a error_or = ('a, string) Result.result
type 'a error_or = ('a, string) Result.result
val ( >>= ) : 'a error_or -> ('a -> 'b error_or) -> 'b error_or
val ( >|= ) : 'a error_or -> ('a -> 'b) -> 'b error_or
val map_bind : ('a -> 'b error_or) -> 'b list -> 'a list -> 'b list error_or
module List : (module type of List)
module String : (module type of String)
module Bytes : (module type of Bytes)
module Int32 : (module type of Int32)
module Int64 : (module type of Int64)
module Nativeint : (module type of Nativeint)
module Array : (module type of Array)
module Result : sig
type ('a, 'b) result = ('a, 'b) Result.result =
| Ok of 'a
| Error of 'b
end
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment