The exhaustiveness checker currently chokes on pattern synonyms. They are marked as always fallible patterns which means that we must also always include a catch-all case in order to avoid a warning.

```
data A = A
pattern :: A
pattern P = A
foo :: A -> A
foo P = A
```

leads to the warning that pattern matches for `foo`

are non-exhaustive.

```
simpletest.hs:7:1: warning: [-Wincomplete-patterns]
Pattern match(es) are non-exhaustive
In an equation for ‘foo’: Patterns not matched: _
```

Inspecting the definition of `P`

we can see that the matches for `foo`

are indeed exhaustive as `A`

is a unary data type but the pattern match checker does not make use of this information.

And neither should it! Pattern synonyms are a means of *abstraction*, if the exhaustiveness checker could look through a definition then the implementation of `P`

would leak into error messages.
We want users to be able to replace bona-fide data constructors with pattern synonyms without consumers noticing.
To that end, we allow users to specify a complete set of pattern synonyms in order to sate the pattern match checker. If a complete pragma is not provided then we keep the same behaviour as in previous releases.

# Definitions

We introduce a new top-level pragma which we use to declare a complete set of conlikes.

A **conlike** is either a data constructor or a pattern synonym.

We say that a set of conlikes is a **complete** match when a function which is defined by matching on all of the conlikes is total.

# Syntax

A user declares a complete match using a `COMPLETE`

pragma. The definition consists of a list of conlikes.

`{-# COMPLETE con_1, ..., con_n #-}`

`COMPLETE`

pragmas can appear in any module in which `con_1,..., con_n`

are in scope. Specifically, they need not be in the defining module.

Optionally a user may also specify the type constructor of the patterns.

`{-# COMPLETE con_1, ..., con_n :: T #-}`

# Semantics

`COMPLETE`

pragmas are only used in the pattern match checker.

For each `COMPLETE`

pragma we identify the type of the set of conlikes.

For a `COMPLETE`

pragma of type `T`

with conlikes `c_1, ..., c_n`

. If in a pattern match of type `T`

we match on `c_1, ..., c_n`

then
we assume that the match is covering. This means that the pattern match checker will no longer emit a warning about incomplete pattern matches.

`COMPLETE`

pragmas are always imported and exported from modules.

`COMPLETE`

pragmas only specify that a certain match is covering, because of this, we do not warn about redundant or inaccessible matches when the pattern match checking result arises
from checking against a `COMPLETE`

pragma.

Different `COMPLETE`

pragmas can mention overlapping sets of conlikes. If there is more than one relevant `COMPLETE`

pragma then each is tried, if none of them result in a covering match then an error is reported
as described in the "Error Reporting" section.

There are no checks to ensure that the set of patterns is actually complete or covering in any way. It is up to the user to get it right.

`COMPLETE`

pragmas are a new source of orphan modules. For example,

```
module M where
import N( pattern P, pattern Q )
{-# COMPLETE P, Q #-}
```

where neither `P`

nor `Q`

is defined in M. Then every module that is
transitively "above" M would need to read `M.hi`

just in case its
`COMPLETE`

pragmas was relevant.

## Typing

We refer to the leftmost type in the result type of a conlike as the rtc.

For example, the rtc of `P :: a -> b -> T a b`

is `T`

, the rtc of `P :: T`

is `T`

and the rtc of `P :: ... -> f Int`

is a type variable `f`

.

We distinguish between polymorphic and monomorphic conlikes.

- A monomorphic conlike is when the rtc is a type constructor.
- A polymorphic conlike is when the rtc is not a type constructor.

By the end of type checking, we must identify a type constructor to identify with each set of patterns.

In the case where there is at least one monomorphic pattern `P`

, the rtc of `P`

is the type constructor for the whole set of patterns.
Each monomorphic conlike must have the same rtc as `P`

.
There is no requirement for polymorphic conlikes.
In addition, if the user specifies the type signature then the rtc of `P`

must be the same as the type constructor specified by the type signature.

In the case where all the patterns are polymorphic, a user must provide a type signature but we accept the definition regardless of the type signature they provide. The type constructor for the whole set of patterns is the type constructor as specified by the user. If the user does not provide a type signature then the definition is rejected as ambiguous.

This design is a consequence of the design of the pattern match checker. Complete sets of patterns must be identified relative to a type. This is a sanity check as users would never be able to match on all constructors if the set of patterns is inconsistent in this manner.

### Examples of Typing

```
pattern P :: ()
pattern P = ()
{-# COMPLETE P #-}
```

Accepted, the type of the match is `()`

as the rtc of `P`

is `()`

.

```
pattern P :: ()
pattern P = ()
{-# COMPLETE P :: () #-}
```

Accepted, the type of the match is `()`

as the rtc of `P`

is `()`

and this is the same as the user specified type which is `()`

.

```
pattern P :: ()
pattern P = ()
{-# COMPLETE P :: Int #-}
```

Rejected as the user specified type signature is not the same as the rtc of `P`

. (`Int /= ()`

)

```
pattern P :: ()
pattern P = ()
pattern Q :: Maybe a
pattern Q = Nothing
{-# COMPLETE P, Q #-}
```

Rejected: the rtc of `P`

and `Q`

is different.

```
pattern P :: ()
pattern P = ()
pattern Q :: ()
pattern Q = ()
{-# COMPLETE P, Q #-}
```

Accepted, the type of the whole set is `()`

as this is the rtc of both `P`

and `Q`

.

```
class C f where
match :: f a -> ()
pattern P :: C f => f a
pattern P <- (match -> ())
{-# COMPLETE P #-}
```

Rejected. All the conlikes are polymorphic but no type signature is provided

```
class C f where
match :: f a -> ()
pattern P :: C f => f a
pattern P <- (match -> ())
{-# COMPLETE P :: () #-}
```

Accepted. All the conlikes are polymorphic but a type signature is provided.

```
class C f where
match :: f a -> ()
pattern P :: C f => f a
pattern P <- (match -> ())
pattern Q :: ()
pattern Q = ()
{-# COMPLETE P, Q #-}
```

Accepted. There is one polymorphic conlike `P`

but there is also a monomorphic conlike `Q`

which fixes the type of the whole set. Therefore the type of the whole match is `()`

.

```
pattern P :: [Int]
pattern P = [5]
pattern Q :: [Char]
pattern Q = ['a']
{-# COMPLETE P, Q #-}
```

Accepted. The rtc of `P`

and `Q`

is `[]`

. This is despite the fact that `P`

and `Q`

could never be used in the same pattern match. The check is there as a convenience to the user.

# Examples

The following examples should emit no warnings.

```
pattern P :: A
pattern P = A
{-# COMPLETE P #-}
foo :: A -> A
foo P = A
```

```
pattern N :: Maybe a
pattern N = Nothing
{-# COMPLETE N, Just #-}
qux :: Maybe a -> Bool
qux N = False
qux (Just x) = True
```

## Error Messages

When the pattern match checker requests a set of constructors for a type constructor `T`

, we now return a list of sets which include the normal data constructor set and also any `COMPLETE`

pragmas of type `T`

.
We then try each of these sets, not warning if any of them are a perfect match. In the case the match isn't perfect, we select one of the branches of the search depending on how good the result is.

The results are prioritised in this order.

- Fewest uncovered clauses
- Fewest redundant clauses
- Fewest inaccessible clauses
- Whether the match comes from a
`COMPLETE`

pragma or the built-in set of data constructors for a type constructor.

It may be desirable to produce a summary of the results in a more intelligent way; #13363 (closed) showed that the current state of affairs is broken. Exploration of this is left open for further discussion.