git.iko.soy/rowtype-yoga/purescript-arraybuffer-builder
on master help sign in
docs
605e060James Brock
DEVELOPMENT.mdnew file+38
compare with master
unifiedsplit
@@ -0,0 +1,38 @@
1+# Development Notes
2+
3+All of the commands needed for development are in the `shell.nix` environment.
4+
5+```
6+$ nix-shell
7+```
8+
9+## Edit
10+
11+The `psc-ide` command is available for the [VS Code Purescript IDE extension](https://github.com/nwolverson/vscode-ide-purescript.git).
12+
13+```
14+[nix-shell:]$ code .
15+```
16+
17+## Build
18+
19+```
20+[nix-shell:]$ spago build
21+```
22+
23+## Test
24+
25+The test dependencies are specified seperately in `test.dhall`.
26+
27+```
28+[nix-shell:]$ spago -x test.dhall test
29+```
30+
31+## Publishing to Pursuit with `spago`
32+
33+[Publishing with `spago`](https://github.com/purescript/spago#publish-my-library).
34+
35+```
36+[nix-shell:]$ spago bump-version --no-dry-run major
37+[nix-shell:]$ node node_modules/pulp/index.js publish
38+```
README.md+75−1
@@ -1,3 +1,77 @@
1# purescript-arraybuffer-builder
1# purescript-arraybuffer-builder
2
2
3−run `nix-shell` and run `psc-package build`
3+`ArrayBuffer` serialization in the “builder monoid” and “builder monad” style.
4+In this style, we build up serialized data structures by `append`ing to
5+a monoid in a Writer monad with do-notation. This style of serialization
6+has been used for a long time and we [insist that it works really well]
7+(https://wiki.haskell.org/Do_notation_considered_harmful#Library_design).
8+
9+This package provides a `Builder` monoid and a `PutM` monad which are roughly
10+equivalent to types of the same name in the Haskell
11+[`Data.Binary.Put`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html)
12+module.
13+
14+This package defines no typeclasses. Typeclass-based
15+serialization/deserialization generally assumes that we are round-tripping
16+some data structures out to storage and then back into our program.
17+This package is designed for the case in which we are serializing some data
18+to be sent to another program which expects a serialization format
19+that we don't control.
20+
21+## Deserialization
22+
23+This package is only for writing `ArrayBuffer`s, not reading them.
24+See
25+[__purescript-parsing-dataview__](https://pursuit.purescript.org/packages/purescript-parsing-dataview/)
26+for a way to deserialize from `ArrayBuffer` back to Purescript data.
27+
28+## Usage Examples
29+
30+All `ArrayBuffer` building must occur in `Effect`.
31+
32+### Serialize an integer
33+
34+Create a two-byte `arraybuffer :: ArrayBuffer` which contains the number *-2* encoded as big-endian 16-bit two’s-complement.
35+```purescript
36+do
37+ arraybuffer <- execPut $ putInt16be (-2)
38+```
39+
40+### Serialize a `String` as UTF8
41+
42+A function which encodes a `String` as UTF8 with a length prefix in a
43+way that's compatible with the
44+[`Binary.Put.putStringUtf8`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html#v:putStringUtf8)
45+function from the Haskell
46+[__binary__](https://hackage.haskell.org/package/binary)
47+library.
48+Uses [`Data.TextEncoding.encodeUtf8`](https://pursuit.purescript.org/packages/purescript-text-encoding/docs/Data.TextEncoding#v:encodeUtf8).
49+```purescript
50+putStringUtf8 :: forall m. (MonadEffect m) => String -> PutM m Unit
51+putStringUtf8 s = do
52+ let stringbuf = Data.ArrayBuffer.Typed.buffer $
53+ Data.TextEncoding.encodeUtf8 s
54+ -- Put a 64-bit big-endian length prefix for the length of the utf8
55+ -- string, in bytes.
56+ putUint32be 0
57+ putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
58+ putArrayBuffer stringbuf
59+```
60+
61+### Serialize an `Array Int`
62+
63+A function which encodes an `Array Int` with a length prefix in a
64+way that's compatible with the
65+[`Binary` instance for `[Int32]`](https://hackage.haskell.org/package/binary/docs/Data-Binary.html#t:Binary)
66+from the Haskell
67+[__binary__](https://hackage.haskell.org/package/binary)
68+library.
69+```purescript
70+putArrayInt32 :: forall m. (MonadEffect m) => Array Int -> PutM m Unit
71+putArrayInt32 xs = do
72+ -- Put a 64-bit big-endian length prefix for the length of the
73+ -- array, in bytes.
74+ putUint32be 0
75+ putUint32be $ Data.Uint.fromInt $ Data.Array.length xs
76+ traverse_ putInt32be xs
77+```
src/Data/ArrayBuffer/Builder.purs+2−69
@@ -1,74 +1,7 @@
1-- | `ArrayBuffer` serialization in the “builder monoid” style.
1-- | `ArrayBuffer` serialization in the “builder monoid” style.
2-- |
2-- |
3−-- | This module provides a `Builder` monoid and a `PutM` monad which are roughly
3+-- | This module provides a `Builder` monoid and a `PutM` monad
4−-- | equivalent to types of the same name in the Haskell
4+-- | for building `ArrayBuffer`s. See the package README for usage examples.
5−-- | [`Data.Binary.Put`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html)
6−-- | module.
7−-- |
8−-- | This library defines no typeclasses. Typeclass-based
9−-- | serialization/deserialization generally assumes that we are round-tripping
10−-- | some data structures out to storage and then back into our program.
11−-- | This library is designed for the case that we are serializing some data
12−-- | to be sent to another program which expects a certain serialization format
13−-- | that we don't control.
14−-- |
15−-- | ## Deserialization
16−-- |
17−-- | This module is only for writing `ArrayBuffer`s, not reading them.
18−-- | See
19−-- | [__purescript-parsing-dataview__](https://pursuit.purescript.org/packages/purescript-parsing-dataview/)
20−-- | for a way to deserialize from `ArrayBuffer` back to Purescript data.
21−-- |
22−-- | ## Usage Examples
23−-- |
24−-- | All `ArrayBuffer` building must occur in `Effect`.
25−-- |
26−-- | ### Serialize an integer
27−-- |
28−-- | Create a two-byte `arraybuffer :: ArrayBuffer` which contains the number *-2* encoded as big-endian 16-bit two’s-complement.
29−-- | ```purescript
30−-- | do
31−-- | arraybuffer <- execPut $ putInt16be (-2)
32−-- | ```
33−-- |
34−-- | ### Serialize a `String` as UTF8
35−-- |
36−-- | A function which encodes a `String` as UTF8 with a length prefix in a
37−-- | way that's compatible with the
38−-- | [`Binary.Put.putStringUtf8`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html#v:putStringUtf8)
39−-- | function from the Haskell
40−-- | [__binary__](https://hackage.haskell.org/package/binary)
41−-- | library.
42−-- | Uses [`Data.TextEncoding.encodeUtf8`](https://pursuit.purescript.org/packages/purescript-text-encoding/docs/Data.TextEncoding#v:encodeUtf8).
43−-- | ```purescript
44−-- | putStringUtf8 :: forall m. (MonadEffect m) => String -> PutM m Unit
45−-- | putStringUtf8 s = do
46−-- | let stringbuf = Data.ArrayBuffer.Typed.buffer $
47−-- | Data.TextEncoding.encodeUtf8 s
48−-- | -- Put a 64-bit big-endian length prefix for the length of the utf8
49−-- | -- string, in bytes.
50−-- | putUint32be 0
51−-- | putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
52−-- | putArrayBuffer stringbuf
53−-- | ```
54−-- |
55−-- | ### Serialize an `Array Int`
56−-- |
57−-- | A function which encodes an `Array Int` with a length prefix in a
58−-- | way that's compatible with the
59−-- | [`Binary` instance for `[Int32]`](https://hackage.haskell.org/package/binary/docs/Data-Binary.html#t:Binary)
60−-- | from the Haskell
61−-- | [__binary__](https://hackage.haskell.org/package/binary)
62−-- | library.
63−-- | ```purescript
64−-- | putArrayInt32 :: forall m. (MonadEffect m) => Array Int -> PutM m Unit
65−-- | putArrayInt32 xs = do
66−-- | -- Put a 64-bit big-endian length prefix for the length of the
67−-- | -- array, in bytes.
68−-- | putUint32be 0
69−-- | putUint32be $ Data.Uint.fromInt $ Data.Array.length xs
70−-- | traverse_ putInt32be xs
71−-- | ```
72module Data.ArrayBuffer.Builder
5module Data.ArrayBuffer.Builder
73( PutM
6( PutM
74, Put
7, Put