Move error code pages over from wiki

docs/errors/Error-Code-AdditionalProperty.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ArgListLengthsDiffer.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-CannotApplyFunction.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-CannotDerive.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-CannotFindDerivingType.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-CannotGetFileInfo.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-CannotReadFile.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-CannotWriteFile.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ClassConflictsWithCtor.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ClassConflictsWithType.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ClassOperator.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ConflictingCtorDecls.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ConflictingImport.md

@@ -0,0 +1,41 @@
+This error can occur when you attempt to define a value with the same name as one which has already been imported.
+
+For example, `Prelude` exports a function called `id`. If I attempt to define my own `id` as well, like this:
+
+```purescript
+module ConflictingImport where
+
+id :: Number
+id = 1
+```
+
+Then this will fail with:
+
+```
+>> Error in module ConflictingImport:
+>> Declaration id conflicts with import ConflictingImport
+```
+
+One potential solution is to hide the problematic imports with a `hiding` list:
+
+```purescript
+module NoConflictingImport where
+
+import Prelude hiding (id)
+
+id :: Number
+id = 1
+```
+
+Alternatively, we can import one of the two modules which define `id` as "qualified":
+
+```purescript
+module NoConflictingImport where
+
+import qualified Prelude as P
+
+id :: Number
+id = 1
+```
+
+In the context of PSCI, a function named "main" is pre-defined by PSCI. Therefore, importing a module which also defines a function named "main" will cause PSCI to emit this ConflictingImport error. This error can be resolved by importing the external module using the `qualified` or `hiding` keywords, as shown above.

docs/errors/Error-Code-ConflictingImports.md

@@ -0,0 +1 @@
+see https://github.com/purescript/purescript/wiki/Error-Code-ConflictingImport, perhaps?

docs/errors/Error-Code-ConflictingTypeDecls.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ConstrainedTypeUnified.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-CtorConflictsWithClass.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-CycleInDeclaration.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-CycleInModules.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-CycleInTypeSynonym.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DeprecatedClassExport.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DeprecatedClassImport.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DeprecatedOperatorDecl.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DeprecatedQualifiedSyntax.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DuplicateClassExport.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DuplicateExportRef.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DuplicateImport.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DuplicateImportRef.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DuplicateLabel.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DuplicateModuleName.md

@@ -0,0 +1,6 @@
+Generally if this happens it is because you are importing the same module twice. If you get this when opening `psci`, check your `.psci` file and look for duplicate imports. In particular, you might find something like
+
+    :m src/Data/Moment/Simple.purs
+    ...
+    :l src/Data/Moment/Simple.purs
+

docs/errors/Error-Code-DuplicateSelectiveImport.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DuplicateTypeArgument.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DuplicateValueDeclaration.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-DuplicateValueExport.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ErrorParsingFFIModule.md

@@ -0,0 +1,3 @@
+You have a bad FFI file; have a look at how to define them:
+http://www.purescript.org/learn/ffi/\#foreign-modules
+

docs/errors/Error-Code-ErrorParsingModule.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ErrorUnifyingTypes.md

@@ -0,0 +1,29 @@
+This error occurs when the type checker is unable to deduce that two types are 'the same'.
+
+For example, take this expression:
+
+```purescript
+[] == [unit]
+```
+
+`[]` has type `forall a. [a]`, but `[unit]` has type `[Unit]`. These types are not the same. But the type checker is able to determine that the type `Unit` may be chosen for the type variable `a`, so the types do become the same. We say that the type checker successfully unifies `forall a. [a]` with `[Unit]` in this case.
+
+Another example:
+
+```purescript
+f :: Number -> Number
+f x = x + 1
+g :: Boolean -> Boolean
+g x = x || true
+
+h = g <<< f
+```
+
+The type of `(<<<)` (that is, function composition) is `forall a b c. (b -> c) -> (a -> b) -> (a -> c)`. For the right hand side of `h` to type-check, we need to find types `a`, `b`, and `c` such that the types match up. That is, we need to find a choice of `a`, `b`, and `c` such that:
+
+* `b = Boolean` (from the argument type of `g`)
+* `c = Boolean` (from the return type of `g`)
+* `a = Number` (from the argument type of `f`)
+* `b = Number` (from the return type of `f`).
+
+`b` can not be `Boolean` and `Number` at the same time, so this system of equations is not satisfiable, and the type checker rejects the program.

docs/errors/Error-Code-EscapedSkolem.md

@@ -0,0 +1,19 @@
+"Better go catch it then." - Unhelpful developer.
+
+Skolem constants are types which only unify with themselves, and a limited range of unification variables. They are used to check polymorphic types, usually when using Rank N Types.
+
+We say that a skolem _escapes its scope_ when an attempt is made to unify it with a unification variable which was generated outside the scope in which the skolem was generated.
+
+Consider for example, this function:
+
+```purescript
+test = do
+  r <- runST (newSTRef 0)
+  return 0
+```
+
+Here the type of `runST` causes us to check `newSTRef 0` against a polymorphic type, unifying the type of `r` with a skolem constant. However, the type of `r` is fresh, generated outside the scope of `newSTRef 0`, so we see an `EscapedSkolem` error. This is good, because we don't want the reference to leak outside of `runST`.
+
+### `$` and `runST`
+
+One common pitfall is to use the `runST` or `runPure` functions with the `$` operator. This will often lead to the `EscapedSkolem` error due to instantiation of type variables. Avoid this by using parentheses instead of `$`.

docs/errors/Error-Code-ExpectedType.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ExprDoesNotHaveType.md

@@ -0,0 +1,9 @@
+This error occurs when the type checker thinks an expression needs to have a certain type to type-check, but it has a different type.
+
+For example:
+
+```purescript
+x = true <> "hello"
+```
+
+The type of `(<>)` is `forall a. (Semigroup a) => a -> a -> a`, which means that in order to type-check, both of its arguments must have the same type. However, the type of `true` is `Boolean`, and the type of `"hello"` is `String`. These are different types, so the type checker rejects this program.

docs/errors/Error-Code-ExtraneousClassMember.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ImplicitImport.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-ImportHidingModule.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-IncompleteExhaustivityCheck.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-IncorrectConstructorArity.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-InfiniteKind.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-InfiniteType.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-IntOutOfRange.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-InvalidDoBind.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-InvalidDoLet.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-InvalidInstanceHead.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-InvalidNewtype.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-KindsDoNotUnify.md

@@ -0,0 +1,34 @@
+# Cannot unify kind * with kind # *
+This can happen when a function is declared without kind `*`, like a function that attempts to return a row:
+
+```purs
+onClick :: forall a. String -> (click :: String | a)
+onClick s = {click: s}
+```
+
+The error message reads along the lines of:
+```purs
+  Prim.String -> (click :: Prim.String | a)
+
+  Cannot unify kind
+    *
+  with kind
+    # *
+```
+
+**Prime suspect:** You are missing an `->` in your type signature.
+
+
+# Cannot unify kind * with kind * -> *
+This error occurs when you try adding a type class instance with a superfluous type parameter, e.g. (from the Purescript by Example book):
+```purs
+data NonEmpty a = NonEmpty a [a]
+
+instance functorNonEmpty :: Functor (NonEmpty a) where
+  (<$>) f (NonEmpty x xs) = NonEmpty (f x) []
+```
+The correct version is (just use `Functor NonEmpty` instead of `Functor (NonEmpty a)`):
+```purs
+instance functorNonEmpty :: Functor NonEmpty where
+  (<$>) f (NonEmpty x xs) = NonEmpty (f x) []
+```

docs/errors/Error-Code-MisleadingEmptyTypeImport.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-MissingClassMember.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-MissingFFIModule.md

@@ -0,0 +1,8 @@
+This error means that a foreign module could not be found. Make sure you have specified the required foreign files (`--ffi`) correctly.
+
+For example, say `psc` can't find the Prelude module (in versions 0.7.0 and later) but you have already installed it with `bower install purescript-prelude`. Then you could call `psc` with something like
+
+    $(npm bin)/psc --ffi 'bower_components/purescript-*/src/**/*.js' \
+      'bower_components/purescript-*/src/**/*.purs' mymodule.purs
+
+in order to let `psc` find the installed module's `.js` files.

docs/errors/Error-Code-MissingTypeDeclaration.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-MultipleFFIModules.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-MultipleFixities.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-NameIsUndefined.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-NoInstanceFound.md

@@ -0,0 +1,19 @@
+This error occurs when you try to use a function which has a type class constraint with a type (or types) that are not instances of the relevant type class.
+
+Example:
+
+```
+> data Foo = Foo
+> show Foo
+No instance found for Show Foo
+```
+
+Here, we use `show`, which is a member of the `Show` type class. Its type is `show :: forall a. (Show a) => a -> String`, which means that `show` takes a value of some type `a` and returns a `String`, with the constraint that `a` must have a `Show` instance.
+
+A possible fix is to add an instance for the relevant type. Following from the earlier example:
+
+```
+> instance showFoo :: Show Foo where show Foo = "Foo"
+> show Foo
+"Foo"
+```

docs/errors/Error-Code-NotExhaustivePattern.md

@@ -0,0 +1,59 @@
+This error occurs when a pattern matching definition has **non-exhaustive** patterns.
+
+As an example of this situation, consider the following definition:
+
+```haskell
+f :: Number -> Number
+f 0 = 0
+```
+
+This is clearly not exhaustive, as it fails to cover all the cases for its argument type: if we apply `f` to a value it cannot match (for example `1`) we will get an error at runtime:
+
+```
+> f 1
+
+Failed pattern match
+```
+
+Such functions are called *partial*, because they are not defined for all inputs: otherwise they are called *total*.
+
+Another example, `Data.Either.Unsafe` exports a function called `fromLeft`:
+
+```haskell
+fromLeft :: forall a b. Either a b -> a
+fromLeft (Left a) = a
+```
+
+The exhaustivity checker will throw the following warning:
+
+```
+Warning in module Data.Either.Unsafe:
+  Warning in value declaration fromLeft:
+  Warning at /home/travis/build/purescript/purescript/core-tests/bower_components/purescript-either/src/Data/Either/Unsafe.purs line 9, column 1 - line 10, column 1:
+    Pattern could not be determined to cover all cases.
+    The definition has the following uncovered cases:
+
+      (Data.Either.Right _)
+```
+
+The solution is to make your functions total in some way. We can use the type `Maybe a` to return `Nothing` in case of a missing case:
+
+```haskell
+f_total :: Number -> Maybe Number
+f_total 0 = Just 0
+f_total _ = Nothing
+```
+
+The compiler will not complain to this new definition for `f`.
+
+Up to now, we support exhaustivity checking for Data Constructors, Objects and Literals. If you are keen on using guards, you have to add an `otherwise` or `true` guard case to ensure exhaustivity.
+
+An example with guards:
+
+```haskell
+data Nat = Zero | Succ Nat
+
+isZero :: Nat -> Boolean
+isZero x | x == Zero = true
+         | otherwise = false
+```

docs/errors/Error-Code-OrphanFixityDeclaration.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-OrphanInstance.md

@@ -0,0 +1,28 @@
+This error occurs when an instance is declared outside of the module that declares the class it is for, and also none of the instance's types are declared in the same module.
+
+For example:
+
+``` purescript
+module A where
+
+  class SomeClass a where
+    someAction :: a -> a
+
+module B where
+
+  data SomeData = SomeData
+
+module C where
+
+  import A
+  import B
+
+  instance someInstance :: SomeClass SomeData where
+    someAction d = d
+```
+
+`someInstance` is an orphan here as it is defined in a module separate from both `SomeData` and `SomeClass`.
+
+In a case where a class has multiple type variables (`class SomeClass a b c ...`) and an instance is being declared in a different module, the instance only needs to provide one type from the current module for the instance to not be considered an orphan.
+
+Orphan instances are disallowed as they can cause conflicts in instance resolution in unrelated parts of the codebase, and can result in situations where you need odd imports like `import SomeModule ()` to just bring the instances into scope - with this restriction, empty-importing a module is never necessary.

docs/errors/Error-Code-OrphanTypeDeclaration.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-OverlappingArgNames.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-OverlappingInstances.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.

docs/errors/Error-Code-OverlappingNamesInLet.md

@@ -0,0 +1 @@
+Please consider sending a pull request to document this error.