97 lines
2.5 KiB
Markdown
97 lines
2.5 KiB
Markdown
# Faraday
|
|
|
|
Faraday is a library for writing fast and memory-efficient serializers. Its
|
|
core type and related operation gives the user fine-grained control over
|
|
copying and allocation behavior while serializing user-defined types, and
|
|
presents the output in a form that makes it possible to use vectorized write
|
|
operations, such as the [writev][] system call, or any other platform or
|
|
application-specific output APIs.
|
|
|
|
|
|
[](https://github.com/inhabitedtype/faraday/actions?query=workflow%3A%22build%22)
|
|
|
|
[writev]: http://man7.org/linux/man-pages/man2/writev.2.html
|
|
|
|
## Installation
|
|
|
|
Install the library and its depenencies via [OPAM][opam]:
|
|
|
|
[opam]: http://opam.ocaml.org/
|
|
|
|
```bash
|
|
opam install faraday
|
|
```
|
|
|
|
## Usage
|
|
|
|
Like its sister project [Angstrom][], Faraday is written with network protocols
|
|
and serialization formats in mind. As such, its source distribution inclues
|
|
implementations of various RFCs that are illustrative of real-world
|
|
applications of the library. This includes a [JSON serializer][json].
|
|
|
|
[angstrom]: https://github.com/inhabitedtype/angstrom
|
|
[json]: https://github.com/inhabitedtype/faraday/blob/master/examples/rFC7159.ml
|
|
|
|
In addition, it's appropriate here to include a serializer for the simple
|
|
arithmetic expression language described in Angstrom's README.
|
|
|
|
```ocaml
|
|
open Faraday
|
|
|
|
type 'a binop = [
|
|
| `Sub of 'a * 'a
|
|
| `Add of 'a * 'a
|
|
| `Div of 'a * 'a
|
|
| `Mul of 'a * 'a
|
|
]
|
|
;;
|
|
|
|
type t = [ `Num of int | t binop ]
|
|
|
|
let rec serialize ?(prec=0) t expr =
|
|
match expr with
|
|
| `Num n -> write_string t (Printf.sprintf "%d" n)
|
|
| #binop as binop ->
|
|
let prec', op, l, r =
|
|
match binop with
|
|
| `Sub(l, r) -> 2, '-', l, r
|
|
| `Add(l, r) -> 3, '+', l, r
|
|
| `Div(l, r) -> 4, '/', l, r
|
|
| `Mul(l, r) -> 5, '*', l, r
|
|
in
|
|
if prec' < prec then write_char t '(';
|
|
serialize t ~prec:prec' l;
|
|
write_char t op;
|
|
serialize t ~prec:prec' r;
|
|
if prec' < prec then write_char t ')'
|
|
|
|
let to_string expr =
|
|
let t = create 0x1000 in
|
|
serialize t expr;
|
|
serialize_to_string t
|
|
```
|
|
|
|
## Development
|
|
|
|
To install development dependencies, pin the package from the root of the
|
|
repository:
|
|
|
|
```bash
|
|
opam pin add -n faraday .
|
|
opam install --deps-only faraday
|
|
```
|
|
|
|
After this, you may install a development version of the library using the
|
|
install command as usual.
|
|
|
|
For building and running the tests during development, you will need to install
|
|
the `alcotest` package:
|
|
|
|
```bash
|
|
opam install alcotest
|
|
make test
|
|
```
|
|
|
|
## License
|
|
|
|
BSD3, see LICENSE file for its text.
|