git.iko.soy/rowtype-yoga/purescript-parsing-dataview
on master help sign in
rowtype-yoga/purescript-parsing-dataview/README.md
105 lines 3.4 kB history raw
1# purescript-parsing-dataview
3[![CI](https://github.com/rowtype-yoga/purescript-parsing-dataview/workflows/CI/badge.svg?branch=master)](https://github.com/rowtype-yoga/purescript-parsing-dataview/actions)
4[![Pursuit](http://pursuit.purescript.org/packages/purescript-parsing-dataview/badge)](http://pursuit.purescript.org/packages/purescript-parsing-dataview/)
5[![Maintainer: jamesdbrock](https://img.shields.io/badge/maintainer-jamesdbrock-teal.svg)](https://github.com/jamesdbrock)
7Primitive parsers for
8`DataView`s on JavaScript `ArrayBuffer`s with the package
9[__parsing__](https://pursuit.purescript.org/packages/purescript-parsing/).
11With this package, the input stream support of __parsing__
12is similar to the built-in stream support of [__Megaparsec__](https://hackage.haskell.org/package/megaparsec):
14| Stream type | parsing | Megaparsec |
15|----|-----|----|
16| UTF-16 strings | String | Text < v2.0|
17| UTF-8 strings | __DataView__ | Text ≥ v2.0 |
18| Listy strings | Token | String |
19| Binary blobs | __DataView__ | ByteString |
21## Usage examples
23Parse values out of a `dataview :: Data.ArrayBuffer.Types.DataView`. All
24`DataView` parsing must be done in an `Effect` context. The `result` will be
25`Either` a parse error or the parsed value.
27### Parse two numbers
29Parse two big-endian IEEE 754 double-precision `Number`s.
31```purescript
32import Parsing (runParserT)
33import Parsing.DataView (anyFloat64be)
35do
36 result <- runParserT dataview do
37 float1 <- anyFloat64be
38 float2 <- anyFloat64be
39 pure $ Tuple float1 float2
40```
42### Parse an array
44Parse an array of `n` 32-bit big-endian signed `Int`s.
46```purescript
47import Parsing (runParserT)
48import Parsing.DataView (anyUint32be)
49import Data.Unfoldable (replicateA)
51do
52 result <- runParserT dataview $ replicateA n anyInt32be
53```
55### Parse UTF-8
57Parse a UTF-8 `String` with a length prefix.
59We give this as an example, rather than supporting it in the library, because
60it depends on
61[__web-encoding__](https://pursuit.purescript.org/packages/purescript-web-encoding) for UTF-8.
63```purescript
64import Control.Monad.Except (ExceptT)
65import Data.ArrayBuffer.Cast (toUint8Array)
66import Effect.Exception (catchException, message)
67import Parsing (runParserT, liftExceptT)
68import Parsing.DataView (anyInt32be, takeN)
69import Web.Encoding.TextDecoder as TextDecoder
70import Web.Encoding.UtfLabel as UtfLabel
72do
73 textDecoder <- TextDecoder.new UtfLabel.utf8
75 result <- runParserT dataview do
76 -- First parse a 32-bit big-endian length prefix for the length
77 -- of the UTF-8 string in bytes.
78 length <- anyInt32be
79 stringview <- takeN length
80 stringarray <- lift $ liftEffect $ toUint8Array stringview
81 liftExceptT $ ExceptT $ catchException (pure <<< Left <<< message) do
82 Right <$> TextDecoder.decode stringarray textDecoder
83```
85## Serialization
87This package is for reading (`DataView`s on) `ArrayBuffer`s, not writing
88them. See the package
89[__arraybuffer-builder__](https://pursuit.purescript.org/packages/purescript-arraybuffer-builder/)
90for a way to
91serialize and build `ArrayBuffer`s.
94## References
96* [MDN `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
97* [MDN `DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView)
99## Development
101Run the tests with the development `spago` file:
103```
104spago -x spago-dev.dhall test
105```