Split.hs

-----------------------------------------------------------------------------
-- |
-- Module      :  Data.List.Split
-- Copyright   :  (c) Brent Yorgey, Louis Wasserman 2008
-- License     :  BSD-style (see LICENSE)
-- Maintainer  :  Brent Yorgey <byorgey@gmail.com>
-- Stability   :  experimental
-- Portability :  unportable (GADTs, Rank2Types)
--
-- The "Data.List.Split" module contains a wide range of strategies
-- for splitting lists with respect to some sort of delimiter, mostly
-- implemented through a unified combinator interface.  The goal is to
-- be flexible yet simple.  Scroll past the Synopsis for usage,
-- examples, and detailed documentation of all exported functions.  If
-- you want to learn about the implementation, see
-- "Data.List.Split.Internals".
--
-- A darcs repository containing the source (including a module with
-- over 40 QuickCheck properties) can be found at
-- <http://code.haskell.org/~byorgey/code/split>.
--
-----------------------------------------------------------------------------
module Data.List.Split (

                       -- * Getting started
                       -- $started

                       -- * Convenience functions
                       -- $conv

                         splitOn
                       , splitOneOf
                       , splitWhen
                       , sepBy
                       , sepByOneOf
                       , endBy
                       , endByOneOf

                       , unintercalate

                       , wordsBy
                       , linesBy

                       -- * Other splitting methods
                       -- $other
                       , splitEvery
                       , chunk
                       , splitPlaces

                       -- * Splitting combinators
                       -- $comb

                       , Splitter
                       , defaultSplitter
                       , split

                       -- ** Basic strategies
                       -- $basic

                       , oneOf
                       , onSublist
                       , whenElt

                       -- ** Strategy transformers
                       -- $transform

                       , dropDelims
                       , keepDelimsL
                       , keepDelimsR
                       , condense
                       , dropInitBlank
                       , dropFinalBlank

                       -- ** Derived combinators
                       -- $derived

                       , dropBlanks
                       , startsWith
                       , startsWithOneOf
                       , endsWith
                       , endsWithOneOf

                       ) where

import Data.List.Split.Internals

-- $started
-- To get started, you should take a look at the functions 'splitOn',
-- 'splitWhen', 'sepBy', 'endBy', 'splitEvery', 'splitPlaces', and
-- other functions listed in the next two sections.  These functions
-- implement various common splitting operations, and one of them will
-- probably do the job 90\% of the time.  For example:
--
-- > > splitOn "x" "axbxc"
-- > ["a","b","c"]
-- > > splitOn "x" "axbxcx"
-- > ["a","b","c",""]
-- > > endBy ";" "foo;bar;baz;"
-- > ["foo","bar","baz"]
-- > > splitWhen (<0) [1,3,-4,5,7,-9,0,2]
-- > [[1,3],[5,7],[0,2]]
-- > > splitOneOf ";.," "foo,bar;baz.glurk"
-- > ["foo","bar","baz","glurk"]
-- > > splitEvery 3 ['a'..'z']
-- > ["abc","def","ghi","jkl","mno","pqr","stu","vwx","yz"]
--
-- If you want more flexibility, however, you can use the combinator
-- library in terms of which these functions are defined.  For more
-- information, skip to the section labeled \"Splitting Combinators\".
--
-- Note that the goal of this library is to be flexible yet simple.
-- It does not implement any particularly sophisticated list-splitting
-- methods, nor is it tuned for speed.  If you find yourself wanting
-- something more complicated or optimized, it probably means you
-- should use a real parsing or regular expression library.

-- $conv
-- These functions implement some common splitting strategies.  Note
-- that all of the functions in this section drop delimiters from the
-- final output, since that is a more common use case even though it
-- is not the default.

-- $other
-- Other useful splitting methods which are not implemented using the
-- combinator framework.

-- $comb
-- The core of the library is the 'Splitter' type, which represents a
-- particular list-splitting strategy.  All of the combinators revolve
-- around constructing or transforming 'Splitter' objects; once a
-- suitable 'Splitter' has been created, it can be run with the
-- 'split' function.  For example:
--
-- > > split (dropBlanks . condense $ whenElt (<0)) [1,2,4,-5,-6,4,9,-19,-30]
-- > [[1,2,4],[-5,-6],[4,9],[-19,-30]]

-- $basic
-- All these basic strategies have the same parameters as the
-- 'defaultSplitter' except for the delimiter.

-- $transform
-- Functions for altering splitting strategy parameters.

-- $derived
-- Combinators which can be defined in terms of other combinators, but
-- are provided for convenience.