From 5b63e9244a35d6e94926653a2ae0b4bab6e20a0b Mon Sep 17 00:00:00 2001 From: Brian Marick Date: Sun, 24 Jun 2018 18:21:54 -0500 Subject: [PATCH 1/2] More documentation in the module header --- src/Data/Tuple/Nested.purs | 74 +++++++++++++++++++++++++++++--------- 1 file changed, 58 insertions(+), 16 deletions(-) diff --git a/src/Data/Tuple/Nested.purs b/src/Data/Tuple/Nested.purs index 5154c49..044b1df 100644 --- a/src/Data/Tuple/Nested.purs +++ b/src/Data/Tuple/Nested.purs @@ -1,26 +1,68 @@ --- | Utilities for n-tuples: sequences longer than two components built from --- | nested pairs. +-- | Tuples that are not restricted to two elements. -- | --- | Nested tuples arise naturally in product combinators. You shouldn't --- | represent data using nested tuples, but if combinators you're working with --- | create them, utilities in this module will allow to to more easily work --- | with them, including translating to and from more traditional product types. +-- | Here is an example of a 3-tuple: -- | +-- | -- | ```purescript --- | data Address = Address String City (Maybe Province) Country --- | --- | exampleAddress1 = makeAddress "221B Baker Street" London Nothing UK --- | exampleAddress2 = makeAddressT $ "221B Baker Street" /\ London /\ Nothing /\ UK +-- | > tuple = tuple3 1 "2" 3.0 +-- | > tuple +-- | (Tuple 1 (Tuple "2" (Tuple 3.0 unit))) +-- | ``` +-- | +-- | Notice that a tuple is a nested structure not unlike a list. The type of `tuple` is this: +-- | +-- | ```purescript +-- | > :t tuple +-- | Tuple Int (Tuple String (Tuple Number Unit)) +-- | ``` +-- | +-- | That, however, can be abbreviated with the `Tuple3` type: +-- | +-- | ```purescript +-- | Tuple3 Int String Number +-- | ``` -- | --- | makeAddressT :: Tuple4 String City (Maybe Province) Country -> Address --- | makeAddressT = uncurry4 Address +-- | All tuple functions are numbered from 1 to 10. That is, there's +-- | an `get1` and a `get10`. -- | --- | makeAddress :: String -> City -> (Maybe Province) -> Country -> Address --- | makeAddress = curry4 unit makeAddressT +-- | The `getN` functions accept tuples of length N or greater: +-- | +-- | ```purescript +-- | get1 tuple == 1 +-- | get3 tuple == 3 +-- | get4 tuple == error +-- | ``` +-- | +-- | The same is true of the `overN` functions: +-- | +-- | ```purescript +-- | over2 negate (tuple3 1 2 3) == tuple3 1 -2 3 +-- | ``` -- | --- | tupleAddress :: Address -> Tuple4 String City (Maybe Province) Country --- | tupleAddress (Address a b c d) = tuple4 a b c d + +-- | `uncurryN` can be used to convert a function that takes `N` arguments to one that takes an N-tuple: +-- | +-- | ```purescript +-- | (uncurry2 (+)) (tuple2 1 2) == 3 -- | ``` +-- | +-- | The reverse `curryN` function converts functions that take +-- | N-tuples (which are rare) to functions that take `N` arguments. +-- | +-- | --------------- +-- | Nested tuples arise naturally in product combinators. You shouldn't +-- | represent data using nested tuples, but if combinators you're working with +-- | create them, utilities in this module will allow you to more easily work +-- | with them, including translating to and from more traditional product types. +-- | +-- | --------------- +-- | In addition to types like `Tuple3`, there are also types like +-- | `T3`. Whereas `Tuple3` describes a tuple with exactly three +-- | elements, `T3` describes a tuple of length *two or longer*. More +-- | specifically, `T3` requires two element plus a "tail" that may be +-- | `unit` or more tuple elements. Use types like `T3` when you want to +-- | create a set of functions for arbitrary tuples. See the source for how that's done. +-- | module Data.Tuple.Nested where import Prelude From ae2cdb79207d295aed8ea87d68602366156950d1 Mon Sep 17 00:00:00 2001 From: Brian Marick Date: Sat, 10 Nov 2018 15:22:17 -0600 Subject: [PATCH 2/2] Implement suggestions of @LiamGoodacre on previous pull request. --- src/Data/Tuple/Nested.purs | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/src/Data/Tuple/Nested.purs b/src/Data/Tuple/Nested.purs index 044b1df..156547a 100644 --- a/src/Data/Tuple/Nested.purs +++ b/src/Data/Tuple/Nested.purs @@ -23,39 +23,33 @@ -- | ``` -- | -- | All tuple functions are numbered from 1 to 10. That is, there's --- | an `get1` and a `get10`. +-- | a `get1` and a `get10`. -- | -- | The `getN` functions accept tuples of length N or greater: -- | -- | ```purescript --- | get1 tuple == 1 --- | get3 tuple == 3 --- | get4 tuple == error +-- | get1 tuple = 1 +-- | get3 tuple = 3 +-- | get4 tuple -- type error. `get4` requires a longer tuple. -- | ``` -- | -- | The same is true of the `overN` functions: -- | -- | ```purescript --- | over2 negate (tuple3 1 2 3) == tuple3 1 -2 3 +-- | over2 negate (tuple3 1 2 3) = tuple3 1 (-2) 3 -- | ``` -- | -- | `uncurryN` can be used to convert a function that takes `N` arguments to one that takes an N-tuple: -- | -- | ```purescript --- | (uncurry2 (+)) (tuple2 1 2) == 3 +-- | uncurry2 (+) (tuple2 1 2) = 3 -- | ``` -- | -- | The reverse `curryN` function converts functions that take -- | N-tuples (which are rare) to functions that take `N` arguments. -- | -- | --------------- --- | Nested tuples arise naturally in product combinators. You shouldn't --- | represent data using nested tuples, but if combinators you're working with --- | create them, utilities in this module will allow you to more easily work --- | with them, including translating to and from more traditional product types. --- | --- | --------------- -- | In addition to types like `Tuple3`, there are also types like -- | `T3`. Whereas `Tuple3` describes a tuple with exactly three -- | elements, `T3` describes a tuple of length *two or longer*. More