diff --git a/CHANGELOG.markdown b/CHANGELOG.markdown deleted file mode 100644 --- a/CHANGELOG.markdown +++ /dev/null @@ -1,7 +0,0 @@ -# Change log - -Flow uses [Semantic Versioning][]. -The change log is available through the [releases on GitHub][]. - -[Semantic Versioning]: http://semver.org/spec/v2.0.0.html -[releases on GitHub]: https://github.com/tfausak/flow/releases diff --git a/README.markdown b/README.markdown --- a/README.markdown +++ b/README.markdown @@ -1,9 +1,10 @@ # [Flow][] -Write more understandable Haskell. +[![Travis CI](https://travis-ci.org/tfausak/flow.svg?branch=master)](https://travis-ci.org/tfausak/flow) +[![Hackage](https://img.shields.io/hackage/v/flow)](https://hackage.haskell.org/package/flow) +[![Stackage](https://www.stackage.org/package/flow/badge/nightly?label=stackage)](https://www.stackage.org/package/flow) -[![Version badge][]][version] -[![Build badge][]][build] +Write more understandable Haskell. Flow is a package that provides functions and operators for writing more understandable Haskell. It is an alternative to some common idioms like @@ -28,8 +29,6 @@ build-depends: flow ==1.0.* ``` -See [the change log][] for a detailed list of changes. - ## Usage Flow is designed to be imported unqualified. It does not export anything that @@ -56,11 +55,11 @@ ### Converting existing code If you want to uniformly use flow operators you can use [HLint] with the -`hlint-flow.yaml` file. For easy use, it is best to extract the +`hlint-flow.yaml` file. For easy use, it is best to extract the `hlint-flow.yaml` to your project directory and do ``` sh -> hlint -h hlint-flow.yaml +> hlint -h hlint-flow.yaml ``` or @@ -75,12 +74,7 @@ [HLint]: https://github.com/ndmitchell/hlint [Flow]: http://taylor.fausak.me/flow/ -[Version badge]: https://www.stackage.org/package/flow/badge/nightly?label=version -[version]: https://www.stackage.org/package/flow -[Build badge]: https://travis-ci.org/tfausak/flow.svg?branch=master -[build]: https://travis-ci.org/tfausak/flow [`($)`]: http://hackage.haskell.org/package/base-4.8.0.0/docs/Prelude.html#v:-36- [`(.)`]: http://hackage.haskell.org/package/base-4.8.0.0/docs/Prelude.html#v:. -[the change log]: CHANGELOG.md [the base package]: http://hackage.haskell.org/package/base [the haddock documentation]: https://hackage.haskell.org/package/flow/docs/Flow.html diff --git a/Setup.hs b/Setup.hs deleted file mode 100644 --- a/Setup.hs +++ /dev/null @@ -1,4 +0,0 @@ -import qualified Distribution.Simple as Cabal - -main :: IO () -main = Cabal.defaultMain diff --git a/flow.cabal b/flow.cabal --- a/flow.cabal +++ b/flow.cabal @@ -1,56 +1,57 @@ -cabal-version: 1.12 +cabal-version: 2.2 --- This file has been generated from package.yaml by hpack version 0.33.0. --- --- see: https://github.com/sol/hpack --- --- hash: 32ef4e8dec5e74445885402c3cbe452e1285bbc57f20413635974fcf5419226d +name: flow +version: 1.0.21 -name: flow -version: 1.0.20 -synopsis: Write more understandable Haskell. -description: Flow provides operators for writing more understandable Haskell. -category: Combinators, Functions, Utility -homepage: https://github.com/tfausak/flow#readme -bug-reports: https://github.com/tfausak/flow/issues -maintainer: Taylor Fausak -license: MIT -license-file: LICENSE.markdown -build-type: Simple -extra-source-files: - CHANGELOG.markdown - package.yaml - README.markdown - stack.yaml +synopsis: Write more understandable Haskell. +description: Flow provides operators for writing more understandable Haskell. +build-type: Simple +category: Combinators, Functions, Utility +extra-source-files: README.markdown +license-file: LICENSE.markdown +license: MIT +maintainer: Taylor Fausak + source-repository head type: git location: https://github.com/tfausak/flow +common basics + default-language: Haskell2010 + ghc-options: + -Weverything + -Wno-all-missed-specialisations + -Wno-implicit-prelude + -Wno-missing-exported-signatures + -Wno-missing-import-lists + -Wno-safe + -Wno-unsafe + + if impl(ghc >= 8.8) + ghc-options: + -Wno-missing-deriving-strategies + + if impl(ghc >= 8.10) + ghc-options: + -Wno-missing-safe-haskell-mode + -Wno-prepositive-qualified-module + library - exposed-modules: - Flow - other-modules: - Paths_flow - hs-source-dirs: - library - ghc-options: -Weverything -Wno-implicit-prelude -Wno-safe -Wno-unsafe + import: basics + build-depends: - base >=4.9.0 && <4.15 - default-language: Haskell2010 + base >= 4.9.0 && < 4.15 + exposed-modules: Flow + hs-source-dirs: src/lib test-suite test - type: exitcode-stdio-1.0 - main-is: Main.hs - other-modules: - Paths_flow - hs-source-dirs: - tests - ghc-options: -Weverything -Wno-implicit-prelude -Wno-safe -Wno-unsafe + import: basics + build-depends: - QuickCheck >=2.8.2 && <2.15 - , base >=4.9.0 && <4.15 - , doctest >=0.11.0 && <0.17 - , flow - , template-haskell >=2.11.0 && <2.17 - default-language: Haskell2010 + base -any + , flow -any + , HUnit >= 1.6.0 && < 1.7 + hs-source-dirs: src/test + main-is: Main.hs + type: exitcode-stdio-1.0 diff --git a/library/Flow.hs b/library/Flow.hs deleted file mode 100644 --- a/library/Flow.hs +++ /dev/null @@ -1,253 +0,0 @@ --- | Flow provides operators for writing more understandable Haskell. It is an --- alternative to some common idioms like ('Prelude.$') for function --- application and ('Prelude..') for function composition. --- --- Flow is designed to be imported unqualified. It does not export anything --- that conflicts with the base package. --- --- >>> import Flow --- --- == Rationale --- --- I think that Haskell can be hard to read. It has two operators for applying --- functions. Both are not really necessary and only serve to reduce --- parentheses. But they make code hard to read. People who do not already --- know Haskell have no chance of guessing what @foo $ bar@ or @baz & qux@ --- mean. --- --- Those that do know Haskell are forced to read lines forwards and backwards --- at the same time, thanks to function composition. Even something simple, --- like finding the minimum element, bounces around: @f = head . sort@. --- --- I think we can do better. By using directional operators, we can allow --- readers to move their eye in only one direction, be that left-to-right or --- right-to-left. And by using idioms common in other programming languages, --- we can allow people who aren't familiar with Haskell to guess at the --- meaning. --- --- So instead of ('Prelude.$'), I propose ('<|'). It is a pipe, which anyone --- who has touched a Unix system should be familiar with. And it points in the --- direction it sends arguments along. Similarly, replace ('Prelude.&') with --- ('|>'). And for composition, ('<.') replaces ('Prelude..'). I would have --- preferred @<<@, but its counterpart @>>@ is taken by Haskell's syntax. --- So-called "backwards" composition is normally expressed with --- ('Control.Category.>>>'), which Flow provides as ('.>'). -module Flow ( - -- * Function application - (|>), (<|), apply, - -- * Function composition - (.>), (<.), compose, - -- * Strict function application - (!>), (>> import Prelude --- >>> let f = (+ 3) --- >>> let g = (* 3) --- >>> let h = (^ 3) - --- | Left-associative 'apply' operator. Read as "apply forward" or "pipe into". --- Use this to create long chains of computation that suggest which direction --- things move in. --- --- >>> 3 |> succ |> recip |> negate --- -0.25 --- --- Or use it anywhere you would use ('Prelude.&'). --- --- prop> \ x -> (x |> f) == f x --- --- prop> \ x -> (x |> f |> g) == g (f x) -infixl 0 |> -(|>) :: a -> (a -> b) -> b -x |> f = apply x f - --- | Right-associative 'apply' operator. Read as "apply backward" or "pipe --- from". Use this to create long chains of computation that suggest which --- direction things move in. You may prefer this operator over ('|>') for --- 'Prelude.IO' actions since it puts the last function first. --- --- >>> print <| negate <| recip <| succ <| 3 --- -0.25 --- --- Or use it anywhere you would use ('Prelude.$'). --- --- Note that ('<|') and ('|>') have the same precedence, so they cannot be used --- together. --- --- >>> -- This doesn't work! --- >>> -- print <| 3 |> succ |> recip |> negate --- --- prop> \ x -> (f <| x) == f x --- --- prop> \ x -> (g <| f <| x) == g (f x) -infixr 0 <| -(<|) :: (a -> b) -> a -> b -f <| x = apply x f - --- | Function application. This function usually isn't necessary, but it can be --- more readable than some alternatives when used with higher-order functions --- like 'Prelude.map'. --- --- >>> map (apply 2) [succ, recip, negate] --- [3.0,0.5,-2.0] --- --- In general you should prefer using an explicit lambda or operator section. --- --- >>> map (\ f -> 2 |> f) [succ, recip, negate] --- [3.0,0.5,-2.0] --- >>> map (2 |>) [succ, recip, negate] --- [3.0,0.5,-2.0] --- >>> map (<| 2) [succ, recip, negate] --- [3.0,0.5,-2.0] --- --- prop> \ x -> apply x f == f x -apply :: a -> (a -> b) -> b -apply x f = f x - --- | Left-associative 'compose' operator. Read as "compose forward" or "and --- then". Use this to create long chains of computation that suggest which --- direction things move in. --- --- >>> let f = succ .> recip .> negate --- >>> f 3 --- -0.25 --- --- Or use it anywhere you would use ('Control.Category.>>>'). --- --- prop> \ x -> (f .> g) x == g (f x) --- --- prop> \ x -> (f .> g .> h) x == h (g (f x)) -infixl 9 .> -(.>) :: (a -> b) -> (b -> c) -> (a -> c) -f .> g = compose f g - --- | Right-associative 'compose' operator. Read as "compose backward" or "but --- first". Use this to create long chains of computation that suggest which --- direction things move in. You may prefer this operator over ('.>') for --- 'Prelude.IO' actions since it puts the last function first. --- --- >>> let f = print <. negate <. recip <. succ --- >>> f 3 --- -0.25 --- --- Or use it anywhere you would use ('Prelude..'). --- --- Note that ('<.') and ('.>') have the same precedence, so they cannot be used --- together. --- --- >>> -- This doesn't work! --- >>> -- print <. succ .> recip .> negate --- --- prop> \ x -> (g <. f) x == g (f x) --- --- prop> \ x -> (h <. g <. f) x == h (g (f x)) -infixr 9 <. -(<.) :: (b -> c) -> (a -> b) -> (a -> c) -g <. f = compose f g - --- | Function composition. This function usually isn't necessary, but it can be --- more readable than some alternatives when used with higher-order functions --- like 'Prelude.map'. --- --- >>> let fs = map (compose succ) [recip, negate] --- >>> map (apply 3) fs --- [0.25,-4.0] --- --- In general you should prefer using an explicit lambda or operator section. --- --- >>> map (\ f -> f 3) (map (\ f -> succ .> f) [recip, negate]) --- [0.25,-4.0] --- >>> map (\ f -> f 3) (map (succ .>) [recip, negate]) --- [0.25,-4.0] --- >>> map (\ f -> f 3) (map (<. succ) [recip, negate]) --- [0.25,-4.0] --- --- prop> \ x -> compose f g x == g (f x) -compose :: (a -> b) -> (b -> c) -> (a -> c) -compose f g = \ x -> g (f x) - --- | Left-associative 'apply'' operator. Read as "strict apply forward" or --- "strict pipe into". Use this to create long chains of computation that --- suggest which direction things move in. --- --- >>> 3 !> succ !> recip !> negate --- -0.25 --- --- The difference between this and ('|>') is that this evaluates its argument --- before passing it to the function. --- --- >>> undefined |> const True --- True --- >>> undefined !> const True --- *** Exception: Prelude.undefined --- ... --- --- prop> \ x -> (x !> f) == seq x (f x) --- --- prop> \ x -> (x !> f !> g) == let y = seq x (f x) in seq y (g y) -infixl 0 !> -(!>) :: a -> (a -> b) -> b -x !> f = apply' x f - --- | Right-associative 'apply'' operator. Read as "strict apply backward" or --- "strict pipe from". Use this to create long chains of computation that --- suggest which direction things move in. You may prefer this operator over --- ('!>') for 'Prelude.IO' actions since it puts the last function first. --- --- >>> print >> const True <| undefined --- True --- >>> const True ') have the same precedence, so they cannot be used --- together. --- --- >>> -- This doesn't work! --- >>> -- print succ !> recip !> negate --- --- prop> \ x -> (f \ x -> (g b) -> a -> b -f >> map (apply' 2) [succ, recip, negate] --- [3.0,0.5,-2.0] --- --- The different between this and 'apply' is that this evaluates its argument --- before passing it to the function. --- --- >>> apply undefined (const True) --- True --- >>> apply' undefined (const True) --- *** Exception: Prelude.undefined --- ... --- --- In general you should prefer using an explicit lambda or operator section. --- --- >>> map (\ f -> 2 !> f) [succ, recip, negate] --- [3.0,0.5,-2.0] --- >>> map (2 !>) [succ, recip, negate] --- [3.0,0.5,-2.0] --- >>> map ( \ x -> apply' x f == seq x (f x) -apply' :: a -> (a -> b) -> b -apply' x f = seq x (apply x f) diff --git a/package.yaml b/package.yaml deleted file mode 100644 --- a/package.yaml +++ /dev/null @@ -1,36 +0,0 @@ -name: flow -version: 1.0.20 - -category: Combinators, Functions, Utility -description: Flow provides operators for writing more understandable Haskell. -extra-source-files: - - CHANGELOG.markdown - - package.yaml - - README.markdown - - stack.yaml -github: tfausak/flow -license-file: LICENSE.markdown -license: MIT -maintainer: Taylor Fausak -synopsis: Write more understandable Haskell. - -dependencies: - base: '>= 4.9.0 && < 4.15' -ghc-options: - -Weverything - -Wno-implicit-prelude - -Wno-safe - -Wno-unsafe - -library: - source-dirs: library - -tests: - test: - dependencies: - doctest: '>= 0.11.0 && < 0.17' - flow: -any - QuickCheck: '>= 2.8.2 && < 2.15' - template-haskell: '>= 2.11.0 && < 2.17' - main: Main.hs - source-dirs: tests diff --git a/src/lib/Flow.hs b/src/lib/Flow.hs new file mode 100644 --- /dev/null +++ b/src/lib/Flow.hs @@ -0,0 +1,247 @@ +-- | Flow provides operators for writing more understandable Haskell. It is an +-- alternative to some common idioms like ('Prelude.$') for function +-- application and ('Prelude..') for function composition. +-- +-- Flow is designed to be imported unqualified. It does not export anything +-- that conflicts with the base package. +-- +-- >>> import Flow +-- +-- == Rationale +-- +-- I think that Haskell can be hard to read. It has two operators for applying +-- functions. Both are not really necessary and only serve to reduce +-- parentheses. But they make code hard to read. People who do not already +-- know Haskell have no chance of guessing what @foo $ bar@ or @baz & qux@ +-- mean. +-- +-- Those that do know Haskell are forced to read lines forwards and backwards +-- at the same time, thanks to function composition. Even something simple, +-- like finding the minimum element, bounces around: @f = head . sort@. +-- +-- I think we can do better. By using directional operators, we can allow +-- readers to move their eye in only one direction, be that left-to-right or +-- right-to-left. And by using idioms common in other programming languages, +-- we can allow people who aren't familiar with Haskell to guess at the +-- meaning. +-- +-- So instead of ('Prelude.$'), I propose ('<|'). It is a pipe, which anyone +-- who has touched a Unix system should be familiar with. And it points in the +-- direction it sends arguments along. Similarly, replace ('Prelude.&') with +-- ('|>'). And for composition, ('<.') replaces ('Prelude..'). I would have +-- preferred @<<@, but its counterpart @>>@ is taken by Haskell's syntax. +-- So-called "backwards" composition is normally expressed with +-- ('Control.Category.>>>'), which Flow provides as ('.>'). +module Flow ( + -- * Function application + (|>), (<|), apply, + -- * Function composition + (.>), (<.), compose, + -- * Strict function application + (!>), (>> 3 |> succ |> recip |> negate +-- -0.25 +-- +-- Or use it anywhere you would use ('Prelude.&'). +-- +-- prop> \ x -> (x |> f) == f x +-- +-- prop> \ x -> (x |> f |> g) == g (f x) +infixl 0 |> +(|>) :: a -> (a -> b) -> b +x |> f = apply x f + +-- | Right-associative 'apply' operator. Read as "apply backward" or "pipe +-- from". Use this to create long chains of computation that suggest which +-- direction things move in. You may prefer this operator over ('|>') for +-- 'Prelude.IO' actions since it puts the last function first. +-- +-- >>> print <| negate <| recip <| succ <| 3 +-- -0.25 +-- +-- Or use it anywhere you would use ('Prelude.$'). +-- +-- Note that ('<|') and ('|>') have the same precedence, so they cannot be used +-- together. +-- +-- >>> -- This doesn't work! +-- >>> -- print <| 3 |> succ |> recip |> negate +-- +-- prop> \ x -> (f <| x) == f x +-- +-- prop> \ x -> (g <| f <| x) == g (f x) +infixr 0 <| +(<|) :: (a -> b) -> a -> b +f <| x = apply x f + +-- | Function application. This function usually isn't necessary, but it can be +-- more readable than some alternatives when used with higher-order functions +-- like 'Prelude.map'. +-- +-- >>> map (apply 2) [succ, recip, negate] +-- [3.0,0.5,-2.0] +-- +-- In general you should prefer using an explicit lambda or operator section. +-- +-- >>> map (\ f -> 2 |> f) [succ, recip, negate] +-- [3.0,0.5,-2.0] +-- >>> map (2 |>) [succ, recip, negate] +-- [3.0,0.5,-2.0] +-- >>> map (<| 2) [succ, recip, negate] +-- [3.0,0.5,-2.0] +-- +-- prop> \ x -> apply x f == f x +apply :: a -> (a -> b) -> b +apply x f = f x + +-- | Left-associative 'compose' operator. Read as "compose forward" or "and +-- then". Use this to create long chains of computation that suggest which +-- direction things move in. +-- +-- >>> let f = succ .> recip .> negate +-- >>> f 3 +-- -0.25 +-- +-- Or use it anywhere you would use ('Control.Category.>>>'). +-- +-- prop> \ x -> (f .> g) x == g (f x) +-- +-- prop> \ x -> (f .> g .> h) x == h (g (f x)) +infixl 9 .> +(.>) :: (a -> b) -> (b -> c) -> (a -> c) +f .> g = compose f g + +-- | Right-associative 'compose' operator. Read as "compose backward" or "but +-- first". Use this to create long chains of computation that suggest which +-- direction things move in. You may prefer this operator over ('.>') for +-- 'Prelude.IO' actions since it puts the last function first. +-- +-- >>> let f = print <. negate <. recip <. succ +-- >>> f 3 +-- -0.25 +-- +-- Or use it anywhere you would use ('Prelude..'). +-- +-- Note that ('<.') and ('.>') have the same precedence, so they cannot be used +-- together. +-- +-- >>> -- This doesn't work! +-- >>> -- print <. succ .> recip .> negate +-- +-- prop> \ x -> (g <. f) x == g (f x) +-- +-- prop> \ x -> (h <. g <. f) x == h (g (f x)) +infixr 9 <. +(<.) :: (b -> c) -> (a -> b) -> (a -> c) +g <. f = compose f g + +-- | Function composition. This function usually isn't necessary, but it can be +-- more readable than some alternatives when used with higher-order functions +-- like 'Prelude.map'. +-- +-- >>> let fs = map (compose succ) [recip, negate] +-- >>> map (apply 3) fs +-- [0.25,-4.0] +-- +-- In general you should prefer using an explicit lambda or operator section. +-- +-- >>> map (\ f -> f 3) (map (\ f -> succ .> f) [recip, negate]) +-- [0.25,-4.0] +-- >>> map (\ f -> f 3) (map (succ .>) [recip, negate]) +-- [0.25,-4.0] +-- >>> map (\ f -> f 3) (map (<. succ) [recip, negate]) +-- [0.25,-4.0] +-- +-- prop> \ x -> compose f g x == g (f x) +compose :: (a -> b) -> (b -> c) -> (a -> c) +compose f g = \ x -> g (f x) + +-- | Left-associative 'apply'' operator. Read as "strict apply forward" or +-- "strict pipe into". Use this to create long chains of computation that +-- suggest which direction things move in. +-- +-- >>> 3 !> succ !> recip !> negate +-- -0.25 +-- +-- The difference between this and ('|>') is that this evaluates its argument +-- before passing it to the function. +-- +-- >>> undefined |> const True +-- True +-- >>> undefined !> const True +-- *** Exception: Prelude.undefined +-- ... +-- +-- prop> \ x -> (x !> f) == seq x (f x) +-- +-- prop> \ x -> (x !> f !> g) == let y = seq x (f x) in seq y (g y) +infixl 0 !> +(!>) :: a -> (a -> b) -> b +x !> f = apply' x f + +-- | Right-associative 'apply'' operator. Read as "strict apply backward" or +-- "strict pipe from". Use this to create long chains of computation that +-- suggest which direction things move in. You may prefer this operator over +-- ('!>') for 'Prelude.IO' actions since it puts the last function first. +-- +-- >>> print >> const True <| undefined +-- True +-- >>> const True ') have the same precedence, so they cannot be used +-- together. +-- +-- >>> -- This doesn't work! +-- >>> -- print succ !> recip !> negate +-- +-- prop> \ x -> (f \ x -> (g b) -> a -> b +f >> map (apply' 2) [succ, recip, negate] +-- [3.0,0.5,-2.0] +-- +-- The different between this and 'apply' is that this evaluates its argument +-- before passing it to the function. +-- +-- >>> apply undefined (const True) +-- True +-- >>> apply' undefined (const True) +-- *** Exception: Prelude.undefined +-- ... +-- +-- In general you should prefer using an explicit lambda or operator section. +-- +-- >>> map (\ f -> 2 !> f) [succ, recip, negate] +-- [3.0,0.5,-2.0] +-- >>> map (2 !>) [succ, recip, negate] +-- [3.0,0.5,-2.0] +-- >>> map ( \ x -> apply' x f == seq x (f x) +apply' :: a -> (a -> b) -> b +apply' x f = seq x (apply x f) diff --git a/src/test/Main.hs b/src/test/Main.hs new file mode 100644 --- /dev/null +++ b/src/test/Main.hs @@ -0,0 +1,36 @@ +import qualified Control.Monad as Monad +import qualified Flow +import qualified System.Exit as Exit +import qualified Test.HUnit as Test + +main :: IO () +main = do + counts <- Test.runTestTT $ Test.TestList + [ True Test.~?= True + , (3 Flow.|> succ Flow.|> recip Flow.|> negate) Test.~?= (-0.25 :: Double) + , (negate Flow.<| recip Flow.<| succ Flow.<| 3) Test.~?= (-0.25 :: Double) + , map (Flow.apply 2) [succ, recip, negate] Test.~?= [3, 0.5, -2 :: Double] + , map (\ f -> 2 Flow.|> f) [succ, recip, negate] Test.~?= [3, 0.5, -2 :: Double] + , map (2 Flow.|>) [succ, recip, negate] Test.~?= [3, 0.5, -2 :: Double] + , map (Flow.<| 2) [succ, recip, negate] Test.~?= [3, 0.5, -2 :: Double] + , map (Flow.apply 3) (map (Flow.compose succ) [recip, negate]) Test.~?= [0.25, -4 :: Double] + , (succ Flow..> recip Flow..> negate) 3 Test.~?= (-0.25 :: Double) + , (negate Flow.<. recip Flow.<. succ) 3 Test.~?= (-0.25 :: Double) + , map (\ f -> f 3) (map (\ f -> succ Flow..> f) [recip, negate]) Test.~?= [0.25, -4 :: Double] + , map (\ f -> f 3) (map (succ Flow..>) [recip, negate]) Test.~?= [0.25, -4 :: Double] + , map (\ f -> f 3) (map (Flow.<. succ) [recip, negate]) Test.~?= [0.25, -4 :: Double] + , (3 Flow.!> succ Flow.!> recip Flow.!> negate) Test.~?= (-0.25 :: Double) + , (undefined Flow.|> const True) Test.~?= True + , (negate Flow. 2 Flow.!> f) [succ, recip, negate] Test.~?= [3, 0.5, -2 :: Double] + , map (2 Flow.!>) [succ, recip, negate] Test.~?= [3, 0.5, -2 :: Double] + , map (Flow.