git.iko.soy/rowtype-yoga/purescript-arraybuffer-builder
on v1.0.0 help sign in
rowtype-yoga/purescript-arraybuffer-builder/README.md
105 lines 4.0 kB history raw
1# purescript-arraybuffer-builder
3[![CI](https://github.com/jamesdbrock/purescript-arraybuffer-builder/workflows/CI/badge.svg?branch=master)](https://github.com/jamesdbrock/purescript-arraybuffer-builder/actions)
4[![Pursuit](http://pursuit.purescript.org/packages/purescript-arraybuffer-builder/badge)](http://pursuit.purescript.org/packages/purescript-arraybuffer-builder/)
6`ArrayBuffer` serialization in the “builder monoid” and “builder monad” style.
7In this style, we build up serialized data structures by `append`ing to
8a monoid in a Writer monad with do-notation. This style of serialization
9has been used for a long time and we [insist that it works really well](https://wiki.haskell.org/Do_notation_considered_harmful#Library_design).
11This package provides a `Builder` monoid and a `PutM` monad which are roughly
12equivalent to types of the same name in the Haskell
13[`Data.Binary.Put`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html)
14module.
16This package defines
17[no typeclasses](http://code.slipthrough.net/2018/03/13/thoughts-on-typeclass-codecs/).
18Typeclass-based
19serialization/deserialization generally assumes that we are round-tripping
20some data structures out to storage and then back into our program.
21This package is designed for the case in which we are serializing some data
22to be sent to another program which expects a serialization format
23that we don't control.
25## Usage Examples
27All `ArrayBuffer` building must occur in `Effect`.
29### Serialize an integer
31Create a two-byte `arraybuffer :: ArrayBuffer` which contains the number *-10* encoded as big-endian 16-bit two’s-complement.
32```purescript
33do
34 arraybuffer <- execPut $ putInt16be (-10)
35```
37### Serialize three floats
39Create a 24-byte `arraybuffer :: ArrayBuffer` which contains three big-endian
40IEEE-754 double-precision floats.
42```purescript
43do
44 arraybuffer <- execPut $ do
45 putFloat64be 1.0
46 putFloat64be 2.0
47 putFloat64be 3.0
48```
50### Serialize a `String` as UTF8
52Encode a `String` as UTF8 with a length prefix.
54We give this as an example, rather than supporting it in the library, because
55it depends on
56[`Data.TextEncoding.encodeUtf8`](https://pursuit.purescript.org/packages/purescript-text-encoding/docs/Data.TextEncoding#v:encodeUtf8).
58```purescript
59putStringUtf8 :: forall m. (MonadEffect m) => String -> PutM m Unit
60putStringUtf8 s = do
61 let stringbuf = Data.ArrayBuffer.Typed.buffer $ Data.TextEncoding.encodeUtf8 s
62 -- Put a 32-bit big-endian length prefix for the length of the utf8 string, in bytes.
63 putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
64 putArrayBuffer stringbuf
66do
67 arraybuffer <- execPut $ putStringUtf8 "BLM"
68```
70### Serialize an `Array Int`
72Encode an `Array Int` with a length prefix in a
73way that's compatible with the
74[`Binary` instance for `[Int32]`](https://hackage.haskell.org/package/binary/docs/Data-Binary.html#t:Binary)
75from the Haskell
76[__binary__](https://hackage.haskell.org/package/binary)
77library.
79```purescript
80putArrayInt32 :: forall m. (MonadEffect m) => Array Int -> PutM m Unit
81putArrayInt32 xs = do
82 -- Put a 64-bit big-endian length prefix for the length of the array.
83 putUint32be 0
84 putUint32be $ Data.Uint.fromInt $ Data.Array.length xs
85 traverse_ putInt32be xs
87do
88 arraybuffer <- execPut $ putArrayInt32 [1,2,3]
89```
91## Deserialization
93This package is only for writing `ArrayBuffer`s, not reading them.
94See
95[__purescript-parsing-dataview__](https://pursuit.purescript.org/packages/purescript-parsing-dataview/)
96for a way to deserialize from `ArrayBuffer` back to Purescript data.
98## References
100* [MDN `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
102## Alternative packages for serializing to an `ArrayBuffer`
104* [__purescript-node-buffer__](https://pursuit.purescript.org/packages/purescript-node-buffer)
105* [__purescript-arraybuffer-class__](https://pursuit.purescript.org/packages/purescript-arraybuffer-class)