Variants and the match construct — Coq 8.20.0 documentation

\[\begin{split}\newcommand{\as}{\kw{as}} \newcommand{\case}{\kw{case}} \newcommand{\cons}{\textsf{cons}} \newcommand{\consf}{\textsf{consf}} \newcommand{\emptyf}{\textsf{emptyf}} \newcommand{\End}{\kw{End}} \newcommand{\kwend}{\kw{end}} \newcommand{\even}{\textsf{even}} \newcommand{\evenO}{\textsf{even}_\textsf{O}} \newcommand{\evenS}{\textsf{even}_\textsf{S}} \newcommand{\Fix}{\kw{Fix}} \newcommand{\fix}{\kw{fix}} \newcommand{\for}{\textsf{for}} \newcommand{\forest}{\textsf{forest}} \newcommand{\Functor}{\kw{Functor}} \newcommand{\In}{\kw{in}} \newcommand{\ind}[3]{\kw{Ind}~[#1]\left(#2\mathrm{~:=~}#3\right)} \newcommand{\Indp}[4]{\kw{Ind}_{#4}[#1](#2:=#3)} \newcommand{\Indpstr}[5]{\kw{Ind}_{#4}[#1](#2:=#3)/{#5}} \newcommand{\injective}{\kw{injective}} \newcommand{\kw}[1]{\textsf{#1}} \newcommand{\length}{\textsf{length}} \newcommand{\letin}[3]{\kw{let}~#1:=#2~\kw{in}~#3} \newcommand{\List}{\textsf{list}} \newcommand{\lra}{\longrightarrow} \newcommand{\Match}{\kw{match}} \newcommand{\Mod}[3]{{\kw{Mod}}({#1}:{#2}\,\zeroone{:={#3}})} \newcommand{\ModImp}[3]{{\kw{Mod}}({#1}:{#2}:={#3})} \newcommand{\ModA}[2]{{\kw{ModA}}({#1}=={#2})} \newcommand{\ModS}[2]{{\kw{Mod}}({#1}:{#2})} \newcommand{\ModType}[2]{{\kw{ModType}}({#1}:={#2})} \newcommand{\mto}{.\;} \newcommand{\nat}{\textsf{nat}} \newcommand{\Nil}{\textsf{nil}} \newcommand{\nilhl}{\textsf{nil\_hl}} \newcommand{\nO}{\textsf{O}} \newcommand{\node}{\textsf{node}} \newcommand{\nS}{\textsf{S}} \newcommand{\odd}{\textsf{odd}} \newcommand{\oddS}{\textsf{odd}_\textsf{S}} \newcommand{\ovl}[1]{\overline{#1}} \newcommand{\Pair}{\textsf{pair}} \newcommand{\plus}{\mathsf{plus}} \newcommand{\SProp}{\textsf{SProp}} \newcommand{\Prop}{\textsf{Prop}} \newcommand{\return}{\kw{return}} \newcommand{\Set}{\textsf{Set}} \newcommand{\Sort}{\mathcal{S}} \newcommand{\Str}{\textsf{Stream}} \newcommand{\Struct}{\kw{Struct}} \newcommand{\subst}[3]{#1\{#2/#3\}} \newcommand{\tl}{\textsf{tl}} \newcommand{\tree}{\textsf{tree}} \newcommand{\trii}{\triangleright_\iota} \newcommand{\Type}{\textsf{Type}} \newcommand{\WEV}[3]{\mbox{$#1[] \vdash #2 \lra #3$}} \newcommand{\WEVT}[3]{\mbox{$#1[] \vdash #2 \lra$}\\ \mbox{$ #3$}} \newcommand{\WF}[2]{{\mathcal{W\!F}}(#1)[#2]} \newcommand{\WFE}[1]{\WF{E}{#1}} \newcommand{\WFT}[2]{#1[] \vdash {\mathcal{W\!F}}(#2)} \newcommand{\WFTWOLINES}[2]{{\mathcal{W\!F}}\begin{array}{l}(#1)\\\mbox{}[{#2}]\end{array}} \newcommand{\with}{\kw{with}} \newcommand{\WS}[3]{#1[] \vdash #2 <: #3} \newcommand{\WSE}[2]{\WS{E}{#1}{#2}} \newcommand{\WT}[4]{#1[#2] \vdash #3 : #4} \newcommand{\WTE}[3]{\WT{E}{#1}{#2}{#3}} \newcommand{\WTEG}[2]{\WTE{\Gamma}{#1}{#2}} \newcommand{\WTM}[3]{\WT{#1}{}{#2}{#3}} \newcommand{\zeroone}[1]{[{#1}]} \end{split}\]

# Variants and the `match` construct

## Variants

The `Variant` command allows defining types by listing the inhabitants of the type. Each inhabitant is specified by a constructor. For instance, Booleans have two constructors: `true` and `false`. Types can include enumerated types from programming languages, such as Booleans, characters or even the degenerate cases of the unit and empty types. Variant types more generally include enumerated types with arguments or even enumerated types with parametric arguments such as option types and sum types. It also includes predicates or type families defined by cases such as the Boolean reflection or equality predicates. Observing the form of the inhabitants of a variant type is done by case analysis using the `match` expression.

When a constructor of a type takes an argument of that same type, the type becomes recursive, in which case it can be either `Inductive` or `CoInductive`. The keyword `Variant` is reserved for non-recursive types. Natural numbers, lists or streams cannot be defined using `Variant`.

Command Variant ident_decl binder* | binder*? : type? := |? constructor+| decl_notations?

  Defines a variant type named `ident` (in `ident_decl`) with the given list of constructors. No induction scheme is generated for this variant, unless the `Nonrecursive Elimination Schemes` flag is on.

  `| binder*?`

    The `|` separates uniform and non uniform parameters. See `Uniform Inductive Parameters`.

  This command supports the `universes(polymorphic)`, `universes(template)`, `universes(cumulative)`, and `private(matching)` attributes.

  Error The natural th argument of ident must be ident in type.

Example

The Booleans, the unit type and the empty type are respectively defined by:

> Module FreshNameSpace.
>   Interactive Module FreshNameSpace started
> Variant bool : Set := true : bool | false : bool.
>   bool is defined
> Variant unit : Set := tt : unit.
>   unit is defined
> Variant Empty_set : Set :=.
>   Empty_set is defined

The option and sum types are defined by:

> Variant option (A : Type) : Type := None : option A | Some : A -> option A.
>   option is defined
> Variant sum (A B : Type) : Type := inl : A -> sum A B | inr : B -> sum A B.
>   sum is defined

Boolean reflection is a relation reflecting under the form of a Boolean value when a given proposition `P` holds. It can be defined as a two-constructor type family over `bool` parameterized by the proposition `P`:

Variant reflect (P : Prop) : bool -> Set := | ReflectT : P -> reflect P true | ReflectF : ~ P -> reflect P false.
  reflect is defined

End FreshNameSpace.
  Module FreshNameSpace is defined

Leibniz equality is another example of variant type.

Note

The standard library commonly uses `Inductive` in place of `Variant` even for non-recursive types in order to automatically derive the schemes `ident` `_rect`, `ident` `_ind`, `ident` `_rec` and `ident` `_sind`. (These schemes are also created for `Variant` if the `Nonrecursive Elimination Schemes` flag is set.)

### Private (matching) inductive types

Attribute private(matching)

  This attribute can be used to forbid the use of the `match` construct on objects of this inductive type outside of the module where it is defined. There is also a legacy syntax using the `Private` prefix (cf. `legacy_attr`).

  The main use case of private (matching) inductive types is to emulate quotient types / higher-order inductive types in projects such as the HoTT library.

  Reducing definitions from the inductive's module can expose `match` constructs to unification, which may result in invalid proof terms. Errors from such terms are delayed until proof completion (i.e. on the `Qed`). Use `Validate Proof` to identify which tactic produced the problematic term.

Example

Module Foo.
  Interactive Module Foo started
#[ private(matching) ] Inductive my_nat := my_O : my_nat | my_S : my_nat -> my_nat.
  my_nat is defined
Check (fun x : my_nat => match x with my_O => true | my_S _ => false end).
  fun x : my_nat => match x with | my_O => true | my_S _ => false end : my_nat -> bool
End Foo.
  Module Foo is defined
Import Foo.
Fail Check (fun x : my_nat => match x with my_O => true | my_S _ => false end).
  The command has indeed failed with message: case analysis on a private type.

## Definition by cases: match

Objects of inductive types can be destructured by a case-analysis construction called pattern matching expression. A pattern matching expression is used to analyze the structure of an inductive object and to apply specific treatments accordingly.

term_match`::=`match case_item+, return term100? with |? eqn*| end`` case_item`::=`term100 as name? in pattern?``eqn`::=`pattern+,+| => term`` pattern`::=`pattern10 : term`````|`pattern10`` pattern10`::=`pattern1 as name`````|`pattern1 pattern1*`````|`@ qualid pattern1*``pattern1`::=`pattern0 % scope_key`````|`pattern0 %_ scope_key`````|`pattern0`` pattern0`::=`qualid`````|`{| qualid := pattern* |}`````|`_`````|`( pattern+| )`````|`number`````|`string``

Note that the `pattern ::= pattern10 : term` production is not supported in `match` patterns. Trying to use it will give this error:

Error Casts are not supported in this pattern.

This paragraph describes the basic form of pattern matching. See Section Multiple and nested pattern matching and Chapter Extended pattern matching for the description of the general form. The basic form of pattern matching is characterized by a single `case_item` expression, an `eqn` restricted to a single `pattern` and `pattern` restricted to the form `qualid ident*`.

The expression `match term return term100? with patterni => termi+| end` denotes a pattern matching over the term `term` (expected to be of an inductive type \(I\)). The `termi` are the branches of the pattern matching expression. Each `patterni` has the form `qualid ident` where `qualid` must denote a constructor. There should be exactly one branch for every constructor of \(I\).

The `return term100` clause gives the type returned by the whole match expression. There are several cases. In the non-dependent case, all branches have the same type, and the `return term100` specifies that type. In this case, `return term100` can usually be omitted as it can be inferred from the type of the branches [1].

In the dependent case, there are three subcases. In the first subcase, the type in each branch may depend on the exact value being matched in the branch. In this case, the whole pattern matching itself depends on the term being matched. This dependency of the term being matched in the return type is expressed with an `ident` clause where `ident` is dependent in the return type. For instance, in the following example:

Inductive bool : Type := true : bool | false : bool.
  bool is defined bool_rect is defined bool_ind is defined bool_rec is defined bool_sind is defined
Inductive eq (A: Type) (x: A) : A -> Prop := eq_refl : eq A x x.
  eq is defined eq_rect is defined eq_ind is defined eq_rec is defined eq_sind is defined
Inductive or (A: Prop) (B: Prop) : Prop := | or_introl : A -> or A B | or_intror : B -> or A B.
  or is defined or_ind is defined or_sind is defined
Definition bool_case (b: bool) : or (eq bool b true) (eq bool b false) := match b as x return or (eq bool x true) (eq bool x false) with | true => or_introl (eq bool true true) (eq bool true false) (eq_refl bool true) | false => or_intror (eq bool false true) (eq bool false false) (eq_refl bool false) end.
  bool_case is defined

the branches have respective types "`or (eq bool true true) (eq bool true false)`" and "`or (eq bool false true) (eq bool false false)`" while the whole pattern matching expression has type "`or (eq bool b true) (eq bool b false)`", the identifier `b` being used to represent the dependency.

Note

When the term being matched is a variable, the `as` clause can be omitted and the term being matched can serve itself as binding name in the return type. For instance, the following alternative definition is accepted and has the same meaning as the previous one.

Reset bool_case.

Definition bool_case (b: bool) : or (eq bool b true) (eq bool b false) := match b return or (eq bool b true) (eq bool b false) with | true => or_introl (eq bool true true) (eq bool true false) (eq_refl bool true) | false => or_intror (eq bool false true) (eq bool false false) (eq_refl bool false) end.
  bool_case is defined

The second subcase is only relevant for indexed inductive types such as the equality predicate (see Section Equality), the order predicate on natural numbers or the type of lists of a given length (see Section Matching objects of dependent types). In this configuration, the type of each branch can depend on the type dependencies specific to the branch and the whole pattern matching expression has a type determined by the specific dependencies in the type of the term being matched. This dependency of the return type in the indices of the inductive type is expressed with a clause in the form `in qualid _+ pattern+`, where

- `qualid` is the inductive type of the term being matched;

- the holes `_` match the parameters of the inductive type: the return type is not dependent on them.

- each `pattern` matches the indices of the inductive type: the return type is dependent on them

- in the basic case which we describe below, each `pattern` is a name `ident`; see Patterns in in for the general case

For instance, in the following example:

Definition eq_sym (A: Type) (x y: A) (H: eq A x y) : eq A y x := match H in eq _ _ z return eq A z x with | eq_refl _ _ => eq_refl A x end.
  eq_sym is defined

the type of the branch is `eq A x x` because the third argument of `eq` is `x` in the type of the pattern `eq_refl`. On the contrary, the type of the whole pattern matching expression has type `eq A y x` because the third argument of eq is y in the type of H. This dependency of the case analysis in the third argument of `eq` is expressed by the identifier `z` in the return type.

Finally, the third subcase is a combination of the first and second subcase. In particular, it only applies to pattern matching on terms in a type with indices. For this third subcase, both the clauses `as` and `in` are available.

There are specific notations for case analysis on types with one or two constructors: `if … then … else …` and `let (…,…) := … in …` (see Sections Pattern-matching on boolean values: the if expression and Irrefutable patterns: the destructuring let variants).

[1]

Except if the inductive type is empty in which case there is no equation that can be used to infer the return type.

Other versions v: 8.20.0

Versions
  dev
  stable
  8.20
  8.19
  8.18
  8.17
  8.16
  8.15
  8.14
  8.13
  8.12
  8.11
  8.10
  8.9
  8.8
  8.7
  8.6
  8.5
  8.4
  8.3
  8.2
  8.1
  8.0

Downloads
  PDF