Update kinds, add newer syntaxes, notes (documentationjs#75)

* Update kinds

* Pattern guards

* Nested records

Fixes documentationjs#18. Todo: Unify with Records.md?

* Expand section on type synonyms

The example involving `one` did not type check. Now it does. Maybe it would be helpful to think of real-world examples for type synonyms and use those here intead of another example involving Foo & Bar.

* Notes that I would find helpful

* Do something with the bound variable

* Misc. formatting

* Typo, hopefully a bit clearer

* Grammar

Author: Nicholas Scheel

language/FFI.md

@@ -31,15 +31,15 @@ Importing Types
 To declare a new abstract type (with no constructors), use `foreign import data` and provide the kind:
 
 ```purescript
-foreign import data DOMElement :: *
+foreign import data DOMElement :: Type
 
 foreign import document :: {
   createElement :: String -> DOMElement
 }
 ```
 
-When declaring types in this way, you may declare your type to have any kind, not just `*`. For example, to declare a row of effects:
+When declaring types in this way, you may declare your type to have any kind, not just `Type`. For example, to declare a row of effects:
 
 ```purescript
-foreign import data MyRow :: # !
+foreign import data MyRow :: # Effect
 ```

language/Modules.md

@@ -26,20 +26,20 @@ module B where
 import A (runFoo)
 ```
 
-Values, type constructors, data constructors, and type classes can all be explicitly imported. A type constructor can be followed by a list of associated data constructors to import in parentheses. A double dot (`..`) can be used to import all data constructors for a given type constructor:
+Values, operators (wrapped in parentheses), type constructors, data constructors, and type classes can all be explicitly imported. A type constructor can be followed by a list of associated data constructors to import in parentheses. A double dot (`..`) can be used to import all data constructors for a given type constructor:
 
 ```purescript
 module B where
 
-import A (runFoo, Foo(..), Bar(Bar))
+import A (runFoo, (.~), Foo(..), Bar(Bar))
 ```
 
-Type classes are imported using the `class` keyword:
+Type classes are imported using the `class` keyword, kinds with `kind`:
 
 ```purescript
 module B where
 
-import A (class Fab)
+import A (class Fab, kind Effect)
 ```
 
 ### Hiding imports
@@ -59,16 +59,33 @@ Modules can also be imported qualified, which means that their names will not be
 
 ```purescript
 module Main where
-  
+
 import Data.Array as Array
-  
+
 null = ...
 
 test = Array.null [1, 2, 3]
 ```
-  
+
 Here, the name ``null`` would ordinarily conflict with ``null`` from ``Data.Array``, but the qualified import solves this problem. ``Data.Array.null`` can be referenced using ``Array.null`` instead.
 
+Operators can also be referenced this way:
+```purescript
+test' = Array.null ([1, 2, 3] Array.\\ [1, 2, 3])
+```
+
+Modules can be merged under the same name, but it is best to use explicit imports to avoid conflicts, in case modules would want to import the same name:
+
+```purescript
+module Main where
+
+import Data.String.Regex (split) as Re
+import Data.String.Regex.Flags (global) as Re
+import Data.String.Regex.Unsafe (unsafeRegex) as Re
+
+split = Re.split (Re.unsafeRegex "[,;:.]\\s+" Re.global)
+```
+
 ## Module Exports
 
 You can control what gets exported from a module by using an export list. When an export list is used, other modules will only be able to see things which are in the export list. For example:
@@ -95,6 +112,15 @@ module A (module B) where
 import B
 ```
 
+Qualified and explicit imports can be used also:
+
+```purescript
+module A (module MoreExports) where
+
+import A.Util (useful, usefulFn) as MoreExports
+import A.Type (ADatatype(..)) as MoreExports
+```
+
 When re-exporting other modules, all local values and types can also be exported by specifying the module itself as an export:
 
 ```purescript

language/Pattern-Matching.md

@@ -23,16 +23,17 @@ Patterns can also be used when introducing functions. For example:
 example x y z = x * y + z
 ```
 
-The following pattern types are supported:
+The following forms can be used for matching:
 
-- Wildcard pattern
+- Wildcard patterns
 - Literal patterns
-- Variable pattern
+- Variable patterns
 - Array patterns
 - Constructor patterns
 - Record patterns
 - Named patterns
-- Guards
+
+Guards and pattern guards are also supported.
 
 The exhaustivity checker will introduce a `Partial` constraint for any pattern which is not exhaustive.
 By default, patterns must be exhaustive, since this `Partial` constraint will not be satisfied. The error can be silenced, however, by adding a local `Partial` constraint to your function.
@@ -125,16 +126,16 @@ Named Patterns
 Named patterns bring additional names into scope when using nested patterns. Any pattern can be named by using the ``@`` symbol:
 
 ```purescript
-f a@[_, _] = true
-f _ = false
+f a@[_, _] = a
+f _ = []
 ```
 
 Here, in the first pattern, any array with exactly two elements will be matched and bound to the variable `a`.
 
 Guards
 ------
 
-Guards are used to impose additional constraints inside a pattern using boolean-valued expressions, and are introduced with a pipe after the pattern::
+Guards are used to impose additional constraints inside a pattern using boolean-valued expressions, and are introduced with a pipe after the pattern:
 
 ```purescript
 evens :: List Int -> Int
@@ -149,3 +150,43 @@ When using patterns to define a function at the top level, guards appear after a
 greater x y | x > y = true
 greater _ _ = false
 ```
+
+To be considered exhaustive, guards must clearly include a case that is always true. Even though the following makes perfect sense, the compiler cannot determine that is is exhaustive:
+
+```purescript
+compare :: Int -> Int -> Ordering
+compare x y
+    | x > y  = GT
+    | x == y = EQ
+    | x < y  = LT
+```
+
+Either of these will work, since they clearly include a final case:
+
+```purescript
+compare x y
+    | x > y = GT
+    | x < y = LT
+    | otherwise = EQ
+
+compare x y | x > y = GT
+compare x y | x < y = LT
+compare _ _ = EQ
+```
+
+(The name `otherwise` is a synonym for `true` commonly used in guards.)
+
+Pattern Guards
+--------------
+
+Pattern guards extend guards with pattern matching, notated with a left arrow. A pattern guard will succeed only if the computation on the right side of the arrow matches the pattern on the left.
+
+For example, we can apply a function `fn` to an argument `x`, succeeding only if
+`fn` returns `Just y` for some `y`, binding `y` at the same time:
+
+```purescript
+bar x | Just y <- fn x = ... -- x and y are both in scope here
+```
+
+Pattern guards can be very useful for expressing certain types of control flow when
+using algebraic data types.

language/Records.md

@@ -24,9 +24,9 @@ Fields of records can be accessed using a dot, followed by the label of the fiel
 
 `{ ... }` is just syntactic sugar for the `Record` type constructor, so `{ language ::  String }` is the same as `Record ( language :: String )`.
 
-The Record type constructor is parameterized by a row of types. In kind notation, `Record` has kind `# * -> *`. That is, it takes a row of types to a type.
+The Record type constructor is parameterized by a row of types. In kind notation, `Record` has kind `# Type -> Type`. That is, it takes a row of types to a type.
 
-`( language :: String )` denotes a row of types (something of kind `# *`), so it can be passed to `Record` to construct a type, namely `Record ( language :: String )`.
+`( language :: String )` denotes a row of types (something of kind `# Type`), so it can be passed to `Record` to construct a type, namely `Record ( language :: String )`.
 
 ## Extending Records
 
@@ -42,7 +42,7 @@ that can then be extended like:
 type Language = Lang ( country :: String )
 ```
 
-The `Language` type synonym would then be equivalent to `{ language :: String, country :: String }`.
+The `Language` type synonym would then be equivalent to `{ language :: String, country :: String }`. Note that parentheses must be used for the extension, since `l` has to be a row kind not a record type.
 
 ## Wildcards
 

language/Syntax.md

@@ -234,20 +234,39 @@ This is equivalent to:
 \rec -> rec.propertyName
 ```
 
+These work with any number of levels:
+
+``` purescript
+_.nested.property.name
+```
+
 ### Record Updates
 
 Properties on records can be updated using the following syntax:
 
 ``` purescript
-rec { key1 = value1, ..., keyN = valueN }
+rec { key1 = value1, ..., keyN = valueN, nestedKey { subKey = value, ... } }
 ```
 
+Some or all of the keys may be updated at once, and records inside of records can also be updated.
+
 For example, the following function increments the `foo` property on its argument:
 
 ``` purescript
 \rec -> rec { foo = rec.foo + 1 }
 ```
 
+[Nested record updates](https://liamgoodacre.github.io/purescript/records/2017/01/29/nested-record-updates.html) look like this:
+
+``` purescript
+r = { val: -1
+    , level1: { val: -1
+              , level2: { val: -1 }
+              }
+    }
+r' = r { level1 { val = 1 } }
+```
+
 Wildcards can also be used in updates to produce a partially applied update:
 
 ``` purescript