Merge pull request #436 from VictorCMiraldo/vcm/error-83865

Documenting two examples for `83865`; Adds `order` field to example headers

Author: BinderDavid

CONTRIBUTING.md

@@ -170,11 +170,16 @@ The fields in the metadata block should be:
 ### Example Descriptions
 
 Example descriptions are written in Markdown with Pandoc-style
-metadata, just like message descriptions. They have only the `title`
-field. All `.hs` files are shown in the list of files for the
+metadata, just like message descriptions. They have the obligatory `title`
+and optional `order` fields. All `.hs` files are shown in the list of files for the
 example. The `index.md` file should explain how the files illustrate
 the message.
 
+Examples are ordered according to their `order` field. Examples
+with no explicit `order` are shown last and examples with the same
+`order` will be shown in an unspecified order with respect to each other,
+but will appear before examples with a greater order.
+
 ## Reference: Technology choices
 
 The website generated by `message-index` uses a few JS components.

message-index/messages/GHC-83865/index.md

@@ -0,0 +1,15 @@
+---
+title: Type Mismatch
+summary: You provided a value of a given type, whereas GHC expected a different type.
+severity: error
+introduced: 9.6.1
+---
+
+GHC expected one type, but was given another. Unlike dynamically-typed programming languages,
+type signatures in Haskell are like a contract between the programmer and the compiler.
+In its simplest form, when you call a function `f` with type `a -> b`, with some argument `x`,
+the compiler will check whether `x` has type `a` and if that is not the case, it will trigger
+the type mismatch error. This case is illustrated by the `terms` example, below.
+
+Type mismatch errors are quite general, however, so you will still encounter them
+in many other situations.

message-index/messages/GHC-83865/terms/after/Terms.hs

@@ -0,0 +1,4 @@
+inc :: Int -> Int
+inc i = i + 1
+
+two = inc 1

message-index/messages/GHC-83865/terms/before/Terms.hs

@@ -0,0 +1,4 @@
+inc :: Int -> Int
+inc i = i + 1
+
+two = inc "x"

message-index/messages/GHC-83865/terms/index.md

@@ -0,0 +1,31 @@
+---
+title: Values of Different Types
+order: 0
+---
+
+Function `inc` has type `Int -> Int`, hence it expects an argument
+of type `Int`; yet, on the definition of `two` it was called with
+an argument of type `String`.
+
+If you ever need to know the type of something, you can ask for it in `ghci`
+with the command `:type` (or its shorthand `:t`):
+
+```
+ghci> :t "x"
+"x" :: String
+```
+
+## Error Message
+
+```
+Terms.hs:6:11: error: [GHC-83865]
+    • Couldn't match type ‘[Char]’ with ‘Int’
+      Expected: Int
+        Actual: String
+    • In the first argument of ‘inc’, namely ‘"x"’
+      In the expression: inc "x"
+      In an equation for ‘two’: two = inc "x"
+  |
+4 | two = inc "x"
+  |
+```

message-index/messages/GHC-83865/type-kind-mism/after/Type.hs

@@ -0,0 +1,3 @@
+isNothing :: Maybe a -> Bool
+isNothing Nothing = True
+isNothing _ = False

message-index/messages/GHC-83865/type-kind-mism/before/Type.hs

@@ -0,0 +1,4 @@
+isNothing :: Maybe -> Bool
+isNothing Nothing = True
+isNothing _ = False
+

message-index/messages/GHC-83865/type-kind-mism/index.md

@@ -0,0 +1,34 @@
+---
+title: Type expected, but kind received.
+order: 1
+---
+
+Forgetting the type parameter to `Maybe` is the culprit, but it is only caught in the
+context of the the arrow in the declaration of `isNothing`, which can be confusing.
+The arrow (`->`) in Haskell is a _type constructor_. It takes two types
+of *kind* `Type`, and returns a fresh type, also of kind `Type`. That is, for `x -> y`
+to make any sense, GHC needs `x` and `y` to be types of kind `Type`, which is not
+the case in this example: `Maybe` by itself has kind `Type -> Type`.
+
+If you ever need to know the kind of something, you can ask `ghci`
+with the `:kind` (or its shorthand `:k`), keeping in mind
+that `*` (pronounced "star") is a synonym for `Type`:
+
+```
+ghci> :k (->)
+(->) :: * -> * -> *
+ghci> :k Maybe
+Maybe :: * -> *
+```
+
+## Error Message
+
+```
+Type.hs:1:14: error: [GHC-83865]
+    • Expecting one more argument to ‘Maybe’
+      Expected a type, but ‘Maybe’ has kind ‘* -> *’
+    • In the type signature: isNothing :: Maybe -> Bool
+  |
+1 | isNothing :: Maybe -> Bool
+  |
+```

message-index/site.hs

@@ -1,6 +1,7 @@
 {-# LANGUAGE DataKinds #-}
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE TupleSections #-}
 {-# LANGUAGE TypeApplications #-}
 {-# LANGUAGE ViewPatterns #-}
 
@@ -9,8 +10,9 @@ import qualified Data.Aeson.KeyMap as KM
 import Data.Binary (Binary)
 import Data.Data (Typeable)
 import Data.Foldable (for_)
+import Data.Function (on)
 import Data.Functor ((<&>))
-import Data.List (find, isPrefixOf, lookup, nub, sort)
+import Data.List (find, isPrefixOf, lookup, nub, sort, sortBy)
 import Data.List.NonEmpty (NonEmpty (..))
 import qualified Data.List.NonEmpty as NE
 import qualified Data.Map.Strict as Map
@@ -193,6 +195,24 @@ messageTitleField = field "title" getTitle
 messageCtx :: Context String
 messageCtx = field "id" (pure . getId) <> indexlessUrlField "url"
 
+data ExampleOrder = InGroup Integer | Last
+  deriving (Eq, Show)
+
+instance Ord ExampleOrder where
+  compare (InGroup i) (InGroup j) = compare i j
+  compare (InGroup _) Last = LT
+  compare Last (InGroup _) = GT
+  compare Last Last = EQ
+
+getExampleOrder :: Identifier -> Compiler ExampleOrder
+getExampleOrder ident = do
+  metas <- getMetadata ident
+  let msgId = getIdentId ident
+  case KM.lookup "order" metas of
+    (Just (JSON.Number i)) -> pure $ InGroup (truncate i)
+    Just other -> fail $ "Not an integer: " ++ show other
+    Nothing -> pure Last
+
 getId :: Item a -> String
 getId item = fromMaybe "" $ getIdentId (itemIdentifier item)
 
@@ -208,7 +228,11 @@ getExamples = do
   code <- case splitDirectories $ toFilePath me of
     ["messages", code, "index.md"] -> pure code
     other -> fail $ "Not processing a message: " ++ show other
-  loadAll $ fromGlob ("messages/" <> code <> "/*/index.*") .&&. hasNoVersion
+  items <- loadAll $ fromGlob ("messages/" <> code <> "/*/index.*") .&&. hasNoVersion
+  sortByM (getExampleOrder . itemIdentifier) items
+  where
+    sortByM :: (Monad m, Ord b) => (a -> m b) -> [a] -> m [a]
+    sortByM f = fmap (map fst . sortBy (compare `on` snd)) . mapM (\x -> (x,) <$> f x)
 
 getExampleFiles :: Compiler [Item (FilePath, Maybe (Item String), Maybe (Item String))]
 getExampleFiles = do