mirror of
https://github.com/composewell/streamly.git
synced 2024-09-11 19:47:10 +03:00
Fix overview of Parser and ParserK module
This commit is contained in:
parent
5854499a9e
commit
49b650afc3
@ -7,15 +7,28 @@
|
||||
-- Stability : pre-release
|
||||
-- Portability : GHC
|
||||
--
|
||||
-- Parsers are stream consumers like folds with the following differences:
|
||||
-- Parsers are more powerful 'Streamly.Data.Fold.Fold's:
|
||||
--
|
||||
-- * folds cannot fail but parsers can fail and backtrack.
|
||||
-- * folds can be composed as a Tee but parsers cannot.
|
||||
-- * folds can be used for scanning but parsers cannot.
|
||||
-- * folds can be converted to parsers.
|
||||
--
|
||||
-- This module implements parsers with stream fusion which compile to efficient
|
||||
-- loops comparable to the speed of C.
|
||||
-- Streamly parsers support all operations offered by popular Haskell parser
|
||||
-- libraries. They operate on a generic input type, support streaming, and are
|
||||
-- faster.
|
||||
--
|
||||
-- Like folds, parsers use stream fusion, compiling to efficient low-level code
|
||||
-- comparable to the speed of C. Parsers are suitable for high-performance
|
||||
-- parsing of streams.
|
||||
--
|
||||
-- Operations in this module are designed to be composed statically rather than
|
||||
-- dynamically. They are inlined to enable static fusion. More importantly,
|
||||
-- they are not designed to be used recursively. Recursive use will break
|
||||
-- fusion and will lead to quadratic performance slowdown. For dynamic or
|
||||
-- recursive composition use the continuation passing style (CPS) operations
|
||||
-- from the "Streamly.Data.ParserK" module. 'Parser' and
|
||||
-- 'Streamly.Data.ParserK.ParserK' types are interconvertible.
|
||||
--
|
||||
-- == Using Parsers
|
||||
--
|
||||
@ -117,23 +130,6 @@
|
||||
-- layer (which should be the case almost always) you can just use 'fromEffect'
|
||||
-- to execute the lower layer monad effects.
|
||||
--
|
||||
-- == Parser vs ParserK Implementation
|
||||
--
|
||||
-- The 'Parser' type represents a stream consumer by composing state as data
|
||||
-- which enables stream fusion. Stream fusion generates a tight loop without
|
||||
-- any constructor allocations between the stages, providing C like performance
|
||||
-- for the loop. Stream fusion works when multiple functions are combined in a
|
||||
-- pipeline statically. Therefore, the operations in this module must be
|
||||
-- inlined and must not be used recursively to allow for stream fusion.
|
||||
--
|
||||
-- The 'ParserK' type represents a stream consumer by composing function calls,
|
||||
-- therefore, a function call overhead is incurred at each composition. It is
|
||||
-- quite fast in general but may be a few times slower than a fused parser.
|
||||
-- However, it allows for scalable dynamic composition especially parsers can
|
||||
-- be used in recursive calls. Using the 'ParserK' type operations like
|
||||
-- 'splitWith' provide linear (O(n)) performance with respect to the number of
|
||||
-- compositions.
|
||||
--
|
||||
-- == Experimental APIs
|
||||
--
|
||||
-- Please refer to "Streamly.Internal.Data.Parser" for functions that have not
|
||||
|
@ -11,18 +11,24 @@
|
||||
-- This module implements a using Continuation Passing Style (CPS) wrapper over
|
||||
-- the "Streamly.Data.Parser" module. It is as fast or faster than attoparsec.
|
||||
--
|
||||
-- == Parser vs ParserK
|
||||
-- Streamly parsers support all operations offered by popular Haskell parser
|
||||
-- libraries. They operate on a generic input type, support streaming, and are
|
||||
-- faster.
|
||||
--
|
||||
-- The 'ParserK' type represents a stream-consumer as a composition of function
|
||||
-- calls, therefore, a function call overhead is incurred at each composition.
|
||||
-- It is reasonably fast in general but may be a few times slower than a fused
|
||||
-- parser represented by the 'Streamly.Data.Parser.Parser' type. However, it
|
||||
-- allows for scalable dynamic composition, especially, 'ParserK' can be used
|
||||
-- in recursive calls. Operations like 'splitWith' on 'ParserK' type have
|
||||
-- linear (O(n)) performance with respect to the number of compositions.
|
||||
--
|
||||
-- 'ParserK' is preferred over 'Streamly.Data.Parser.Parser' when extensive
|
||||
-- applicative, alternative and monadic composition is required, or when
|
||||
-- recursive or dynamic composition of parsers is required. The
|
||||
-- 'Streamly.Data.Parser.Parser' type fuses statically and creates efficient
|
||||
-- loops whereas 'ParserK' uses function call based composition and has
|
||||
-- comparatively larger runtime overhead but it is better suited to the
|
||||
-- specific use cases mentioned above. 'ParserK' also allows to efficient parse
|
||||
-- a stream of arrays, it can also break the input stream into a parse result
|
||||
-- and remaining stream so that the stream can be parsed independently in
|
||||
-- segments.
|
||||
-- recursive or dynamic composition of parsers is required. 'ParserK' also
|
||||
-- allows efficient parsing of a stream of arrays, it can also break the input
|
||||
-- stream into a parse result and remaining stream so that the stream can be
|
||||
-- parsed independently in segments.
|
||||
--
|
||||
-- == Using ParserK
|
||||
--
|
||||
|
Loading…
Reference in New Issue
Block a user