diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +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 +# 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 --- a/Flow.hs +++ b/Flow.hs @@ -1,229 +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) --} - -{- | - prop> (x |> f) == f x - - prop> (x |> f |> g) == g (f x) - - 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.&'). --} -infixl 0 |> -(|>) :: a -> (a -> b) -> b -x |> f = apply x f - -{- | - prop> (f <| x) == f x - - prop> (g <| f <| x) == g (f x) - - 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.$'). --} -infixr 0 <| -(<|) :: (a -> b) -> a -> b -f <| x = apply x f - -{- | - prop> apply x f == f x - - 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] --} -apply :: a -> (a -> b) -> b -apply x f = f x - -{- | - prop> (f .> g) x == g (f x) - - prop> (f .> g .> h) x == h (g (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.>>>'). --} -infixl 9 .> -(.>) :: (a -> b) -> (b -> c) -> (a -> c) -f .> g = compose f g - -{- | - prop> (g <. f) x == g (f x) - - prop> (h <. g <. f) x == h (g (f x)) - - 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..'). --} -infixr 9 <. -(<.) :: (b -> c) -> (a -> b) -> (a -> c) -g <. f = compose f g - -{- | - prop> compose f g x == g (f x) - - 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] --} -compose :: (a -> b) -> (b -> c) -> (a -> c) -compose f g = \ x -> g (f x) - -{- | - prop> (x !> f) == seq x (f x) - - prop> (x !> f !> g) == let y = seq x (f x) in seq y (g y) - - 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 - ... --} -infixl 0 !> -(!>) :: a -> (a -> b) -> b -x !> f = apply' x f - -{- | - prop> (f (g ') for 'Prelude.IO' actions since it puts the last function first. - - >>> print >> const True <| undefined - True - >>> const True b) -> a -> b -f apply' x f == seq x (f x) - - Strict 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] - - 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 - ... --} -apply' :: a -> (a -> b) -> b -apply' x f = seq x (apply x f) +-- | 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 --- a/FlowTest.hs +++ b/FlowTest.hs @@ -1,6 +1,6 @@ -module Main (main) where - -import Test.DocTest (doctest) - -main :: IO () -main = doctest ["Flow.hs"] +module Main (main) where + +import Test.DocTest (doctest) + +main :: IO () +main = doctest ["Flow.hs"] diff --git a/LICENSE.md b/LICENSE.md --- a/LICENSE.md +++ b/LICENSE.md @@ -1,23 +1,23 @@ -[The MIT License (MIT)][] - -Copyright (c) 2016 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. - -[The MIT License (MIT)]: https://opensource.org/licenses/MIT +[The MIT License (MIT)][] + +Copyright (c) 2016 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. + +[The MIT License (MIT)]: https://opensource.org/licenses/MIT diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,67 +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 = 0.9 && < 0.14 + QuickCheck ==2.* + , base <5 + , doctest >=0.9 && <0.14 , flow - , QuickCheck == 2.* - , template-haskell == 2.* + , template-haskell ==2.* + other-modules: + Paths_flow default-language: Haskell2010 diff --git a/package.yaml b/package.yaml --- a/package.yaml +++ b/package.yaml @@ -1,30 +1,30 @@ -name: flow -version: 1.0.9 - -category: Combinators, Functions, Utility -description: Flow provides operators for writing more understandable Haskell. -extra-source-files: - - CHANGELOG.md - - LICENSE.md - - package.yaml - - README.md - - stack.yaml -github: tfausak/flow -license: MIT -maintainer: Taylor Fausak -synopsis: Write more understandable Haskell. - -dependencies: base < 5 -ghc-options: -Wall - -library: - exposed-modules: Flow - -tests: - test: - dependencies: - - doctest >= 0.9 && < 0.14 - - flow - - QuickCheck == 2.* - - template-haskell == 2.* - main: FlowTest.hs +name: flow +version: 1.0.10 + +category: Combinators, Functions, Utility +description: Flow provides operators for writing more understandable Haskell. +extra-source-files: + - CHANGELOG.md + - LICENSE.md + - package.yaml + - README.md + - stack.yaml +github: tfausak/flow +license: MIT +maintainer: Taylor Fausak +synopsis: Write more understandable Haskell. + +dependencies: base < 5 +ghc-options: -Wall + +library: + exposed-modules: Flow + +tests: + test: + dependencies: + - doctest >= 0.9 && < 0.14 + - flow + - QuickCheck == 2.* + - template-haskell == 2.* + main: FlowTest.hs diff --git a/stack.yaml b/stack.yaml --- a/stack.yaml +++ b/stack.yaml @@ -1,1 +1,1 @@ -resolver: lts-9.0 +resolver: lts-10.0