https://github.com/rowtype-yoga/purescript-parsing-dataview

DataView on ArrayBuffer input stream support for purescript-parsing
https://github.com/rowtype-yoga/purescript-parsing-dataview

arraybuffer parsing purescript purescript-parsing

Last synced: about 8 hours ago
JSON representation

DataView on ArrayBuffer input stream support for purescript-parsing

• Host: GitHub
• URL: https://github.com/rowtype-yoga/purescript-parsing-dataview
• Owner: rowtype-yoga
• License: bsd-2-clause
• Created: 2020-02-26T01:59:01.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2022-12-05T00:04:37.000Z (almost 2 years ago)
• Last Synced: 2024-06-24T04:55:14.481Z (5 months ago)
• Topics: arraybuffer, parsing, purescript, purescript-parsing
• Language: PureScript
• Homepage: https://pursuit.purescript.org/packages/purescript-parsing-dataview
• Size: 104 KB
• Stars: 4
• Watchers: 2
• Forks: 2
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-purescript - purescript-parsing-dataview - Parser for deserializing ArrayBuffer (Binary Serialization)

README

        
# purescript-parsing-dataview

[![CI](https://github.com/rowtype-yoga/purescript-parsing-dataview/workflows/CI/badge.svg?branch=master)](https://github.com/rowtype-yoga/purescript-parsing-dataview/actions)

[![Pursuit](http://pursuit.purescript.org/packages/purescript-parsing-dataview/badge)](http://pursuit.purescript.org/packages/purescript-parsing-dataview/)

[![Maintainer: jamesdbrock](https://img.shields.io/badge/maintainer-jamesdbrock-teal.svg)](https://github.com/jamesdbrock)

Primitive parsers for

`DataView`s on JavaScript `ArrayBuffer`s with the package

[__parsing__](https://pursuit.purescript.org/packages/purescript-parsing/).

With this package, the input stream support of __parsing__

is similar to the built-in stream support of [__Megaparsec__](https://hackage.haskell.org/package/megaparsec):

| Stream type | parsing | Megaparsec |

|----|-----|----|

| UTF-16 strings | String | Text < v2.0|

| UTF-8 strings | __DataView__ | Text ≥ v2.0 |

| Listy strings | Token | String |

| Binary blobs | __DataView__ | ByteString |

## Usage examples

Parse values out of a `dataview :: Data.ArrayBuffer.Types.DataView`. All

`DataView` parsing must be done in an `Effect` context. The `result` will be

`Either` a parse error or the parsed value.

### Parse two numbers

Parse two big-endian IEEE 754 double-precision `Number`s.

```purescript

import Parsing (runParserT)

import Parsing.DataView (anyFloat64be)

do

  result <- runParserT dataview do

    float1 <- anyFloat64be

    float2 <- anyFloat64be

    pure $ Tuple float1 float2

```

### Parse an array

Parse an array of `n` 32-bit big-endian signed `Int`s.

```purescript

import Parsing (runParserT)

import Parsing.DataView (anyUint32be)

import Data.Unfoldable (replicateA)

do

  result <- runParserT dataview $ replicateA n anyInt32be

```

### Parse UTF-8

Parse a UTF-8 `String` with a length prefix.

We give this as an example, rather than supporting it in the library, because

it depends on

[__web-encoding__](https://pursuit.purescript.org/packages/purescript-web-encoding) for UTF-8.

```purescript

import Control.Monad.Except (ExceptT)

import Data.ArrayBuffer.Cast (toUint8Array)

import Effect.Exception (catchException, message)

import Parsing (runParserT, liftExceptT)

import Parsing.DataView (anyInt32be, takeN)

import Web.Encoding.TextDecoder as TextDecoder

import Web.Encoding.UtfLabel as UtfLabel

do

  textDecoder <- TextDecoder.new UtfLabel.utf8

  result <- runParserT dataview do

    -- First parse a 32-bit big-endian length prefix for the length

    -- of the UTF-8 string in bytes.

    length      <- anyInt32be

    stringview  <- takeN length

    stringarray <- lift $ liftEffect $ toUint8Array stringview

    liftExceptT $ ExceptT $ catchException (pure <<< Left <<< message) do

      Right <$> TextDecoder.decode stringarray textDecoder

```

## Serialization

This package is for reading (`DataView`s on) `ArrayBuffer`s, not writing

them. See the package

[__arraybuffer-builder__](https://pursuit.purescript.org/packages/purescript-arraybuffer-builder/)

for a way to

serialize and build `ArrayBuffer`s.

## References

* [MDN `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)

* [MDN `DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView)

## Development

Run the tests with the development `spago` file:

```

spago -x spago-dev.dhall test

```