on master help sign in
remove duplication between exposed/internal modules

Keep the unreleased API documentation only in the internal module

commita59c72cb86050aa269a837b195a9b845392dacca authorHarendra Kumar <harendra@composewell.com> dateThu 27 Feb 2020, 14:19 (7 years ago) parent0e2bb73
2 files changed+71−147
src/Streamly/Internal/Prelude.hs+71−9 src/Streamly/Prelude.hs−138
src/Streamly/Internal/Prelude.hs+71−9
@@ -20,6 +20,11 @@
2020-- Stability : experimental
2121-- Portability : GHC
2222--
23+-- This is an Internal module consisting of released, unreleased and
24+-- unimplemented APIs. For stable and released APIs please see
25+-- "Streamly.Prelude" module. This module provides documentation only for the
26+-- unreleased and unimplemented APIs. For documentation on released APIs please
27+-- see "Streamly.Prelude" module.
2328
2429module Streamly.Internal.Prelude
2530 (
@@ -98,7 +103,7 @@ module Streamly.Internal.Prelude
98103 , length
99104 , sum
100105 , product
101− --, mconcat
106+ , mconcat
102107
103108 -- -- ** To Summary (Maybe) (Full Folds)
104109 , maximumBy
@@ -168,6 +173,9 @@ module Streamly.Internal.Prelude
168173 , scan
169174 , postscan
170175
176+ -- XXX Once we have pipes the contravariant transformations can be
177+ -- represented by attaching pipes before a transformation.
178+ --
171179 -- , lscanl'
172180 -- , lscanlM'
173181 -- , lscanl1'
@@ -219,14 +227,25 @@ module Streamly.Internal.Prelude
219227 -- ** Mapping Filters
220228 , mapMaybe
221229 , mapMaybeM
230+
231+ -- ** Window map
222232 , rollingMapM
223233 , rollingMap
224234
225235 -- ** Scanning Filters
236+ -- -- *** Searching Elements
226237 , findIndices
227238 , elemIndices
239+
240+ -- -- *** Searching Sequences
228241 -- , seqIndices -- search a sequence in the stream
229242
243+ -- -- *** Searching Multiple Sequences
244+ -- , seqIndicesAny -- search any of the given sequence in the stream
245+
246+ -- -- -- ** Searching Streams
247+ -- -- | Finding a stream within another stream.
248+
230249 -- ** Insertion
231250 , insertBy
232251 , intersperseM
@@ -234,6 +253,11 @@ module Streamly.Internal.Prelude
234253 , intersperseSuffix
235254 , intersperseSuffixBySpan
236255 -- , intersperseBySpan
256+ -- , intersperseByIndices -- using an index function/stream
257+
258+ -- time domain intersperse
259+ -- , intersperseByTime
260+ -- , intersperseByEvent
237261 , interjectSuffix
238262 , delayPost
239263
@@ -276,24 +300,33 @@ module Streamly.Internal.Prelude
276300 , Z.zipAsyncWith
277301 , Z.zipAsyncWithM
278302
279− -- ** Nested Streams
303+ -- ** Flattening Nested Streams
280304 , concatMapM
281305 , concatM
306+ , concatMap
307+ -- XXX add stateful concatMapWith?
308+ , concatMapWith
309+ -- , bindWith
310+
311+ -- ** Flattening Using Unfolds
282312 , concatUnfold
283313 , concatUnfoldInterleave
284314 , concatUnfoldRoundrobin
285− , concatMap
286− , concatMapWith
315+
316+ -- ** Feedback Loops
317+ , concatMapIterateWith
318+ , concatMapTreeWith
319+ , concatMapLoopWith
320+ , concatMapTreeYieldLeavesWith
321+
322+ -- ** Inserting Streams in Streams
287323 , gintercalate
288324 , gintercalateSuffix
289325 , intercalate
290326 , intercalateSuffix
291327 , interpose
292328 , interposeSuffix
293− , concatMapIterateWith
294− , concatMapTreeWith
295− , concatMapLoopWith
296− , concatMapTreeYieldLeavesWith
329+ -- , interposeBy
297330
298331 -- -- ** Breaking
299332
@@ -312,8 +345,18 @@ module Streamly.Internal.Prelude
312345
313346 -- By sequences
314347 -- , breakOnSeq
348+ -- , breakOnStream -- on a stream
315349
316350 -- ** Splitting
351+ -- | Streams can be sliced into segments in space or in time. We use the
352+ -- term @chunk@ to refer to a spatial length of the stream (spatial window)
353+ -- and the term @session@ to refer to a length in time (time window).
354+
355+ -- In imperative terms, grouped folding can be considered as a nested loop
356+ -- where we loop over the stream to group elements and then loop over
357+ -- individual groups to fold them to a single value that is yielded in the
358+ -- output stream.
359+
317360 -- , groupScan
318361
319362 -- -- *** Chunks
@@ -332,7 +375,7 @@ module Streamly.Internal.Prelude
332375 -- , splitByPrefix
333376 , wordsBy -- stripAndCompactBy
334377
335− -- -- *** Using Sequence Separators
378+ -- -- *** Splitting By Sequences
336379 , splitOnSeq
337380 , splitOnSuffixSeq
338381 -- , splitOnPrefixSeq
@@ -348,6 +391,9 @@ module Streamly.Internal.Prelude
348391 -- , splitOnAnySuffixSeq
349392 -- , splitOnAnyPrefixSeq
350393
394+ -- -- *** Splitting By Streams
395+ -- | Splitting a stream using another stream as separator.
396+
351397 -- Nested splitting
352398 , splitInnerBy
353399 , splitInnerBySuffix
@@ -367,17 +413,33 @@ module Streamly.Internal.Prelude
367413
368414 -- * Windowed Classification
369415
416+ -- | Split the stream into windows or chunks in space or time. Each window
417+ -- can be associated with a key, all events associated with a particular
418+ -- key in the window can be folded to a single result. The stream is split
419+ -- into windows of specified size, the window can be terminated early if
420+ -- the closing flag is specified in the input stream.
421+ --
422+ -- The term "chunk" is used for a space window and the term "session" is
423+ -- used for a time window.
424+
370425 -- ** Tumbling Windows
426+ -- | A new window starts after the previous window is finished.
427+
371428 -- , classifyChunksOf
372429 , classifySessionsBy
373430 , classifySessionsOf
374431
375432 -- ** Keep Alive Windows
433+ -- | The window size is extended if an event arrives within the specified
434+ -- window size. This can represent sessions with idle or inactive timeout.
435+
376436 -- , classifyKeepAliveChunks
377437 , classifyKeepAliveSessions
378438
379439 {-
380440 -- ** Sliding Windows
441+ -- | A new window starts after the specified slide from the previous
442+ -- window. Therefore windows can overlap.
381443 , classifySlidingChunks
382444 , classifySlidingSessions
383445 -}
src/Streamly/Prelude.hs−138
@@ -174,8 +174,6 @@ module Streamly.Prelude
174174 -- ** Right Folds
175175 -- $rightfolds
176176 , foldrM
177− -- , foldrS
178− -- , foldrT
179177 , foldr
180178
181179 -- ** Left Folds
@@ -199,7 +197,6 @@ module Streamly.Prelude
199197 , length
200198 , sum
201199 , product
202− --, mconcat
203200
204201 -- -- ** To Summary (Maybe) (Full Folds)
205202 -- -- | Folds that summarize a non-empty stream to a 'Just' value and return
@@ -209,7 +206,6 @@ module Streamly.Prelude
209206 , minimumBy
210207 , minimum
211208 , the
212− -- , toListRev -- experimental
213209
214210 -- ** Lazy Folds
215211 --
@@ -252,19 +248,13 @@ module Streamly.Prelude
252248 , eqBy
253249 , cmpBy
254250 , isPrefixOf
255− -- , isSuffixOf
256− -- , isInfixOf
257251 , isSubsequenceOf
258252
259253 -- trimming sequences
260254 , stripPrefix
261− -- , stripSuffix
262− -- , stripInfix
263255
264256 -- * Transformation
265257
266− --, transform
267−
268258 -- ** Mapping
269259 -- | In imperative terms a map operation can be considered as a loop over
270260 -- the stream that transforms the stream into another stream by performing
@@ -343,8 +333,6 @@ module Streamly.Prelude
343333 , scanlM'
344334 , postscanl'
345335 , postscanlM'
346− -- , prescanl'
347− -- , prescanlM'
348336 , scanl1'
349337 , scanl1M'
350338
@@ -352,16 +340,6 @@ module Streamly.Prelude
352340 , scan
353341 , postscan
354342
355− -- , lscanl'
356− -- , lscanlM'
357− -- , lscanl1'
358− -- , lscanl1M'
359− --
360− -- , lpostscanl'
361− -- , lpostscanlM'
362− -- , lprescanl'
363− -- , lprescanlM'
364−
365343 -- ** Filtering
366344 -- | Remove some elements from the stream based on a predicate. In
367345 -- imperative terms a filter over a stream corresponds to a loop with a
@@ -380,9 +358,6 @@ module Streamly.Prelude
380358 -- | Deleting elements is a special case of de-interleaving streams.
381359 , deleteBy
382360 , uniq
383− -- , uniqBy -- by predicate e.g. to remove duplicate "/" in a path
384− -- , uniqOn -- to remove duplicate sequences
385− -- , pruneBy -- dropAround + uniqBy - like words
386361
387362 -- ** Inserting Elements
388363 -- | Inserting elements is a special case of interleaving/merging streams.
@@ -390,73 +365,27 @@ module Streamly.Prelude
390365 , insertBy
391366 , intersperseM
392367 , intersperse
393− -- , insertAfterEach
394− -- , intersperseBySpan
395− -- , intersperseByIndices -- using an index function/stream
396− -- , intersperseByTime
397− -- , intersperseByEvent
398−
399− -- -- * Inserting Streams in Streams
400− -- , interposeBy
401− -- , intercalate
402368
403369 -- ** Indexing
404370 -- | Indexing can be considered as a special type of zipping where we zip a
405371 -- stream with an index stream.
406372 , indexed
407373 , indexedR
408− -- , timestamped
409− -- , timestampedR -- timer
410374
411375 -- ** Reordering Elements
412376 , reverse
413− -- , reverse'
414377
415378 -- ** Trimming
416379 -- | Take or remove elements from one or both ends of a stream.
417380 , take
418− -- , takeEnd
419381 , takeWhile
420382 , takeWhileM
421− -- , takeWhileEnd
422383 , drop
423− -- , dropEnd
424384 , dropWhile
425385 , dropWhileM
426− -- , dropWhileEnd
427− -- , dropAround
428386
429387 -- -- ** Breaking
430388
431− -- By chunks
432− -- , splitAt -- spanN
433− -- , splitIn -- sessionN
434−
435− -- By elements
436− -- , span -- spanWhile
437− -- , break -- breakBefore
438− -- , breakAfter
439− -- , breakOn
440− -- , breakAround
441− -- , spanBy
442− -- , spanByRolling
443−
444− -- By sequences
445− -- breakOnSeq/breakOnArray -- on a fixed sequence
446− -- breakOnStream -- on a stream
447−
448− -- ** Slicing
449− -- | Streams can be sliced into segments in space or in time. We use the
450− -- term @chunk@ to refer to a spatial length of the stream (spatial window)
451− -- and the term @session@ to refer to a length in time (time window).
452−
453− -- In imperative terms, grouped folding can be considered as a nested loop
454− -- where we loop over the stream to group elements and then loop over
455− -- individual groups to fold them to a single value that is yielded in the
456− -- output stream.
457−
458− -- , groupScan
459−
460389 , chunksOf
461390 , intervalsOf
462391
@@ -468,15 +397,6 @@ module Streamly.Prelude
468397 , findIndices
469398 , elemIndices
470399
471− -- -- *** Searching Sequences
472− -- , seqIndices -- search a sequence in the stream
473−
474− -- -- *** Searching Multiple Sequences
475− -- , seqIndices -- search a sequence in the stream
476−
477− -- -- ** Searching Streams
478− -- -- | Finding a stream within another stream.
479−
480400 -- ** Splitting
481401 -- | In general we can express splitting in terms of parser combinators.
482402 -- These are some common use functions for convenience and efficiency.
@@ -502,32 +422,10 @@ module Streamly.Prelude
502422 -- -- ** Splitting By Elements
503423 , splitOn
504424 , splitOnSuffix
505− -- , splitOnPrefix
506425
507− -- , splitBy
508426 , splitWithSuffix
509− -- , splitByPrefix
510427 , wordsBy -- strip, compact and split
511428
512− -- -- *** Splitting By Sequences
513− -- , splitOnSeq
514− -- , splitOnSuffixSeq
515− -- , splitOnPrefixSeq
516−
517− -- Keeping the delimiters
518− -- , splitBySeq
519− -- , splitBySeqSuffix
520− -- , splitBySeqPrefix
521− -- , wordsBySeq
522−
523− -- Splitting By Multiple Sequences
524− -- , splitOnAnySeq
525− -- , splitOnAnySuffixSeq
526− -- , splitOnAnyPrefixSeq
527−
528− -- -- ** Splitting By Streams
529− -- -- | Splitting a stream using another stream as separator.
530−
531429 -- ** Grouping
532430 -- | Splitting a stream by combining multiple contiguous elements into
533431 -- groups using some criterion.
@@ -535,40 +433,6 @@ module Streamly.Prelude
535433 , groupsBy
536434 , groupsByRolling
537435
538− {-
539− -- * Windowed Classification
540− -- | Split the stream into windows or chunks in space or time. Each window
541− -- can be associated with a key, all events associated with a particular
542− -- key in the window can be folded to a single result. The stream is split
543− -- into windows of specified size, the window can be terminated early if
544− -- the closing flag is specified in the input stream.
545− --
546− -- The term "chunk" is used for a space window and the term "session" is
547− -- used for a time window.
548−
549− -- ** Tumbling Windows
550− -- | A new window starts after the previous window is finished.
551− -- , classifyChunksOf
552− -- , classifySessionsOf
553−
554− -- ** Keep Alive Windows
555− -- | The window size is extended if an event arrives within the specified
556− -- window size. This can represent sessions with idle or inactive timeout.
557− -- , classifyKeepAliveChunks
558− -- , classifyKeepAliveSessions
559−
560− {-
561− -- ** Sliding Windows
562− -- | A new window starts after the specified slide from the previous
563− -- window. Therefore windows can overlap.
564− , classifySlidingChunks
565− , classifySlidingSessions
566− -}
567− -- ** Sliding Window Buffers
568− -- , slidingChunkBuffer
569− -- , slidingSessionBuffer
570− -}
571−
572436 -- * Combining Streams
573437 -- | New streams can be constructed by appending, merging or zipping
574438 -- existing streams.
@@ -660,9 +524,7 @@ module Streamly.Prelude
660524 -- > filter p m = S.concatMap (\x -> if p x then S.yield x else S.nil) m
661525 --
662526
663− -- XXX add stateful concatMapWith
664527 , concatMapWith
665− --, bindWith
666528 , concatMap
667529 , concatMapM
668530 , concatUnfold