diff --git a/Acme/StrTok.hs b/Acme/StrTok.hs new file mode 100644 --- /dev/null +++ b/Acme/StrTok.hs @@ -0,0 +1,105 @@ +{-| +Module : StrTok +Description : Provides the strTok function +License : Public Domain +Maintainer : Manuel Eberl +Stability : experimental + +This module provides the function @strTok@, a variant of the @strtok@ function in C and PHP. This function can be +used to tokenise a string (or, more generally, a list) with successive calls of the @strtok@ function. Since +@strTok@ is a stateful function (it produces different results when called with the same parameter multiple times), +computations using @strTok@ must take place in the @StrTok@ monad or the @StrTokT@ monad transformer. +-} +module Acme.StrTok ( + -- * The StrTokT monad transformer + StrTokT, + runStrTokT, + -- * The StrTok monad + StrTok, + runStrTok, + -- * The strTok function + strTok + ) where + +import Control.Applicative +import Control.Monad +import Control.Monad.Identity +import Control.Arrow +import Control.Monad.Trans + + +-- | The @StrTokT@ monad, parametrised with: +-- +-- * @s@ - The type of list elements (e.g. @Char@ if the input to @strTok@ is a @String@). +-- +-- * @m@ - The inner monad. +newtype StrTokT s m a = StrTokT { runStrTokT' :: [s] -> m (a, [s]) } + +instance Functor m => Functor (StrTokT s m) where + fmap f (StrTokT g) = StrTokT $ fmap (first f) . g + +instance (Functor m, Monad m) => Applicative (StrTokT s m) where + pure = return + (<*>) = ap + +instance (Functor m, MonadPlus m) => Alternative (StrTokT s m) where + empty = mzero + (<|>) = mplus + +instance (MonadPlus m) => MonadPlus (StrTokT s m) where + mzero = StrTokT $ const mzero + m `mplus` n = StrTokT $ \s -> runStrTokT' m s `mplus` runStrTokT' n s + +instance (MonadFix m) => MonadFix (StrTokT s m) where + mfix f = StrTokT $ \s -> mfix $ \ ~(a, _) -> runStrTokT' (f a) s + +instance Monad m => Monad (StrTokT s m) where + return x = StrTokT $ \s -> return (x,s) + StrTokT f >>= g = StrTokT $ \s -> do {(x,s) <- f s; runStrTokT' (g x) s} + +instance MonadTrans (StrTokT s) where + lift m = StrTokT $ \s -> do {x <- m; return (x,s)} + +instance (MonadIO m) => MonadIO (StrTokT s m) where + liftIO = lift . liftIO + +-- | Executes a @strTok@ computation in the state transformer monad @StrTokT@. +runStrTokT :: Functor m => StrTokT s m a -> m a +runStrTokT (StrTokT f) = fmap fst (f []) + + + +-- | The @StrTok@ monad. +type StrTok s = StrTokT s Identity + +-- | Executes a @strTok@ computation in the state monad @StrTok@. +runStrTok :: StrTok s a -> a +runStrTok = runIdentity . runStrTokT + + + +-- | A Haskell variant of the @strtok@ function from C and PHP. This function splits a string into tokens which are +-- delimited by a given set of characters. A call with @Just s@ and the delimiting characters @ds@ will yield +-- the first token in @s@ that is delimited by characters from @ds@. Every subsequent call of @strTok@ with @Nothing@ +-- will yield the next token. If the string contains no more tokens, an empty list is returned. +-- +-- @strTok@ returns a stateful computation of type @StrTokT a m [a]@ (or @StrTok a [a]@). +-- Several invocations of @strTok@ and computations with the results can be chained in the @StrTokT@ (resp. @StrTok@) +-- monad and then executed with @runStrTokT@ (resp. @runStrTok@). +-- +-- Example: +-- +-- >runStrTokT $ +-- > do a <- strTok (Just "- This, a sample string.") " ,.-" +-- > b <- strTok Nothing " ,.-" +-- > c <- strTok Nothing ",.-" +-- > return (a, b, c) +-- +-- evaluates to +-- +-- >("This","a"," sample string") +strTok :: (Eq a, Monad m) => Maybe [a] -> [a] -> StrTokT a m [a] +strTok s delims = StrTokT $ maybe strTok' (const . strTok') s + where strTok' = return . break (`elem` delims) . dropWhile (`elem` delims) + + diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,24 @@ +This is free and unencumbered software released into the public domain. + +Anyone is free to copy, modify, publish, use, compile, sell, or +distribute this software, either in source code form or as a compiled +binary, for any purpose, commercial or non-commercial, and by any +means. + +In jurisdictions that recognize copyright laws, the author or authors +of this software dedicate any and all copyright interest in the +software to the public domain. We make this dedication for the benefit +of the public at large and to the detriment of our heirs and +successors. We intend this dedication to be an overt act of +relinquishment in perpetuity of all present and future rights to this +software under copyright law. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +For more information, please refer to diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,2 @@ +import Distribution.Simple +main = defaultMain diff --git a/acme-strtok.cabal b/acme-strtok.cabal new file mode 100644 --- /dev/null +++ b/acme-strtok.cabal @@ -0,0 +1,67 @@ +-- Initial acme-strtok.cabal generated by cabal init. For further +-- documentation, see http://haskell.org/cabal/users-guide/ + +-- The name of the package. +name: acme-strtok + +-- The package version. See the Haskell package versioning policy (PVP) +-- for standards guiding when and how versions should be incremented. +-- http://www.haskell.org/haskellwiki/Package_versioning_policy +-- PVP summary: +-+------- breaking API changes +-- | | +----- non-breaking API additions +-- | | | +--- code changes with no API change +version: 0.1.0.0 + +-- A short (one-line) description of the package. +synopsis: A Haskell port of the C/PHP strtok function + +-- A longer description of the package. +-- description: This package provides a Haskell version of the strtok function from C/PHP. Successive calls of this function return tokens (delimited by given delimiting characters) from a string (or a list), one by one. + +-- The license under which the package is released. +license: PublicDomain + +-- The file containing the license text. +license-file: LICENSE + +-- The package author(s). +author: Manuel Eberl + +-- An email address to which users can send suggestions, bug reports, and +-- patches. +maintainer: last name + m _at_ in.tum.de + +-- A copyright notice. +-- copyright: + +category: ACME + +build-type: Simple + +-- Extra files to be distributed with the package, such as examples or a +-- README. +-- extra-source-files: + +-- Constraint on the version of Cabal needed to build this package. +cabal-version: >=1.10 + + +library + -- Modules exported by the library. + exposed-modules: Acme.StrTok + + -- Modules included in this library but not exported. + -- other-modules: + + -- LANGUAGE extensions used by modules in this package. + -- other-extensions: + + -- Other library packages from which modules are imported. + build-depends: base >=4.6 && <4.7, mtl >=2.1 && <2.2 + + -- Directories containing source files. + -- hs-source-dirs: + + -- Base language which the package is written in. + default-language: Haskell2010 +