diff --git a/CHANGELOG.markdown b/CHANGELOG.markdown new file mode 100644 --- /dev/null +++ b/CHANGELOG.markdown @@ -0,0 +1,7 @@ +# 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/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 --- a/CHANGELOG.md +++ /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/Flow.hs b/Flow.hs deleted file mode 100644 --- a/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 info". 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/FlowTest.hs b/FlowTest.hs deleted file mode 100644 --- a/FlowTest.hs +++ /dev/null @@ -1,6 +0,0 @@ -module Main (main) where - -import Test.DocTest (doctest) - -main :: IO () -main = doctest ["Flow.hs"] diff --git a/LICENSE.markdown b/LICENSE.markdown new file mode 100644 --- /dev/null +++ b/LICENSE.markdown @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2018 Taylor Fausak + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +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 OR COPYRIGHT HOLDERS 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. diff --git a/LICENSE.md b/LICENSE.md deleted file mode 100644 --- a/LICENSE.md +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2018 Taylor Fausak - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -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 OR COPYRIGHT HOLDERS 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. diff --git a/README.markdown b/README.markdown new file mode 100644 --- /dev/null +++ b/README.markdown @@ -0,0 +1,67 @@ +# [Flow][] + +Write more understandable Haskell. + +[![Version badge][]][version] +[![Build badge][]][build] + +Flow is a package that provides functions and operators for writing more +understandable Haskell. It is an alternative to some common idioms like +[`($)`][] for function application and [`(.)`][] for function composition. + +- [Requirements](#requirements) +- [Installation](#installation) +- [Usage](#usage) + - [Cheat sheet](#cheat-sheet) + +## Requirements + +Flow requires a Haskell compiler. It is tested with recent versions of GHC, but +older or different compilers should be acceptable. For installation with Cabal, +Flow requires at least Cabal 1.8. + +## Installation + +To add Flow as a dependency to your package, add it to your Cabal file. + +``` +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 +conflicts with [the base package][]. + +``` hs +import Flow +``` + +### Cheat sheet + +Flow | Base +--------------- | ------------- +x |> f | `x & f` +f <| x | `f $ x` +`apply x f` | `f x` +`f .> g` | `f >>> g` +`g <. f` | `g . f` +`compose f g x` | `g (f x)` +`x !> f` | - +`f x |> f | `x & f` -f <| x | `f $ x` -`apply x f` | `f x` -`f .> g` | `f >>> g` -`g <. f` | `g . f` -`compose f g x` | `g (f x)` -`x !> f` | - -`f = 1.10 extra-source-files: - CHANGELOG.md - LICENSE.md + CHANGELOG.markdown package.yaml - README.md + README.markdown stack.yaml source-repository head @@ -28,9 +28,11 @@ location: https://github.com/tfausak/flow library - ghc-options: -Wall + hs-source-dirs: + library + ghc-options: -Weverything -Wno-implicit-prelude -Wno-safe -Wno-unsafe build-depends: - base <5 + base >=4.9.0 && <4.12 exposed-modules: Flow other-modules: @@ -39,14 +41,16 @@ test-suite test type: exitcode-stdio-1.0 - main-is: FlowTest.hs - ghc-options: -Wall + main-is: Main.hs + hs-source-dirs: + tests + ghc-options: -Weverything -Wno-implicit-prelude -Wno-safe -Wno-unsafe build-depends: - QuickCheck ==2.* - , base <5 - , doctest >=0.9 && <0.15 + QuickCheck >=2.8.2 && <2.12 + , base >=4.9.0 && <4.12 + , doctest >=0.11.0 && <0.16 , flow - , template-haskell ==2.* + , template-haskell >=2.11.0 && <2.14 other-modules: Paths_flow default-language: Haskell2010 diff --git a/library/Flow.hs b/library/Flow.hs new file mode 100644 --- /dev/null +++ b/library/Flow.hs @@ -0,0 +1,253 @@ +-- | 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 info". 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 --- a/package.yaml +++ b/package.yaml @@ -1,30 +1,36 @@ name: flow -version: 1.0.11 +version: 1.0.12 category: Combinators, Functions, Utility description: Flow provides operators for writing more understandable Haskell. extra-source-files: - - CHANGELOG.md - - LICENSE.md + - CHANGELOG.markdown - package.yaml - - README.md + - README.markdown - stack.yaml github: tfausak/flow +license-file: LICENSE.markdown license: MIT maintainer: Taylor Fausak synopsis: Write more understandable Haskell. -dependencies: base < 5 -ghc-options: -Wall +dependencies: + base: '>= 4.9.0 && < 4.12' +ghc-options: + -Weverything + -Wno-implicit-prelude + -Wno-safe + -Wno-unsafe library: - exposed-modules: Flow + source-dirs: library tests: test: dependencies: - - doctest >= 0.9 && < 0.15 - - flow - - QuickCheck == 2.* - - template-haskell == 2.* - main: FlowTest.hs + doctest: '>= 0.11.0 && < 0.16' + flow: -any + QuickCheck: '>= 2.8.2 && < 2.12' + template-haskell: '>= 2.11.0 && < 2.14' + main: Main.hs + source-dirs: tests diff --git a/stack.yaml b/stack.yaml --- a/stack.yaml +++ b/stack.yaml @@ -1,1 +1,1 @@ -resolver: lts-10.0 +resolver: lts-7.0 diff --git a/tests/Main.hs b/tests/Main.hs new file mode 100644 --- /dev/null +++ b/tests/Main.hs @@ -0,0 +1,4 @@ +import qualified Test.DocTest as Doctest + +main :: IO () +main = Doctest.doctest ["library"]