@@ -5,24 +5,73 @@
55
66The module `Text.Parsing.Parser.DataView` provides primitive parsers for parsing
77DataViews on Javascript ArrayBuffers with the package
8−[__purescript-parsing__](https://github.com/purescript-contrib/purescript-parsing).
8+[__purescript-parsing__](https://pursuit.purescript.org/packages/purescript-parsing/).
99
10−This module brings __purescript-parsing__ into rough feature parity
11−with __Megaparsec__:
10+This module brings the input stream support of __purescript-parsing__ to be
11+able to roughly match the built-in stream support of __Megaparsec__:
1212
1313| Stream type | purescript-parsing | Megaparsec |
1414|----|-----|----|
1515| UTF-16 strings | String | Text |
1616| Listy strings | Token | String |
17−| Binary blobs | __DataView__ | Bytestring |
17+| Binary blobs | __Text.Parsing.Parser.DataView__ | Bytestring |
1818
19−## Installation
19+## Usage examples
2020
21+Parse values out of a `dataview :: Data.ArrayBuffer.Types.DataView`. All
22+`DataView` parsing must be done in an `Effect` context. The `result` will be
23+`Either` a parse error or the parsed value.
24+
25+### Parse two numbers
26+
27+Parse two big-endian IEEE 754 double-precision floats.
28+
29+```purescript
30+do
31+ result <- Text.Parsing.Parser.runParserT dataview $ do
32+ float1 <- anyFloat64be
33+ float2 <- anyFloat64be
34+ pure $ Tuple float1 float2
2135```
22−bower install jamesdbrock/purescript-parsing-dataview --save
36+
37+### Parse an array
38+
39+Parse `n` 32-bit signed integers.
40+
41+```purescript
42+do
43+ result <- Text.Parsing.Parser.runParserT dataview $ replicateA n anyInt32be
44+```
45+
46+### Parse UTF8
47+
48+Parse a `String` as UTF8 with a length prefix in a
49+way that's compatible with the
50+[`Binary.Put.putStringUtf8`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html#v:putStringUtf8)
51+function from the Haskell
52+[__binary__](https://hackage.haskell.org/package/binary)
53+library.
54+We give this as an example, rather than supporting it in the library, because
55+it depends on
56+[`Data.TextDecoding.decodeUtf8`](https://pursuit.purescript.org/packages/purescript-text-encoding/docs/Data.TextDecoding#v:decodeUtf8).
57+
58+```purescript
59+do
60+ result <- Text.Parsing.Parser.runParserT dataview $ do
61+ -- Parse a big-endian 64-big length prefix
62+ _ <- anyUint32be
63+ length <- anyUint32be
64+ stringview <- takeN $ UInt.toInt length
65+ stringarray <- liftEffect $ mkTypedArray stringview
66+ pure $ Data.TextDecoding.decodeUtf8 stringarray
67+
68+where
69+ mkTypedArray :: Data.ArrayBuffer.Types.DataView -> Effect Data.ArrayBuffer.Types.Uint8Array
70+ mkTypedArray dv = do
71+ let buffer = Data.ArrayBuffer.DataView.buffer dv
72+ byteOffset = Data.ArrayBuffer.DataView.byteOffset dv
73+ byteLength = Data.ArrayBuffer.DataView.byteLength dv
74+ pure $ Data.ArrayBuffer.Typed.part buffer byteOffset byteLength
2375```
2476
25−## Documentation
2677
27−- [See the tests](test/Main.purs) for some example usages.
28−- Module documentation is [published on Pursuit](http://pursuit.purescript.org/packages/purescript-parsing-dataview).