Ch7 - Add anchors (#239)

* Ch7 replace code snippets with anchors

* Add removeAnchors.sh script

* remove unused unV code

Author: milesfrain

exercises/chapter7/src/Data/AddressBook.purs

@@ -8,14 +8,18 @@ type Address
     , state :: String
     }
 
+-- ANCHOR: address_anno
 address :: String -> String -> String -> Address
+-- ANCHOR_END: address_anno
 address street city state = { street, city, state }
 
+-- ANCHOR: PhoneType
 data PhoneType
   = HomePhone
   | WorkPhone
   | CellPhone
   | OtherPhone
+-- ANCHOR_END: PhoneType
 
 {-| derive has not been discussed yet but will be
 covered in Ch 10.  Here it is needed by the unit
@@ -35,7 +39,9 @@ type PhoneNumber
     , number :: String
     }
 
+-- ANCHOR: phoneNumber_anno
 phoneNumber :: PhoneType -> String -> PhoneNumber
+-- ANCHOR_END: phoneNumber_anno
 phoneNumber ty number =
   { "type": ty
   , number: number
@@ -48,13 +54,17 @@ type Person
     , phones :: Array PhoneNumber
     }
 
+-- ANCHOR: person_anno
 person :: String -> String -> Address -> Array PhoneNumber -> Person
+-- ANCHOR_END: person_anno
 person firstName lastName homeAddress phones = { firstName, lastName, homeAddress, phones }
 
+-- ANCHOR: examplePerson
 examplePerson :: Person
 examplePerson =
   person "John" "Smith"
     (address "123 Fake St." "FakeTown" "CA")
     [ phoneNumber HomePhone "555-555-5555"
     , phoneNumber CellPhone "555-555-0000"
     ]
+-- ANCHOR_END: examplePerson

exercises/chapter7/src/Data/AddressBook/Validation.purs

@@ -10,74 +10,124 @@ import Data.Traversable (traverse)
 import Data.Validation.Semigroup (V, unV, invalid)
 import Partial.Unsafe (unsafePartial)
 
+-----------------
+-- Some simple early examples returning `Either` instead of `V`:
+
+-- ANCHOR: nonEmpty1
+nonEmpty1 :: String -> Either String Unit
+nonEmpty1 "" = Left "Field cannot be empty"
+nonEmpty1 _  = Right unit
+-- ANCHOR_END: nonEmpty1
+
+-- ANCHOR: validatePerson1
+validatePerson1 :: Person -> Either String Person
+validatePerson1 p =
+  person <$> (nonEmpty1 p.firstName *> pure p.firstName)
+         <*> (nonEmpty1 p.lastName  *> pure p.lastName)
+         <*> pure p.homeAddress
+         <*> pure p.phones
+-- ANCHOR_END: validatePerson1
+
+-- ANCHOR: validatePerson1Ado
+validatePerson1Ado :: Person -> Either String Person
+validatePerson1Ado p = ado
+  f <- nonEmpty1 p.firstName *> pure p.firstName
+  l <- nonEmpty1 p.lastName *> pure p.firstName
+  in person f l p.homeAddress p.phones
+-- ANCHOR_END: validatePerson1Ado
+
+-----------------
+
+-- ANCHOR: Errors
 type Errors
   = Array String
+-- ANCHOR_END: Errors
 
+-- ANCHOR: nonEmpty
 nonEmpty :: String -> String -> V Errors Unit
 nonEmpty field "" = invalid [ "Field '" <> field <> "' cannot be empty" ]
+nonEmpty _     _  = pure unit
+-- ANCHOR_END: nonEmpty
 
-nonEmpty _ _ = pure unit
-
+-- ANCHOR: arrayNonEmpty
 arrayNonEmpty :: forall a. String -> Array a -> V Errors Unit
-arrayNonEmpty field [] = invalid [ "Field '" <> field <> "' must contain at least one value" ]
-
-arrayNonEmpty _ _ = pure unit
+arrayNonEmpty field [] =
+  invalid [ "Field '" <> field <> "' must contain at least one value" ]
+arrayNonEmpty _     _  =
+  pure unit
+-- ANCHOR_END: arrayNonEmpty
 
+-- ANCHOR: lengthIs
 lengthIs :: String -> Int -> String -> V Errors Unit
-lengthIs field len value
-  | length value /= len = invalid [ "Field '" <> field <> "' must have length " <> show len ]
-
-lengthIs _ _ _ = pure unit
+lengthIs field len value | length value /= len =
+  invalid [ "Field '" <> field <> "' must have length " <> show len ]
+lengthIs _     _   _     = pure unit
+-- ANCHOR_END: lengthIs
 
+-- ANCHOR: phoneNumberRegex
 phoneNumberRegex :: Regex
 phoneNumberRegex =
   unsafePartial case regex "^\\d{3}-\\d{3}-\\d{4}$" noFlags of
     Right r -> r
+-- ANCHOR_END: phoneNumberRegex
 
+-- ANCHOR: matches
 matches :: String -> Regex -> String -> V Errors Unit
-matches _ regex value
-  | test regex value = pure unit
-
-matches field _ _ = invalid [ "Field '" <> field <> "' did not match the required format" ]
+matches _     regex value | test regex value =
+  pure unit
+matches field _     _     =
+  invalid [ "Field '" <> field <> "' did not match the required format" ]
+-- ANCHOR_END: matches
 
+-- ANCHOR: validateAddress
 validateAddress :: Address -> V Errors Address
 validateAddress a =
-  address <$> (nonEmpty "Street" a.street *> pure a.street)
-    <*> (nonEmpty "City" a.city *> pure a.city)
-    <*> (lengthIs "State" 2 a.state *> pure a.state)
+  address <$> (nonEmpty "Street"  a.street *> pure a.street)
+          <*> (nonEmpty "City"    a.city   *> pure a.city)
+          <*> (lengthIs "State" 2 a.state  *> pure a.state)
+-- ANCHOR_END: validateAddress
 
+-- ANCHOR: validateAddressAdo
 validateAddressAdo :: Address -> V Errors Address
 validateAddressAdo a = ado
-  street <- (nonEmpty "Street" a.street *> pure a.street)
-  city <- (nonEmpty "City" a.city *> pure a.city)
-  state <- (lengthIs "State" 2 a.state *> pure a.state)
+  street <- (nonEmpty "Street"  a.street *> pure a.street)
+  city   <- (nonEmpty "City"    a.city   *> pure a.city)
+  state  <- (lengthIs "State" 2 a.state  *> pure a.state)
   in address street city state
+-- ANCHOR_END: validateAddressAdo
 
+-- ANCHOR: validatePhoneNumber
 validatePhoneNumber :: PhoneNumber -> V Errors PhoneNumber
 validatePhoneNumber pn =
   phoneNumber <$> pure pn."type"
-    <*> (matches "Number" phoneNumberRegex pn.number *> pure pn.number)
+              <*> (matches "Number" phoneNumberRegex pn.number *> pure pn.number)
+-- ANCHOR_END: validatePhoneNumber
 
+-- ANCHOR: validatePhoneNumberAdo
 validatePhoneNumberAdo :: PhoneNumber -> V Errors PhoneNumber
 validatePhoneNumberAdo pn = ado
-  tpe <- pure pn."type"
+  tpe    <- pure pn."type"
   number <- (matches "Number" phoneNumberRegex pn.number *> pure pn.number)
   in phoneNumber tpe number
+-- ANCHOR_END: validatePhoneNumberAdo
 
+-- ANCHOR: validatePerson
 validatePerson :: Person -> V Errors Person
 validatePerson p =
   person <$> (nonEmpty "First Name" p.firstName *> pure p.firstName)
-    <*> (nonEmpty "Last Name" p.lastName *> pure p.lastName)
-    <*> validateAddress p.homeAddress
-    <*> (arrayNonEmpty "Phone Numbers" p.phones *> traverse validatePhoneNumber p.phones)
+         <*> (nonEmpty "Last Name" p.lastName   *> pure p.lastName)
+         <*> validateAddress p.homeAddress
+         <*> (arrayNonEmpty "Phone Numbers" p.phones *>
+              traverse validatePhoneNumber p.phones)
+-- ANCHOR_END: validatePerson
 
+-- ANCHOR: validatePersonAdo
 validatePersonAdo :: Person -> V Errors Person
 validatePersonAdo p = ado
   firstName <- (nonEmpty "First Name" p.firstName *> pure p.firstName)
-  lastName <- (nonEmpty "Last Name" p.lastName *> pure p.lastName)
-  address <- validateAddress p.homeAddress
-  numbers <- (arrayNonEmpty "Phone Numbers" p.phones *> traverse validatePhoneNumber p.phones)
+  lastName  <- (nonEmpty "Last Name" p.lastName   *> pure p.lastName)
+  address   <- validateAddress p.homeAddress
+  numbers   <- (arrayNonEmpty "Phone Numbers" p.phones *>
+                traverse validatePhoneNumber p.phones)
   in person firstName lastName address numbers
-
-validatePerson' :: Person -> Either Errors Person
-validatePerson' p = unV Left Right $ validatePerson p
+-- ANCHOR_END: validatePersonAdo

scripts/removeAnchors.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+# This script removes all code anchors to improve readability
+
+# All .purs files in the exercises directories (excluding hidden files)
+ALL_PURS=$(find exercises \( ! -regex '.*/\..*' \) -type f -name '*.purs')
+
+for f in $ALL_PURS; do
+  # Delete lines starting with an '-- ANCHOR' comment
+  perl -ni -e 'print if !/^-- ANCHOR/' $f
+done

text/chapter2.md

@@ -15,10 +15,11 @@ Now that you've installed the necessary development tools, clone this book's rep
 git clone https://github.com/purescript-contrib/purescript-book.git
 ```
 
-The book repo contains PureScript example code and unit tests for the exercises that accompany each chapter. There's some initial setup required to reset the exercise solutions so they are ready to be solved by you. Use the `resetSolutions.sh` script to simplify this process:
+The book repo contains PureScript example code and unit tests for the exercises that accompany each chapter. There's some initial setup required to reset the exercise solutions so they are ready to be solved by you. Use the `resetSolutions.sh` script to simplify this process. While you're at it, you should also strip out all the anchor comments with the `removeAnchors.sh` script (these anchors are used for copying code snippets into the book's rendered markdown, and you probably don't need this clutter in your local repo):
 ```
 cd purescript-book
 ./scripts/resetSolutions.sh
+./scripts/removeAnchors.sh
 git commit --all --message "Exercises ready to be solved"
 ```