Text.Parcom.Stream

Typeclasses to describe various aspects of parsable streams and tokens. The standard range of Haskell string-like types (String, and both the lazy and strict flavors of ByteString and Text) is supported already, as well as any List, so under normal circumstances, you should not need to touch this module directly.

Documentation

class Stream s t | s -> t where

Typeclass for types that are suitable as source streams. Note that implementing just Stream gives you only a small subset of Parcom's features; if you want to implement your own Stream instances, you will most likely also want to implement Token for the corresponding token type, Listish to enable parsers that need to convert to or from lists of tokens, and Textish to enable parsers that work on Unicode text.

Minimal complete definition

peek, atEnd

Methods

peek :: s -> t

atEnd :: s -> Bool

consume :: s -> s

pop :: s -> (t, s)

Instances

Stream ByteString Word8

Stream ByteString Word8

Stream Text Char

Stream Text Char

Stream [a] a

All lists are instances of Stream, and the corresponding token type is the list element type. Obviously, this also includes String ('[Char]') and '[Word8]'

class Token t where

This typeclass is pretty much required to do anything useful with Parcom; it is needed for Parcom to detect line endings so that parser errors will report the correct source positions. If you need to parse streams that do not support any meaningful concept of lines, consider implementing a dummy instance, like so: instance Token Foobar where isLineDelimiter _ = False This will treat the entire input as a single line.

Methods

isLineDelimiter :: t -> Bool

Instances

Token Char

Unicode characters are valid tokens.

Token Word8

class Listish s t | s -> t where

List-like types.

Methods

toList :: s -> [t]

fromList :: [t] -> s

Instances

Listish ByteString Word8

Listish ByteString Word8

Listish Text Char

Listish Text Char

Listish [a] a

Any list is trivially list-like

class Textish s where

Enables parsing on a per-character basis rather than per-token. For stream types where the token type is Char already, this is trivial, but for other streams (e.g., bytestrings), some extra processing is required to perform a conversion to Unicode.

Methods

peekChar :: s -> (Maybe Char, Int)

Character-wise equivalent of peek. Returns a pair, where the first element is Just the parsed Unicode character, or Nothing on failure, and the second element is the number of tokens that the character has consumed. Generally, there are two reasons why parsing may fail: end-of-input, and a token sequence that does not represent a valid Unicode character according to the underlying stream's semantics.

Instances

Textish ByteString

Textish ByteString

Textish Text

Textish Text

Textish [Char]