Hackage :: [Package]

attoparsec-run: Conveniently run Attoparsec parsers

[ apache, library, parsing ] [ Propose Tags ]

This package fixes a number of problems with the API that Attoparsec provides for running parsers. The difficulties stem from the that that Attoparsec's IResult type encompasses three situations: When parsing has succeeded, when parsing has failed, and when parsing is awaiting further input. This is insufficient to describe situations in which we know we are dealing with a subset of these three cases. We address this by introducing two smaller types: FinalResult and ParseError.

[Skip to Readme]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.0.0.0, 0.0.1.0, 0.0.2.0
Change log changelog.md
Dependencies attoparsec (>=0.14.4 && <0.15), base (>=4.14 && <4.19), bytestring (>=0.10.12 && <0.12), mtl (>=2.2.2 && <2.4), text (>=1.2.4 && <1.3 || >=2.0 && <2.1) [details]
License Apache-2.0
Author Chris Martin
Maintainer Chris Martin, Julie Moronuki
Revised Revision 1 made by chris_martin at 2023-05-30T18:14:05Z
Category Parsing
Home page https://github.com/typeclasses/attoparsec-run
Bug tracker https://github.com/typeclasses/attoparsec-run/issues
Source repo head: git clone git://github.com/typeclasses/attoparsec-run.git
Uploaded by chris_martin at 2023-04-10T17:15:23Z
Distributions LTSHaskell:0.0.2.0, NixOS:0.0.2.0
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 228 total (12 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2023-04-10 [all 1 reports]

Readme for attoparsec-run-0.0.2.0

[back to package description]

This package fixes a number of problems with the API that Attoparsec provides for running parsers.

The difficulties stem from the that that Attoparsec's IResult type encompasses three situations: When parsing has succeeded, when parsing has failed, and when parsing is awaiting further input. This is insufficient to describe situations in which we know we are dealing with a subset of these three cases. We address this by introducing two smaller types: FinalResult and ParseError.

FinalResult

FinalResult represents a result that we know not to be partial; for example, the sort of result that we get when running a parser using parseWith.

data FinalResult i a = FinalResult i (Either ParseError a)

ParseError

ParseError represents only the case in which parsing has failed.

data ParseError = ParseError [String] String

Our showParseError function gives an error string in the same format as Attoparsec's eitherResult function.

showParseError :: ParseError -> String

BufferedInput

The BufferedInput type corresponds to two arguments of Attoparsec's parseWith, the initial input and the action to obtain more input.

data BufferedInput m i = BufferedInput i (m i)

In each of the modules Data.Attoparsec.ByteString.Run and Data.Attoparsec.Text.Run, we provide a function called parseStream. This closely corresponds to Attoparsec's parseWith function, but ours returns the more specific FinalResult type, rather than Result, reflecting the fact that a result returned here is never partial.

parseStream :: Monad m =>
    BufferedInput m ByteString -> Parser a -> m (FinalResult ByteString a)

RestorableInput

RestorableInput offers a new way to do streaming parsing that may be more convenient than parseStream and BufferedInput. This type represents an input stream with the ability to push unused input back to it.

data RestorableInput m i = RestorableInput (m i) (i -> m ())

We use this type with the parseAndRestore function:

parseAndRestore :: Monad m =>
    RestorableInput m ByteString -> Parser a -> m (Either ParseError a)

This shifts the burden of storing the unused remainder to feed back into the next parsing step from the user of parseStream to the definer of the RestorableInput.